DQL Reference Manual 6.5

EMC® Documentum®
Content Server
Version 6.5
DQL Reference Manual

P/N 300007200–A01
EMC Corporation
Corporate Headquarters:
Hopkinton, MA 01748‑9103
1‑508‑435‑1000
www.EMC.com
Copyright © 1992 ‑ 2008 EMC Corporation. All rights reserved.
Published July 2008
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS
OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY
DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
For the most up‑to‑date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.
All other trademarks used herein are the property of their respective owners.
Table of Contents
Preface .......................................................................................................................... 11
Chapter 1 DQL Language Elements ....................................................................... 13
Literals ...................................................................................................... 13
Integer literals ........................................................................................ 13
Floating point literals .............................................................................. 14
Character string literals ........................................................................... 15
ID literals ............................................................................................... 15
Date literals ............................................................................................ 15
Default formats .................................................................................. 16
Short date formats .......................................................................... 16
ANSI format .................................................................................. 17
Other character string formats ......................................................... 17
Date literal keywords .......................................................................... 18
Date output formats............................................................................ 18
Date storage and handling .................................................................. 19
Special keywords ........................................................................................ 19
Functions ................................................................................................... 20
Scalar functions ...................................................................................... 21
UPPER ............................................................................................... 21
LOWER ............................................................................................ 21
SUBSTR ............................................................................................. 22
Aggregate functions ............................................................................... 23
COUNT ............................................................................................ 23
MIN .................................................................................................. 23
MAX.................................................................................................. 24
AVG ................................................................................................. 24
SUM ................................................................................................. 25
Date functions ........................................................................................ 25
DATEDIFF ........................................................................................ 25
DATEADD ......................................................................................... 26
DATEFLOOR ..................................................................................... 27
DATETOSTRING ............................................................................... 27
The ID function ...................................................................................... 28
The MFILE_URL function ....................................................................... 28
Examples ........................................................................................... 29
Predicates .................................................................................................. 30
Arithmetic operators ............................................................................... 30
Comparison operators ............................................................................ 31
Column and property predicates ............................................................. 31
Predicates for columns and single‑valued properties ............................. 31
Predicates for repeating properties ...................................................... 32
Pattern matching with LIKE ................................................................ 35
The percent sign ............................................................................. 35
The underbar ................................................................................. 36
Matching cases ............................................................................... 36
The ESCAPE character .................................................................... 36
EMC Documentum Content Server Version 6.5 DQL Reference Manual 3

Table of Contents
SysObject predicates ............................................................................... 37

The TYPE predicate ............................................................................ 37
The FOLDER predicate ....................................................................... 38
The CABINET predicate...................................................................... 39
Logical operators ........................................................................................ 39
AND and OR ......................................................................................... 40
NOT ...................................................................................................... 40
Order of precedence ............................................................................... 40
DQL reserved words................................................................................... 42
Chapter 2 DQL Statements .................................................................................... 43

Chapter 3 Administration Methods ...................................................................... 187
Invoking administration methods .............................................................. 187
Scope of the administration methods ..................................................... 188
Administration method operations ............................................................ 188
Chapter 4 Using DQL ........................................................................................... 377

Introducing DQL ...................................................................................... 377
Quoting object type and property names .................................................... 379
NULLs, default values, and DQL ............................................................... 380
Testing for default and NULL values ..................................................... 380
Default values and aggregate functions .................................................. 381
Sorting and nulls .................................................................................. 382
Repeating properties in queries ................................................................. 382
Modifying repeating attributes .............................................................. 383
Adding new values ........................................................................... 383
Inserting values ............................................................................ 383
Appending values ........................................................................ 384
Updating values ............................................................................... 385
Deleting values ................................................................................. 385
Forcing index correspondence in query results ....................................... 385
Performance note for Sybase or MS SQL Server users .............................. 386
Querying virtual documents ..................................................................... 387
Full‑text searching and virtual documents .................................................. 388
Querying registered tables ........................................................................ 388
Referencing registered tables in queries.................................................. 389
Security controls ................................................................................... 389
Default object‑level permissions and table permits .............................. 390
Caching queries ........................................................................................ 390
Privileges, permissions, and queries........................................................... 390
Appendix A Using DQL Hints .................................................................................. 393

General guidelines for all .......................................................................... 393
SQL_DEF_RESULT_SET N ........................................................................ 394
FORCE_ORDER ....................................................................................... 395
RETURN_TOP N ...................................................................................... 396
Database‑specific implementations ........................................................ 396
SQL Server ....................................................................................... 396
Subqueries and the hint ................................................................ 397
DB2 ................................................................................................. 397
Oracle and Sybase ............................................................................ 397
4 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Table of Contents
Effects of a SEARCH clause ................................................................... 397

Recommended use ............................................................................... 398
OPTIMIZE_TOP N ................................................................................... 398
FETCH_ALL_RESULTS N......................................................................... 399
SQL Server, the hint, and subqueries ..................................................... 399
OPTIMIZATION_LEVEL level_1 level_2 .................................................... 399
UNCOMMITTED_READ ......................................................................... 400
IN and EXISTS ......................................................................................... 400
ROW_BASED ........................................................................................... 401
Effects on returned results ..................................................................... 401
Effects on query syntax rules ................................................................. 402
FTDQL and NOFTDQL............................................................................. 403
TRY_FTDQL_FIRST .................................................................................. 403
FT_CONTAIN_FRAGMENT ..................................................................... 403
GROUP_LIST_LIMIT N ............................................................................ 404
HIDE_SHARED_PARENT ........................................................................ 404
Including multiple hints limiting rows returned ......................................... 405
Passthrough hints ..................................................................................... 405
Syntax ................................................................................................. 405
Error handling and debugging .............................................................. 406
Appendix B Implementing Java Evaluation of Docbasic Expressions .................... 407

Docbasic expression handling by Content Server ....................................... 407
How DFC Version 6 and later handles the expressions ................................ 408
Migrating the expressions for pre‑6 clients ................................................. 408
Repository storage of migrated expressions ............................................ 409
Migrating Docbasic expressions to Java .................................................. 410
Disabling or re‑enabling Java evaluation .................................................... 413
Docbasic expression components support .................................................. 413
Operators ............................................................................................. 414
Supported functions for Java evaluation ................................................. 415
Unsupported functions for Java evaluation............................................. 419
Supported constants ............................................................................. 421
Unsupported constants ........................................................................ 421
Implicit objects ..................................................................................... 422
Appendix C DQL Quick Reference .......................................................................... 423

The DQL statements ................................................................................. 423
Execute ................................................................................................ 426
DQL reserved words ................................................................................ 431
Appendix D Document Query Language Examples ................................................ 437

Basic examples ......................................................................................... 437
The simplest format .............................................................................. 437
Using the WHERE clause ...................................................................... 438
Searching repeating properties in a WHERE Clause ............................ 438
Using aggregate functions ..................................................................... 439
Using the GROUP BY clause ............................................................. 439
Using the HAVING clause................................................................. 440
The ORDER BY clause .......................................................................... 440
Using the asterisk (*) in queries ............................................................. 440

Table of Contents
Searching cabinets and folders .................................................................. 441

Querying registered tables ........................................................................ 442
Querying virtual documents ..................................................................... 442
Determining the components ................................................................ 443

Table of Contents
List of Figures
Figure 1. Sample virtual document ............................................................................. 145

Figure 2. Repository storage of Docbasic expressions for object types ............................. 408
Figure 3. Repository storage of manually migrated Docbasic expressions ....................... 410
Figure 4. Virtual document model ............................................................................... 443

Table of Contents
List of Tables
Table 1. Valid ranges for floating point literals .............................................................. 14

Table 2. Default character string formats for dates ......................................................... 16
Table 3. Arithmetic operators ....................................................................................... 30
Table 4. Valid comparison operators for DQL statements ............................................... 31
Table 5. Predicates for columns and single‑valued properties ......................................... 31
Table 6. Predicates for repeating properties .................................................................. 33
Table 7. ALTER GROUP argument descriptions ............................................................ 45
Table 8. ALTER ASPECT argument descriptions ........................................................... 47
Table 9. Syntax variations for full‑text‑indexing of aspect properties .............................. 50
Table 10. ALTER TYPE argument descriptions ............................................................... 51
Table 11. Alter Type operations ..................................................................................... 54
Table 12. CHANGE...OBJECT argument descriptions...................................................... 71
Table 13. CREATE GROUP argument descriptions ......................................................... 76
Table 14. CREATE...OBJECT argument descriptions ........................................................ 79
Table 15. CREATE TYPE argument descriptions ............................................................. 84
Table 16. DB2 tablespace page sizes and associated maximum row lengths ...................... 87
Table 17. DELETE argument descriptions ..................................................................... 101
Table 18. DELETE...OBJECT argument descriptions ...................................................... 103
Table 19. DROP GROUP syntax description ................................................................. 107
Table 20. DROP TYPE argument descriptions ............................................................... 109
Table 21. EXECUTE argument descriptions .................................................................. 111
Table 22. Administration methods by category for the EXECUTE statement ................... 112
Table 23. GRANT argument descriptions ..................................................................... 118
Table 24. INSERT argument descriptions ..................................................................... 120
Table 25. REGISTER argument descriptions ................................................................. 123
Table 26. REVOKE argument descriptions .................................................................... 128
Table 27. SELECT argument descriptions ..................................................................... 131
Table 28. DQL standard hints ...................................................................................... 168
Table 29. UNREGISTER argument descriptions ............................................................ 173
Table 30. UPDATE argument descriptions .................................................................... 175
Table 31. UPDATE...OBJECT argument descriptions ..................................................... 178
Table 32. Administration methods by category ............................................................. 188
Table 33. BATCH_PROMOTE arguments ..................................................................... 194
Table 34. CHECK_CACHE_CONFIG arguments .......................................................... 198
Table 35. Properties in the CHECK_CACHE_CONFIG result object ............................... 199
Table 36. CHECK_RETENTION_EXPIRED arguments .................................................. 201
Table 37. CHECK_SECURITY arguments ..................................................................... 205

Table of Contents
Table 38. CLEAN_DELETED_OBJECTS arguments ...................................................... 208

Table 39. DB_STATS arguments ................................................................................... 212
Table 40. Query result object properties for DB_STATS administration method ............... 212
Table 41. DELETE_REPLICA arguments ...................................................................... 214
Table 42. DO_METHOD arguments ............................................................................. 218
Table 43. Properties of the query result object returned by DO_METHOD ...................... 221
Table 44. DROP_INDEX arguments ............................................................................. 227
Table 45. ESTIMATE_SEARCH arguments ................................................................... 229
Table 46. EXEC_SQL arguments .................................................................................. 232
Table 47. EXPORT_TICKET_KEY arguments ............................................................... 234
Table 48. GENERATE_PARTITION_SCHEME_SQL arguments ..................................... 239
Table 49. GET_FILE_URL arguments ........................................................................... 245
Table 50. GET_INBOX arguments ................................................................................ 247
Table 51. SysObject‑related property names for GET_INBOX query result
objects ..................................................................................................... 248
Table 52. GET_PATH arguments.................................................................................. 253
Table 53. HTTP_POST arguments ................................................................................ 257
Table 54. Query result object properties for HTTP_POST............................................... 258
Table 55. IMPORT_REPLICA arguments...................................................................... 262
Table 56. IMPORT_TICKET_KEY arguments ................................................................ 264
Table 57. LIST_RESOURCES arguments ....................................................................... 268
Table 58. Collection properties for LIST_RESOURCES .................................................. 268
Table 59. Collection properties for LIST_RESOURCES .................................................. 270
Table 60. LIST_SESSIONS arguments ........................................................................... 273
Table 61. Complete information returned by LIST_SESSIONS (BRIEF_INFO=F).............. 273
Table 62. Brief information returned by LIST_SESSIONS (BRIEF_INFO=T) ..................... 275
Table 63. Query result object properties for LIST_TARGETS .......................................... 278
Table 64. LOG_OFF arguments .................................................................................... 282
Table 65. MAKE_INDEX arguments ............................................................................ 284
Table 66. MARK_FOR_RETRY arguments .................................................................... 290
Table 67. MIGRATE_CONTENT arguments ................................................................. 292
Table 68. MIGRATE_TO_LITE arguments .................................................................... 304
Table 69. MODIFY_TRACE arguments ........................................................................ 312
Table 70. MOVE_INDEX arguments ............................................................................ 314
Table 71. PING arguments .......................................................................................... 316
Table 72. PURGE_AUDIT arguments ........................................................................... 318
Table 73. PUSH_CONTENT_ATTRS arguments ........................................................... 328
Table 74. RECOVER_AUTO_TASKS arguments ........................................................... 331
Table 75. REGISTER_ASSET arguments ....................................................................... 333
Table 76. Queue item property values set by REGISTER_ASSET ................................... 334
Table 77. REGISTER_ASSET arguments ....................................................................... 335
Table 78. REORGANZE_TABLE arguments ................................................................. 337
Table 79. REPLICATE arguments ................................................................................. 340

Table of Contents
Table 80. RESTORE_CONTENT arguments.................................................................. 345

Table 81. ROLES_FOR_USER arguments...................................................................... 347
Table 82. SET_APIDEADLOCK arguments .................................................................. 349
Table 83. Valid operation names for SET_APIDEADLOCK ............................................ 350
Table 84. SET_CONTENT_ATTRS arguments ............................................................... 352
Table 85. Example settings for content metadata properties in content objects................. 355
Table 86. SET_OPTIONS arguments ............................................................................ 357
Table 87. Trace options for SET_OPTIONS ................................................................... 358
Table 88. SET_STORAGE_STATE arguments ................................................................ 361
Table 89. TRANSCODE_CONTENT arguments............................................................ 365
Table 90. Queue item properties set by TRANSCODE_CONTENT ................................ 367
Table 91. UPDATE_STATISTICS arguments ................................................................. 369
Table 92. WEBCACHE_PUBLISH arguments ............................................................... 372
Table 93. Valid arguments for ARGUMENTS ............................................................... 372
Table 94. DQL basic query statements .......................................................................... 378
Table 95. Default property values by datatype .............................................................. 380
Table 96. Predicates that test for NULL and default values ............................................ 381
Table 97. Comparison of logical reads with and without default result sets..................... 394
Table 98. Example of object‑based query results............................................................ 402
Table 99. Example of row‑based query results .............................................................. 402
Table 100. Arguments for the Docbasic expression migration methods ............................ 411
Table 101. dmc_SetJavaExprEnabled arguments ............................................................. 413
Table 102. Docbasic operators supported by Java evaluation ........................................... 414
Table 103. Docbasic functions supported for Java evaluation ........................................... 415
Table 104. Docbasic functions not supported for Java evaluation ..................................... 419
Table 105. Docbasic constants supported for Java evaluation ........................................... 421
Table 106. Constants not supported for Java evaluation .................................................. 422
Table 107. Summary of FTDQL query rules .................................................................... 428
Table 108. DQL reserved words..................................................................................... 431

Preface
This manual is the reference manual for Documentum’s Document Query Language, supported by
Content Server. It is a companion to Documentum Object Reference Manual, Content Server Fundamentals,
Content Server Administration Guide, and Documentum Distributed Configuration Guide.
Intended audience
This manual is written for application developers and system administrators and any
others who want to build a content or workgroup management application that uses
DQL. It assumes that you are familiar with the concepts of document processing,
object‑oriented programming, and client‑server applications. It also assumes working
knowledge of SQL.
Conventions
This manual uses the following conventions in the syntax descriptions and examples.
Syntax conventions
Convention Identifies
italics A variable for which you must provide a value.
[ ] square brackets An optional argument that may be included only once
{ } curly braces An optional argument that may be included multiple
times
| vertical line A choice between two or more options
Revision history
The following changes have been made to this document.

Preface
Revision history
Revision Date Description

July 2008 First Publication

Chapter 1
DQL Language Elements
This chapter describes the building blocks of a DQL statement, including:

• Literals, page 13, which describes the literal formats for the Documentum datatypes
• Special keywords, page 19, which describes the special keywords that you can use in DQL queries
• Functions, page 20, which describes the functions that you can use in DQL queries
• Predicates, page 30 , which describes the predicates that you can use in expressions in queries
• Logical operators, page 39 , which describes the logical operators supported by DQL
• DQL reserved words, page 42 , which cross‑references you to a list of the words reserved in DQL
Literals
Literals are values that are interpreted by the server exactly as they are entered. Content
Server recognizes five types of literals:
• Integer literals, page 13
• Floating point literals, page 14
• Character string literals, page 15
• ID literals, page 15
• Date literals, page 15
Integer literals
An integer literal specifies any whole number and is expressed in the following format:
[+ | ] n
where n is any number between ‑2147483647 and +2147483647.

DQL does not support the negative integer value ‑2147483648 because this number is not
supported in a number of relational databases. If you enter this number, your results
are unpredictable.
Floating point literals

A floating point literal specifies any number that contains a decimal point and is
expressed in the following format:
5.347
21.
0.45
.66
4.12
A floating point literal can also be expressed in scientific notation. For example:
10.4e6
or
3.6E7
or
12e3
DQL accepts either uppercase or lowercase in the notation.

If you assign an integer literal to a property that has a floating point datatype, the system
automatically converts the integer to a floating point number.
The underlying RDBMS determines the maximum and minimum values that you can
assign as a floating point literal. Table 1, page 14 lists the ranges for supported databases.
Note: Do not reset the decimal symbol at the operating system level to a comma. Doing
so results in incorrect execution of some Documentum Administration jobs.
Table 1. Valid ranges for floating point literals
RDBMS Range Significant digits
Oracle 1.0 x 10‑129 to 9.99 x 10‑129 15

DB2 1.0 x 10‑307 to 1.798 x 10+308 15
MS SQL Server 1.7e‑308 to 1.7e+308 15
and Sybase

Character string literals

Character string literals are strings of printable characters and are enclosed in single
quotes. You cannot place non‑printable characters, such as line feeds or carriage returns,
in a character string literal. To include a single quote as part of the literal, include it
twice. For example:
'The company''s third quarter results were very good.'
The maximum length of a character string literal is determined by the maximum allowed
by the underlying RDBMS, but in no case will the maximum length exceed 1999 bytes.
If a property is defined as a string datatype, the maximum length of the character string
literal you can place in the property is defined by the property’s defined length. If you
attempt to place a longer value in the property, DFC will throw an exception. You can
change the behavior and allow DFC to truncate the character string value to fit the
property by setting the dfc preference called dfc.compatibility.truncate_long_values in
dfc.properties.
ID literals
An ID literal specifies an object ID as a 16‑character string enclosed in single quotes. ID
literals are generally used in DQL queries. For example:
SELECT "object_name" FROM "dm_document"
WHERE "r_object_id" = '099af3ce800001ff'
Note that you cannot use ID literals to assign object IDs to objects. Object IDs are
assigned automatically by the server when the object is created.
Date literals
A date literal specifies a date using the following syntax:
DATE('date_value[utc]' [,'pattern'])
date_value can be defined using any of the valid character string formats representing a
date, or it can be one of the keywords that represent dates.
If utc is included, Content Server assumes that the specified date_value is UTC time. The
specification of utc is not case sensitive.
There are some date formats that the server can interpret as more than one date. For
example, 03/04/96 can be interpreted as March 4, 1996 or as April 3, 1996. To resolve this,
some formats require you to specify what pattern the server uses to interpret the date.

Valid dates range from 01/01/1753 (January 1, 1753) to 12/31/9999 (December 31, 9999).
The following paragraphs describe the character string formats and keywords you
can use to specify a date. When you use a character string format, you must enclose
date_value in single quotes.
Default formats
Table 2, page 16 lists the character string formats for date_value that are accepted by
default:
Table 2. Default character string formats for dates
Format Examples
mm/dd/[yy]yy DATE(’03/24/1989’) DATE(’4/7/1992’)
dd‑mon‑[yy]yy DATE(’4‑Apr‑1975’)
month dd[,] [yy]yy DATE(’January 1, 1993’)
mon dd [yy]yy DATE(’March 23 1990’)
the client’s localized short date format DATE(’30‑11‑1990’) (Assumes short date
format dd‑mm‑yyyy is defined on the client
machine)
ANSI format (dow mon dd hh:mm:ss yyyy) No example
Although it is not required, you can specify a pattern for any of these formats except the
short date format and the ANSI format. You cannot specify a pattern when you enter
a date using either of those two formats.
When using the formats listed in Table 2, page 16, the following rules apply:
• It is not necessary to include leading zeros for months or days that are represented as
a single digit.
• You can abbreviate a month’s name to three letters.
• If you enter only the year and not the century, the server uses the century defined by
the current date in the server machine. For example, 03/23/95 is interpreted as March
23, 1995 before the year 2000 and is interpreted as March 23, 2095 after the year 2000.
Short date formats
The server accepts a client’s localized short date format as a valid character string format
as long as the format contains only numeric characters. For example, dd‑mmm‑yy is not
an accepted short date format.

Windows, Solaris, and AIX client platforms provide a default short date format. The
Windows platform also lets you define your own default short date format. (Refer to the
Content Server Administration Guide for information about defining short date formats.)
For HP and Linux clients, which do not have a default short date format, the server
assumes the default format is mm/dd/yy hh:mi:ss.
If the locally defined short date format conflicts with one of the default input formats, the
locally defined format takes precedence. For example, assume that the locally defined
format is dd/mm/yyyy. If a user wants to enter March 14, 1994 and enters 03/14/1994
(mm/dd/yyyy), the server interprets this as the 3rd day of the 14th month of the year 1994
and returns an error because there is no 14th month.
If you use the pattern argument to specify a format for a date, that pattern takes
precedence over the short date format.
ANSI format
You can also specify the date using the ANSI format (dow mon dd hh:mm:ss yyyy).
However, DQL ignores the time fields. (To enter a date and time using the ANSI format,
use DFC.)
Other character string formats
The following character string formats for date_value are also acceptable but require a
pattern argument:
[dd/]mm/[yy]yy[hh:mi:ss]
[yy]yy/mm[/dd] [hh:mi:ss]
[mon‑][yy]yy [hh:mi:ss]
month[,] [yy]yy [hh:mi:ss]
If you do not enter the time (hh:mi:ss), the server assumes the time is 00:00:00. If you
do not enter the day or month, the server assumes the first day of the month or the first
month of the year, respectively.
For example, suppose the pattern argument is [dd/]mm/[yy]yy [hh:mi:ss]. The following
date literal is interpreted as April 1, 1996 00:00:00 (assuming the current century is 1900).
DATE('04/96','mm/yy')
When you specify date_value, you can use any character except a space or an
alphanumeric character as the delimiter. You must use the same delimiter to separate all
elements of the date or time. For example, if you use a forward slash to separate dd and
mm, you must use a forward slash to separate mm and yy. Similarly, if you use a period
to separate hh and mi, you must use a period to separate mi and ss.

The delimiter that you use in the date can be different from the delimiter that you use
in the time portion. For example, the following is valid:
'230496 12.32.04'
It is not necessary to use the same delimiter for the date_value and pattern arguments.
For example, the following function call is valid:
DATE('230496 12.32.04','dd/mm/yy hh:mi:ss')
Date literal keywords
Four keywords represent dates. They are:

• TODAY, which returns the current date. The time defaults to 00:00:00. For example,
SELECT "supervisor_name", "object_name" FROM "dm_workflow"
WHERE "r_start_date" <= DATE(TODAY)
AND "r_runtime_state"=1
ORDER BY 1
• NOW, which returns the current date and time. For example,
SELECT "supervisor_name", "object_name" FROM "dm_workflow"
WHERE "r_start_date" <= DATE(NOW) AND "r_runtime_state"=1
ORDER BY 1
• YESTERDAY, which returns the current date minus one day. The time defaults to
00:00:00. For example,
SELECT * FROM dm_document
WHERE "r_creation_date" >= DATE(YESTERDAY)
AND
"r_creation_date" <= DATE(TODAY)
AND
ANY "authors" IN (john,henry,jane)
• TOMORROW, which returns the current date plus one day. The time defaults to
00:00:00. For example,
SELECT "r_act_name", "object_name", "process_id"
FROM "dm_workflow"
WHERE ANY "r_pre_timer" >= DATE(TOMORROW)
ORDER BY 2
Date output formats
By default, the server uses the client’s localized short date format to output dates to the
client. If the client’s format represents years using two digits, dates in the current century
are displayed using two digits. However, to avoid ambiguity, years in other centuries are
displayed using all four digits (1834 or 1792).

The default short date formats, by platform, are:

• Windows: The default short date format is the format specified in the regional
settings accessed through the Control Panel dialog box.
• UNIX/Solaris and UNIX/AIX: The default short date format is the format defined
by the machine’s locale. (Locale is set by the UNIX setlocale command. Refer to the
Content Server Administration Guide for information about setting this value.)
• UNIX/HP and Linux: The format is assumed to be mm/dd/yy hh:mi:ss.
Note: The session config property r_date_format contains the date format that the
server returns to a client for a given session.
If the date is entered as NULLDATE, then the output is the string NULLDATE.
You can override the default format. If you retrieve a property has a Date datatype, you
can include a pattern argument that defines the format in which the date is returned.
Dates that are included in error messages or a dump file are displayed in ANSI date
format.
Date storage and handling
How dates are stored in the repository and handled during transmission between
Content Server and a client application is not affected by the input or output format
chosen for use.
By default, when communicating with a Documentum Version 6 client, a Content Server
in a new repository assumes that all date values in a query are expressed as client
local time and stores all dates in the repository normalized to UTC time based on that
assumption. This is the recommended format for date storage. Content Server and DFC
will make the necessary time zone adjustments when dates are sent and received. This
behavior can be changed so that Content Server stores the dates in server local time,
rather than in UTC time. However, this is not recommended.
When communicating with a client version earlier than Documentum Version 6, Content
Server assumes that the date values in queries are server local time.
For complete information about date storage and handling, refer to the Content Server
Administration Guide.
Special keywords
DQL includes some special keywords for use in queries. These keywords have special
meanings for Content Server when used in a DQL query. (They cannot be used in DFC
methods.) The keywords are:

• USER, which identifies the current user.

You can use USER in comparison operations in queries. For example,
SELECT "process_id", "object_name" FROM dm_workflow
WHERE supervisor_name=USER
• TRUE and FALSE, which represent the Boolean true and false.
You can use TRUE and FALSE in comparison operations involving any property
having a BOOLEAN datatype. For example,
SELECT * FROM "dm_user"
WHERE "r_is_group" = TRUE
• DM_SESSION_DD_LOCALE, which represents the data dictionary locale most
appropriate for the client’s session locale.
This keyword is particularly useful if the client session locale has no exact match
recognized by the server. If you use this keyword, the server will return the
information from the best matching locale. For example, suppose the server
recognizes three locales, English (en), French (fr), and Spanish (es) and the client
session locale is French Canadian (fr_cn). Suppose the client issues the following
query:
SELECT type_name, label_text from dmi_dd_type_info where
nls_key='fr_cn'
The query returns nothing because the locale fr_cn is not recognized by the server.
However, the following query returns the information from the French locale:
SELECT type_name, label_text from dmi_dd_type_info where
nls_key=DM_SESSION_DD_LOCALE
The server checks whether the locale identified in the client’s session locale, fr_cn,
exists in the repository. Since fr_cn isn’t found, the server attempts to find a good
match among the existing locales. It determines that fr (French) is a good match
and uses that locale to execute the query.
If a good match isn’t found, the server uses the default locale to execute the query.
Functions
Functions are operations on values. DQL recognizes three groups of functions and two
unique functions:
• Scalar functions, page 21
Scalar functions operate on one value and return one value.
• Aggregate functions, page 23
Aggregate functions operate on a set of values and return one value.

• Date functions, page 25

Date functions operate on date values.
• The ID function, page 28
The ID function, a unique function recognized by DQL, is used in the FOLDER and
CABINET predicates and in the IN DOCUMENT and IN ASSEMBLY clauses.
• The MFILE_URL function, page 28
The MFILE_URL function returns URLs to content files and renditions in particular
format.
Scalar functions
The three scalar functions are:
• UPPER
• LOWER
• SUBSTR
UPPER
The UPPER function takes one argument and returns the uppercase of that value. The
value supplied as the argument must be a character string or a property that has a
character string datatype.
For example, the following statement returns the object names of all documents that have
the word government in their title. Because LIKE returns only exact matches, the UPPER
function is used to ensure that all instances are found, regardless of the case (upper,
lower, or mixed) in which the word appears in the title.
WHERE UPPER("title") LIKE '%GOVERMENT%'
LOWER
The LOWER function takes one argument and returns the lowercase of that value. The
value supplied as the argument must be a character string or a property that has a
character string datatype.
For example, the following statement returns the subjects in lowercase of all documents
owned by regina:

SELECT LOWER("subject") FROM "dm_document"

WHERE "owner_name" = 'regina'
SUBSTR
The SUBSTR function returns some or all of a particular string. Its syntax is:
substr(string_value,start[,length])
The value of string_value can be a literal string or a column or property name. If you
specify a column or property, the server uses the value in that column or property as
the string value. The property you specify can be either a single‑valued property or a
repeating property.
The start argument identifies the starting position, in the specified string, of the substring
you want returned. Positions are numbered from the left, beginning at 1. (If you specify
0 as the start, the server automatically begins with 1.) The argument must be an integer.
The length argument defines how many characters should be returned in the substring.
Length is an optional argument. If you do not specify a length, the default behavior of
the function differs depending on the RDMBS you are using. For Oracle and DB2, the
default is the entire string value or the full width of the column if a property or column is
specified. For all other databases, the function returns 1 character.
For example, suppose you have a document subtype called purchase_order, which has
a property called order_no. The values in this property are 10‑digit numbers, with the
last three digits representing a specific sales region. The following statement returns all
documents for which the last three digits in the order_no property are 003:
SELECT "r_object_id","order_no" FROM "purchase_order"
WHERE SUBSTR("order_no",8,3) = '003'
You can also use the SUBSTR function with the SELECT statement. For example:
SELECT SUBSTR("emp_name",1,4) AS short_name FROM "employee"
You must use the AS clause option to rename the query result property that holds the
return value of the SUBSTR function. If you do not, the server cannot return the result
of the function.
If you specify a repeating property, the function returns one value for each value in
the property.
You cannot use the SUBSTR function in assignment statements.
Additionally, you cannot specify SUBSTR in a LIKE predicate. Refer to Pattern matching
with LIKE, page 35, for more information about using LIKE.

Aggregate functions
The five aggregate functions are:
• COUNT
• MIN
• MAX
• AVG
• SUM
COUNT
The COUNT function counts values. The syntax is:

COUNT ([DISTINCT] name | *)
The name argument must identify a property or column. You can count all values for the
property or column or you can include the DISTINCT keyword to count the number of
unique values.
Using an asterisk directs the server to count all items that match specified criteria. For
example, the following statement counts all documents that belong to the user named
grace:
SELECT COUNT(*) FROM "dm_document"
WHERE "owner_name" = 'grace'
MIN
The MIN function returns the minimum value in a given set of values. The syntax is:
MIN(DISTINCT name | [ALL] value_expresssion)
The DISTINCT name argument directs the server to first select all distinct values from
the set (no duplicates) and then return the minimum value. name can be a property or
column name. Note that for this function, the DISTINCT name option has little meaning.
[ALL] value_expression directs the server to return the minimum value found in the
set of values specified by the value_expression argument. value_expression can be any
valid numeric expression or a property or column name. The keyword ALL is optional;
whether it is specified or omitted, all of the values in the set are evaluated.
For example, assuming that rental_charges is a user‑defined object type, the following
statement returns the minimum rent charged for a two‑bedroom apartment:
SELECT MIN("charge") FROM "rental_charges"

WHERE "style" = 'apt' AND "bedroom" = 2
MAX
The MAX function returns the maximum value in a given set of values. The syntax is:
MAX(DISTINCT name | [ALL] value_expresssion)
The DISTINCT name argument directs the server to first select all distinct values from
the set (no duplicates) and then return the maximum value. name can be a property or
column name. Note that for the MAX function, this option has little meaning.
[ALL] value_expression directs the server to return the maximum value found in the
set of values specified by the value_expression argument. value_expression can be any
valid numeric expression or a property or column name. The keyword ALL is optional;
whether it is specified or omitted, all of the values in the set are evaluated.
statement returns the maximum rent charged for a two‑bedroom apartment:
SELECT MAX("charge") FROM "rental_charges"
AVG
The AVG function returns an average. The syntax is:

AVG(DISTINCT name | [ALL] value_expression)
The DISTINCT name option directs the server to select all distinct values from the set (no
duplicates) and return the average of those distinct values. name can be a property or
column name.
[ALL] value_expression directs the server to return the average value found in the set of
values specified by the value_expression argument. The value of value_expression can be
any valid numeric expression or a property or column name. Use the optional keyword
ALL to include all of the values in the set in the operation.
statement returns the average rent charged on a two‑bedroom apartment:
SELECT AVG("charge") FROM "rental_charges"

SUM
The SUM function returns a total. The syntax is:

SUM(DISTINCT name | [ALL] value_expression)
The DISTINCT name option directs the server to select all distinct values from the set
(no duplicates) and return the sum of those distinct values. name can be a property or
column name.
[ALL] value_expression directs the server to return the sum of the values in the set of
values specified by the value_expression argument. The value of value_expression can be
any valid numeric expression or a property or column name. Use the optional keyword
ALL to include all of the values in the set in the operation.
For example, assuming that rent_records is a user‑defined object type that contains
payment records of tenants, the following statement provides a total of the rents paid in
May:
SELECT SUM("rent_amt") FROM "rent_records"
WHERE "mon" = 'may' AND UPPER("paid") = 'Y'
Date functions
The four date functions are:
• DATEDIFF (refer to DATEDIFF , page 25)
• DATEADD (refer to DATEADD, page 26)
• DATEFLOOR (refer to DATEFLOOR, page 27)
• DATETOSTRING (refer to DATETOSTRING, page 27)
DATEDIFF
The DATEDIFF function subtracts two dates and returns a number that represents the
difference between the two dates. The syntax is:
DATEDIFF(date_part, date1, date2)
The date_part argument defines the units in which the return value is expressed. Valid
values are year, month, week, and day.
The date1 and date2 arguments specify the dates to be subtracted. date1 is subtracted from
date2. You can specify the dates as date literals or the names of single‑valued properties
with a date datatype.

For example, the following statement uses the DATEDIFF function to return all tasks
that were started a month or more late:
SELECT "task_number", "supervisor_name"
FROM dm_tasks_queued
WHERE
DATEDIFF(month,"plan_start_date", "actual_start_date")>=1
This next example returns all tasks that were started more than one week ago:
SELECT "task_number", "r_task_user"
FROM dm_tasks_queued
WHERE DATEDIFF(week, "actual_start_date", DATE(TODAY))>=1
If the repository is using Oracle or DB2, the return value is a floating point number.
If the repository is using DB2, the server assumes 365 days per year and 30.42 days per
month (the mean number of days in a month). These assumptions can cause return values
that differ from the expected value. To illustrate, the following example, which asks for
the number of days between March 1, 1996 and Feb 1, 1996, returns 30.42 instead of 28:
DATEDIFF(day, date('03/01/1996 0:0:0'),
date('02/01/1996 0:0:0'))
If the repository is using MS SQL Server or Sybase, the return value is an integer for all
units except day. If you specify day in the function, the return value is a floating point.
The MS SQL Server and Sybase implementations round up if the difference is one half
or greater of the specified unit. The implementations round down if the difference is
less than one half of the specified unit. To illustrate, the following example, which asks
for the difference between March 1, 1996 and July 1, 1996 expressed as years, returns 0
because the difference is only 4 months.
DATEDIFF(year,date('03/01/1996'),date('07/01/1996'))
DATEADD
The DATEADD function adds a number of years, months, weeks, or days to a date
and returns the new date. The syntax is:
DATEADD(date_part, number, date)
Thedate_part argument defines the units that are being added to the specified date. Valid
date parts are year, month, week, and day.
The number argument defines how date_part values are being added to the date. For
example, the following statement uses the DATEADD function to obtain all tasks that
started more than a week ago but are not yet finished:
SELECT "task_number", "supervisor_name" FROM dm_tasks_queued
WHERE DATEADD(week, 1, "actual_start_date") < DATE(TODAY)
AND "actual_completion_date" IS NULLDATE
AND NOT("actual_start_date" IS NULLDATE)

DATEFLOOR
The DATEFLOOR function rounds a given date down to the beginning of the year,
month, or day. The syntax is:
DATEFLOOR(date_part,date)
The date argument is the name of a date property. The function rounds the value of the
property down to the beginning of the unit specified as the value of date_part. Valid
date_part values are year, month, and day.
For example, suppose that a document’s r_creation_date property has a value of March
23, 1996 at 9:30:15 am. Using the DATEFLOOR function on this property returns these
values:
Specifying Returns
January 1, 1996 at 00:00:00
DATEFLOOR(year,"r_creation_
date")
March 1, 1996 at 00:00:00
DATEFLOOR(month,"r_creation_
date")
March 23, 1996 at 00:00:00
DATEFLOOR(day,"r_creation_date")
When you include DATEFLOOR in the selected values list of a SELECT statement, you
must use the AS clause to assign a name to the column representing the returned values.
For example:
SELECT DATEFLOOR(month,"r_creation_date") AS Created...
DATETOSTRING
The DATETOSTRING function returns a date as a character string in a particular format.

The syntax is:
DATETOSTRING(date,'format')
The date argument is the name of a date property. The format argument defines how
you want the character string formatted. The format can be any of the valid character
string input formats for date literals, subject to the following RDBMS restrictions and
qualifications:
• MS SQL Server and Sybase do not support month. If you specify a format that
contains month, such as month dd yyyy, the date is returned in the default short
date format.

• Oracle and DB2 always return the month name as a fixed‑length 9‑character string.
This means that if the name of the month is shorter than 9 characters, the string
value is padded.
Suppose that a document’s r_creation_date property has a value of May 14, 1995. Here
are some examples of the values returned by the DATETOSTRING function using this
date and a variety of formats.
Specifying Returns
DATETOSTRING("r_creation_ 14May95
date",'ddmonyy')
DATETOSTRING("r_creation_ 05/14/95
date",'mm/dd/yy')
DATETOSTRING("r_creation_ May 95
date",'month yy')
The ID function
The ID function is used to identify a folder or cabinet whose contents you want to search.
You can use the ID function in FOLDER and CABINET predicates and IN DOCUMENT
and IN ASSEMBLY clauses. The syntax is:
ID('object_id')
The object_id argument identifies the folder, cabinet, or virtual document you want to
search. The object must reside in the current repository.
Use the literal 16‑character representation of the object’s ID. For example, the following
statement returns all documents in the specified folder with titles containing the
characters Pond:
SELECT * FROM "dm_document"
WHERE FOLDER (ID('099af3ce800001ff'))
AND "title" LIKE '%Pond%'
The MFILE_URL function

The MFILE_URL function returns URLs to content files or renditions associated with
a document. Only those objects on which the user has at least Read permission are
returned if MFILE_URL is included in a selected values list.
The syntax of MFILE_URL is:

MFILE_URL('format',page_no,'page_modifier')
The arguments are ANDed together to determine which URLs are returned. Only the
format argument is required. page_no and page_modifier are optional.
The format argument restricts the returned URLs to those pointing to files in the
specified format. Enclose the format value in single quotes. If you specify format as
an empty string, Content Server takes the format value from the returned object’s
a_content_type property.
The page_no argument restricts the returned URLs to those pointing to content files
associated with given page number. If you do not include page_no, the value defaults to
0, which represents the first content file associated with an object. To indicate that all
content pages should be considered, define page_no as ‑1. If you define page_no as ‑1,
Content Server returns all URLs that satisfy the other arguments regardless of the page
with which the content files are associated.
The page_modifier argument restricts the returned URLs to those pointing to content
files that have the specified page_modifier. The page_modifier argument must be
enclosed in single quotes. If you specify a value for page_modifier (other than an empty
string), all the returned URLs point to renditions, as content files for primary pages have
no page modifier. To return URLs for content files that have no page modifier, define
page_modifier as an empty string. (Content Server sets the page_modifier property to an
empty string by default when a user adds a content file to an object or saves a rendition
without a page modifier.) If you don’t include page_modifier, Content Server returns
the URLs that satisfy the other arguments regardless of whether their content files have
a page modifier or not.
Examples
The following statement returns the URLs to the jpeg_th renditions of the first content
pages of documents owned by ronaldh that have a page modifier of image1.
SELECT MFILE_URL('jpeg_th',0,'image1')
FROM "dm_document" WHERE "object_owner"='ronaldh'
The following example returns the owner name and object ID of all documents that
have the subject prairie chickens. For each returned document, it also returns URLs to
the primary content files associated with the document.
SELECT owner_name,r_object_id,MFILE_URL('',1,'')
FROM "dm_document" WHERE "subject"='prairie_chickens'

Predicates
Predicates are used in WHERE clauses to restrict the objects returned by a query. The
WHERE clause defines criteria that each object must meet. Predicates are the verbs
within the expression that define the criteria.
For example, the following statement returns only documents that contain the value
approved in their keywords property:
SELECT "r_object_id", "object_name", "object_owner"
FROM "dm_document"
WHERE ANY "keywords" = 'approved'
In this example, the equal sign (=) is a predicate. It specifies that any object returned
must have a keywords property value that equals (matches) the specified word (in this
case, the word approved).
DQL recognizes these predicates:
• Arithmetic operators (refer to Arithmetic operators, page 30)
• Comparison operators (refer to Comparison operators, page 31 )
• Column and property predicates (refer to Column and property predicates, page 31 )
• SysObject predicates (refer to SysObject predicates, page 37 )
Arithmetic operators
Arithmetic operators perform arithmetic operations on numerical expressions. Table 3,
page 30 lists the arithmetic operators that you can use as predicates.
Table 3. Arithmetic operators
Operator Operation
+ Addition
– Subtraction
/ Division
* Multiplication
** Exponentiation

Comparison operators
Comparison operators compare one expression to another. Table 4, page 31 lists the
comparison operators that can be used as predicates.
Table 4. Valid comparison operators for DQL statements
Operator Relationship
= Equal
>= Greater than or equal to
<= Less than or equal to
> Greater than
< Less than
<> Not equal
!= Not equal
Column and property predicates

Column and property predicates let you compare values in a registered table’s columns
or an object’s properties to defined criteria. These predicates are divided into two groups.
One group is used only when the search criterion specifies a column or single‑valued
property. The other group is used when the search criteria specifies a repeating property.
Predicates for columns and singlevalued properties
The predicates in this group allow you to compare a value in a table column or
single‑valued property to defined criteria. Table 5, page 31 lists the predicates in this
group.
Table 5. Predicates for columns and singlevalued properties
Predicate Description
IS [NOT] NULL Determines whether the property is assigned a value.
This predicate is useful only for registered table
columns.

IS [NOT] NULLDATE Determines whether the property is assigned a null
date.
IS [NOT] NULLSTRING Determines whether the property is assigned a null
string.
IS [NOT] NULLINT Determines whether the property is assigned a null
integer value.
[NOT] LIKE pattern [ESCAPE Determines whether the property is like a particular
character] pattern. (Refer to The ESCAPE character, page 36 for
information about the ESCAPE clause option.)
[NOT] IN value_list Determines whether the property is in one of a
particular list of values.
[NOT] EXISTS (subquery) Determines whether the property matches a value
found by the subquery.
comparison_op SOME Determines whether the comparison between the
(subquery) comparison_op property value and the results of the subquery
ANY (subquery) evaluate to TRUE in any case.
comparison_op ALL (subquery) Determines whether the comparison between the
property value and the results of the subquery
evaluate to TRUE in all cases.
For example, the following statement selects all documents that have a title that starts
with the word Breads:
WHERE "title" LIKE 'Breads%'
This next example selects all workflows that are supervised by one of the users named in
the predicate:
SELECT "r_object_id", "supervisor_name" FROM "dm_workflow"
WHERE "supervisor_name" IN ('carrie','davidk','holly')
ORDER BY 2
Predicates for repeating properties
The predicates for repeating properties let you compare the values in repeating
properties to some defined criteria. The basic syntax for repeating property predicates is:
[NOT] [ANY] predicate
The ANY keyword must be used whenever an expression references a repeating

property predicate unless the query also includes the DQL hint, ROW_BASED. If

ROW_BASED is included in the query, it is not necessary to include the ANY keyword
with repeating property predicates.
Table 6, page 33 lists the predicates in this group.
Table 6. Predicates for repeating properties
attr_name [NOT] LIKE pattern Evaluates to TRUE if any value of the repeating
[ESCAPE character] property is [not] like a particular pattern. (Refer to
The ESCAPE character, page 36 for information about
the optional ESCAPE clause.)
attr_name IN (value_list) Evaluates to TRUE if any value of the property
matches a value in the value_list. Value_list is a
comma‑separated list of values.
[IN|EXISTS] attr_name IN Evaluates to TRUE if any value of the property
(subquery) matches a value returned by the subquery.
IN and EXISTS are database hints that may enhance

performance by changing the structure of the
generated SQL query. Refer to Appendix A, Using
DQL Hints, for more information about these optional
hints.
attr_name IS [NOT] NULL Evaluates to TRUE if any value of the property is [not]
null.
attr_name IS [NOT] Evaluates to TRUE if any value of the property is [not]
NULLDATE a nulldate.
attr_name IS [NOT] Evaluates to TRUE if any value of the property is [not]
NULLSTRING a null string.
attr_name IS [NOT] NULLINT Evaluates to TRUE if any value of the specified
repeating property is [not] a null integer value.
attr_name comparison_op Evaluates to TRUE if the comparison operation is
value_expression TRUE for any value of the property.
For example, the following statement returns the object names of all documents with an
author whose name begins with a letter in the first half of the alphabet:
WHERE ANY "authors" <= 'M'
You can use logical operators to build more complex predicate expressions, such as:
[NOT] ANY predicate AND|OR [NOT] ANY predicate {AND|OR
[NOT] ANY predicate}

For example, the following statement selects all documents that have Ingrid as an author
and a version label of 1.0:
SELECT "r_object_id", "object_name" FROM "dm_document"
WHERE ANY "authors" = 'Ingrid' AND
ANY "r_version_label" = '1.0'
The predicate statement returns all objects that meet the specified criteria regardless of
where the qualifying value is found in the property’s value list. For example, look at
the following statement:
WHERE ANY "authors" IN ('jeanine','harvey') AND
ANY "keywords" = 'working'
This statement returns the name of all documents with either jeanine or harvey as a value
anywhere in the authors property values list and with the keyword working as a value in
any position in the list of values in the keywords property.
In some circumstances, you may want only objects for which the specified values are
found in the same respective positions. For example, assume that the search finds an
object for which jeanine is the value at position 3 in the authors property. You want the
name of this object only if the keyword working is in position 3 of the keywords property.
You can impose this restriction by enclosing the predicate expression in parentheses:
[NOT] ANY (predicate AND|OR [NOT]predicate {AND|OR [NOT]predicate})
For example, the statement below returns the names of documents for which either
jeanine and working or harvey and working (or both) are values of the authors and
keywords properties, respectively, and occupy corresponding positions in the properties.
WHERE ANY ("authors" IN ('jeanine','harvey')
AND "keywords" = 'working')
Notes:
• To return values at a matching index position level, the keyword ANY is outside the
parentheses.
• You cannot specify an index position at which to look for values. You can specify
only that the values be found in the same respective positions.
• Using the logical operator OR returns the same results as using the basic syntax,
because the server returns the object if either predicate is true.
For more information and examples of querying repeating properties, refer to Repeating
properties in queries, page 382.

Pattern matching with LIKE
The [NOT] LIKE predicate for both single‑valued and repeating properties lets you
identify a pattern to match the property value. This pattern is specified as a character
string literal. For example, the following predicate returns all objects whose subject
contains the word Cake:
subject LIKE '%Cake%'
When you use LIKE, the value in the property must match the string exactly, including
the case of each character. If you use NOT LIKE, then the comparison is TRUE for any
value that does not match exactly.
Sometimes, however, you may not know the text of the character string. For example,
you might want to retrieve all documents that have the word Cake in their title but not
know all of the titles. For these instances, Documentum provides two pattern‑matching
characters that serve as wildcards. The two characters are:
• The percent sign (%)
• The underbar (_)
You can include the pattern‑matching characters anywhere in a character string.
The percent sign
The percent sign replaces 0 or more characters. For example, suppose the predicate
contains:
"subject" LIKE 'Breads%'
This returns any object whose subject begins with the word Breads, regardless of the
how many characters or words follow Breads.
To search for any object that contains a particular string in any position, use a predicate
that contains a percent sign both before and after the literal text. For example, the
following predicate returns all objects whose subject contains the string ’work’:
subject LIKE '%work%'
By default, this predicate returns all objects whose subject contains “work” in any
position, including where the string appears as part of a larger string. For example, it
returns any object whose subject contains “networking” or “workers”.
However, for full‑text queries only, a behavior change was implemented beginning in
release 6.0 to make them more useful and perform better. The fulltext query:
object_name like '%mall%'
is interpreted as searching for the whole‑word mall instead of a word‑fragment mall.
The following query will behave differently for Content Server 6.0 and pre‑6.0:
select r_object_id from dm_document where object_name like '%mall%' enable(ftdql)

For pre–6.0, the query produces the following hits:

small.txt
the mall document.txt
For 6.0 and later, the query produces hits only for:
the mall document.txt
This change was done to produce more meaningful hits, since word‑fragments often
produce a mass of unwanted hits and cause performance issues for the full‑text engine.
Additionally, studies of customer queries showed that users often use this form to look
for whole words.
To produce the earlier behavior, use the DQL hint FT_CONTAIN_FRAGMENT. See
Appendix A, Using DQL Hints for information about using DQL hints. Another
approach is to add this hint to the Webtop DQL hint file. Information about this file can
be found in the EMC® Documentum® Search Development Guide. A more permanent
option is to add a parameter called ’fds_contain_fragment’ to the dm_ftengine_config
object in the docbase and set the parameter value to ’true’. The docbase needs to be
restarted for this change to take effect.
The underbar
The underbar replaces one character. For example, suppose the predicate contains:
"subject" LIKE 'Bread_'
This returns any object whose subject is the single word Bread, followed by a space, an s
(Breads), or any other single, printable character.
Matching cases
You can use the UPPER and LOWER functions to retrieve an object that matches a value
regardless of the case of the letters in the value. For example, to retrieve any object with
the word cake in the title, regardless of its position in the title or the case:
UPPER("title") LIKE '%CAKE%'
Using the UPPER function changes all titles to uppercase for the comparison so that the
case of the characters is not a factor. You can use the LOWER function the same way:
LOWER("title") LIKE '%cake%'
The ESCAPE character
There may be occasions when the pattern you want to match includes a percent sign (%)
or an underbar (_). To match either of those characters literally, you must specify an

escape character and insert that character before the percent sign or underscore in the
pattern. Use the optional ESCAPE clause to specify the escape character.
For example, suppose you want to find all documents whose object names contain an
underscore. Because the underscore is interpreted as a wild card by default, you must
define and use an escape character in the query:
SELECT "r_object_id" FROM "dm_document"
WHERE "object_name" LIKE '%\_%' ESCAPE '\'
In the above example, the backslash is defined as the escape character. Placed in the
pattern directly ahead of the underscore, it tells the server to treat the underscore as a
literal character rather than a wild card.
In addition to the wildcard characters, an escape character can also escape itself. For
example, suppose you want to match the string %_\ and that you have defined the
backslash as the escape character. Your LIKE predicate would look like this:
LIKE '\%\_\\' ESCAPE '\'
In the above example, the backslash character escapes not only the percent sign and
underscore but also itself.
Escape characters can escape only the two wildcard characters and themselves. If you
insert an escape character before any other character in a pattern, it generates an error.
You can use any printable character as an escape character.
SysObject predicates
Three predicates restrict the search specified in a FROM clause.
When you specify an object type in a FROM clause, the server examines that type and
its subtypes for any objects that fulfill the conditions specified in the rest of the query.
However, sometimes you may want to limit the search to specific subtypes, folders, or
cabinets. These three predicates allow you to do so. They are:
• TYPE
• FOLDER
• CABINET
The TYPE predicate
The TYPE predicate restricts the search to objects of a single type or one of its subtypes.
The syntax is:
TYPE(type_name)

The type_name argument must identify a subtype of a type specified in the FROM clause.
For example, the following statement retrieves all documents of the type legal_doc
or accounting_doc or a subtype:
WHERE TYPE("legal_doc") OR TYPE("accounting_doc")
Using the TYPE predicate provides one way to select from more than one type. For
example, to retrieve all documents or workflow process definitions that have been
created after a particular date, you could use the following statement:
SELECT "r_object_id", "object_name", "owner_name", "r_creation_date"
FROM "dm_sysobject" WHERE TYPE("dm_document") OR TYPE("dm_process")
The FOLDER predicate
The FOLDER predicate identifies what folders to search. The syntax is:
[NOT] FOLDER(folder_expression {,folder_expression} [,DESCEND])
The folder_expression argument identifies a folder in the current repository. You can’t
search a remote folder (a folder that doesn’t reside in the current repository). Valid
values are:
• An ID function
• The ID function (described in The ID function, page 28) identifies a particular folder.
• A folder path
A folder path has the format:
/cabinet_name{/folder_name}
Enclose the path in single quotes. Because cabinets are a subtype of folder, you can
specify a cabinet as the folder.
• The keyword DEFAULT
The keyword DEFAULT directs the server to search the user’s default folder. Note
that a user’s default folder is the same as the user’s default cabinet (because cabinets
are a subtype of folders).
The DESCEND keyword directs the server to search the specified folder or folders and
any local folders directly or indirectly contained within that folder or folders. The
predicate does not search any contained, remote folders. The specified folder or folders
may have no more than 25,000 nested folders if you include the DESCEND keyword.
When the search finds a remote folder, it returns the object ID of the associated mirror
object in the current repository. It does not return the object’s ID in the remote repository.

DESCEND applies to all folders specified in the predicate. If you want to search one
folder without descending but descend through another folder, include two folder
predicates in your statement and OR them together. For example:
FOLDER ('/cakes/yeasted', DESCEND) OR FOLDER (DEFAULT)
The keyword NOT directs the server not to search a particular folder.
The CABINET predicate
The CABINET predicate restricts the search to a particular cabinet. Its syntax is:
[NOT] CABINET(cabinet_expression [,DESCEND])
The cabinet_expression argument must identify a cabinet that resides in the current
repository. Valid values are:
• An ID function
The ID function (described in The ID function, page 28) must specify a cabinet ID.
• A folder path
The folder path must identify a cabinet. Its format is:
/cabinet_name
Enclose the path in single quotes.

The keyword DESCEND directs the server to search the specified cabinet and any folders
directly or indirectly contained in the cabinet that reside in the current repository. The
predicate does not search any contained, remote folders.
When the search finds a remote folder, it returns the object ID of the associated mirror
object in the current repository. It does not return the object’s ID in the remote repository.
The keyword NOT directs the server not to search a particular cabinet.
Logical operators
Logical operators are used in WHERE clauses. DQL recognizes three logical operators:
• AND
• OR
• NOT

AND and OR
The AND and OR operators join two or more comparison expressions to form a complex
expression that returns a single Boolean TRUE or FALSE. The syntax for these operators
is:
expression AND | OR expression
Two expressions joined using AND return TRUE only if both expressions are true. For
example, the following complex expression returns TRUE when both of its component
expressions are true, and FALSE when only one of them is true:
"title" = 'Yeast Breads of England' AND "subject" = 'Breads'
Similarly, the following expression also returns TRUE only if both conditions are true:
"subject" = 'Breads' AND ANY "authors" IN ('clarice','michelle','james')
Two expressions joined using OR return TRUE if either expression is true. For example,
the following expression returns true when either comparison is true:
"subject" = 'Cheeses' OR "owner_name" = 'donaldm'
NOT
The NOT operator reverses the logic of an expression. The following expression is
a simple example:
"subject" = 'Cheeses'
When the server encounters this expression, it is looking for objects that have a subject
property with the value Cheeses. The server returns TRUE if the subject value is Cheeses
and FALSE if it is not.
Now, look at the same expression with the NOT operator:
NOT("subject" = 'Cheeses')
In this instance, the server looks for the objects with subject properties that do not
contain the value Cheeses. The server returns TRUE if the subject is not Cheeses and
FALSE if the subject is Cheeses.
Order of precedence
You can join any number of expressions together with logical operators. Content Server
imposes no limit. (Note that your underlying RDBMS may impose a limit.) The resulting
complex expression is evaluated from left to right in the order of precedence of the
operators. This order, from highest to lowest, is:

NOT
AND
OR
To illustrate, look at the following example:
NOT expression1 AND expression2 OR expression3 AND expression4
The server resolves this expression as follows:
1. Evaluates NOT expression1

2. ANDs the result of Step 1 with the result of expression2
3. ANDs the results of expression3 and expression4
4. ORs the results of Steps 2 and 3
You can change the order of evaluation by using parentheses. For example:
NOT expression1 AND (expression2 OR expression3) AND expression4
The server resolves this expression as follows:
1. Evaluates NOT expression1

2. ORs the results of expression2 and expression3
3. ANDs the results of Step 1 and Step 2
4. ANDs the results of Step 3 with the result of expression4
Similarly, you can use parentheses to change the precedence of the NOT operator:
NOT(expression1 AND expression2 AND expression3)
The complex expression inside the parentheses is evaluated first and the NOT operator
applied to its result.

DQL reserved words

DQL reserved words , page 431, lists the DQL reserved words. If you use any of these as
object or property names, you must enclose the name in double quotes whenever it is
used in a DQL statement.

Chapter 2
DQL Statements
This chapter contains descriptions of the DQL statements. The description of each
statement includes:
• Syntax
• Argument descriptions (if any)
• Return value (if appropriate)
• Detailed information about required permissions and usage
• Related statements
• Example
Quoting Object Type Names and Property Names: Documentum recommends that
you put double quotes around all object type names and property names referenced in
applications. Doing that will ensure that the names will not conflict with any DQL
reserved words or any words reserved by your underlying RDBMS. Documentum
object type names and property names will not generate conflicts, but using the quotes
in applications will make sure that no conflicts are generated by user‑defined type or
property names. To encourage this best practice, the DQL examples in our manuals use
the double quotes.
Comments within DQL Statements: DQL does not accept inline comment. An inline
comment is a comment embedded within a DQL statement.

Abort
Abort
Purpose Cancels an explicit transaction.
Syntax
ABORT [TRAN[SACTION]]
Description
The ABORT statement terminates a transaction that was opened with the BEGIN TRAN
statement. Any changes made while the transaction was open are rolled back. They
are not saved to the repository.
The ALTER TYPE statement does not participate in transactions. If you alter a type as
part of an explicit transaction and then issue an ABORT statement, the changes you
made to the type are not reversed.
You can include either keyword, TRAN or TRANSACTION.
Related statements
Begin Tran, page 70

Commit, page 75

Alter Group
Alter Group
Purpose Modifies a user group.
Syntax
ALTER GROUP group_name ADD members

ALTER GROUP group_name DROP members
ALTER GROUP group_name SET ADDRESS email_address
ALTER GROUP group_name SET PRIVATE TRUE|FALSE
Arguments
Table 7. ALTER GROUP argument descriptions
Variable Description
group_name Identifies the group you want to modify. Use the
group’s name. The name can be a string, which must
be enclosed in single quotes, or an identifier, which
need not be in quotes.
members Identifies users, groups, or both to add or drop from
the group. You can specify user names representing
individual users or names representing groups. Use
a comma‑separated list to specify multiple names.
Alternatively, you can use a SELECT statement to
identify the members (illustrated in Examples, page
46).
When you are identifying an individual user, the

name must be the value of the user’s user_name
property.
email_address Defines an electronic mail address for a group.
Specify this as a character string literal. You
can use any email address that is valid for your
environment. To remove a group’s email address,
specify email_address as an empty string.

Alter Group
Permissions
To alter a group, you must be either the group’s owner or a user with Superuser user
privileges.
Description
Each ALTER GROUP statement can perform only one type of operation. That is, you
cannot add and drop members in the same statement. Nor can you set an email address
in the same statement that adds or drops members.
The SET PRIVATE clause

SET PRIVATE sets the is_private property for the group. Setting the property to TRUE
makes the group a private group; setting it to FALSE makes the group a public group.
Related statements
Create Group, page 76

Drop Group, page 107
Examples
The following example adds two users to the group called superusers:
ALTER GROUP superusers ADD steve,chip
The next example uses a SELECT statement to identify which users to add to the
engineering group:
ALTER GROUP engineering ADD (SELECT "user_name"
FROM "dm_user" WHERE "user_os_name" LIKE '%eng%')
The final example defines an email address for the engineering group:
ALTER GROUP engineering
SET ADDRESS 'engineering@lion.stellar.com'

Alter Aspect
Alter Aspect
Purpose Adds, drops, or changes fulltext‑indexed properties for an aspect.
Syntax
ALTER ASPECT aspect_name ADD

[(property_def {,property_def})]
[[NO]OPTIMIZEFETCH]
ALTER ASPECT aspect_name ADD_FTINDEX ALL
ALTER ASPECT aspect_name DROP_FTINDEX ALL
ALTER ASPECT aspect_name ADD_FTINDEX property_list
ALTER ASPECT aspect_name DROP_FTINDEX property_list
Arguments
Table 8. ALTER ASPECT argument descriptions
aspect_name Identifies the aspect for which the properties are
defined. Use the object_name of a dmc_aspect_type
object.
[NO] OPTIMIZEFETCH Indicates whether to duplicate the names and values
of the properties in the object’s property bag when
the aspect is attached to an object that has a property
bag. OPTIMIZEFETCH directs Content Server to
store the values in the object’s property bag. NO
OPTIMIZEFETCH directs Content Server not to
duplicate the properties into the property bag. The
default is OPTIMIZEFETCH.

Alter Aspect
property_def Defines a property for the aspect. Each property
definition has the following format:
property_name domain [REPEATING]
[(property_modifier_list)]
property_name names the property and domain defines

its datatype. The property name must consist of
ASCII characters. The domain can be any valid
DQL datatype. If the datatype is a character string
datatype, the domain specification must also include
the length.
REPEATING defines the property as a repeating

property.
property_modifier_list defines data dictionary
information for the property. Valid property
modifiers are:
update_modifier
value_assistance_specification
mapping_table_specification
default_specification
constraint_specification
Separate multiple modifiers with commas.
You cannot include a property modifier if the

statement is inside an explicit transaction.
Refer to Property modifiers, page 89, for descriptions

of the property modifiers.
You can specify a maximum of 30 properties in an

ALTER ASPECT statement.
property_list Identifies the properties to be indexed or dropped
from indexing. The properties must be properties
defined for the aspect identified in aspect_name.
Permissions
You must have Superuser privileges to use this statement.

Alter Aspect
Description
Use the ALTER ASPECT statement to add properties to aspects or to drop or modify
properties already attached to an aspect. The statement is also used to define or modify
the fulltext indexing of aspect properties.
Adding properties
You can add a maximum of 30 properties to an aspect in a single operation. If you wish
to add more than 30 to a particular aspect, you must issue multiple ALTER ASPECT
statements.
You cannot add properties to an aspect whose name includes a dot. For example, if the
name of the aspect is “com.mycompany.policy”, then you cannot define properties
for that aspect.
If the ALTER ASPECT statement is inside an explicit transaction, you cannot include
property modifiers (data dictionary information) in the definition.
If you specify OPTIMIZEFETCH when you first add properties to an aspect, you
must specify it also if you add more properties later. Similarly, if you specify NO
OPTIMIZEFETCH, when you first add properties to an aspect, you must specify NO
OPTIMIZEFETCH also if you add more properties later.
When you add a property to an aspect that is already attached to one or more objects,
the value for that property in those objects is the null value (nulldate, nullstring, and
so forth).
Dropping properties
Dropping properties of an aspect also removes the property from objects to which the
aspect is attached.
[NO] OPTIMIZEFETCH
You can choose to optimize performance for fetching or querying aspect properties
by including the OPTIMIZEFETCH keyword in the ALTER ASPECT statement. That
keyword directs Content Server to duplicate the properties and their values into the
property bag of any object to which the aspect is attached, if the object has a property bag.
For more information about property bags, non‑qualifiable properties, and how they are
stored in the object type tables, refer to Content Server Fundamentals.
Fulltext indexing of aspect properties

Properties associated with aspects are not fulltext‑indexed by default. If you wish to
index them, you must issue an ALTER ASPECT statement to identify the aspects you
want indexed. Table 9, page 50, describes the syntax options for specifying full‑text
indexing and what each defines.

Alter Aspect
Table 9. Syntax variations for fulltextindexing of aspect properties
Syntax Description
ADD_FTINDEX ALL Defines all properties of the aspect for indexing
ADD_FTINDEX Defines for indexing only those aspect properties listed in
property_list property_list.
DROP_FTINDEX ALL Stops indexing of all properties of the aspect
DROP_FTINDEX Stops indexing of those aspect properties listed in
property_list property_list.
When you add or drop indexing for aspect properties, only new objects are affected.
The index is not updated to add or drop aspect property values for aspects attached
to existing objects.
Related statements
None
Examples
ALTER ASPECT grant_validation

ADD(grant_amount integer, disbursement_date date,
approved_by string(32))OPTIMIZEFETCH

Alter Type
Alter Type
Purpose Modifies an object type.
Syntax
ALTER TYPE type_name

[FOR POLICY policy_id STATE state_name]
type_modifier_list [PUBLISH]
MODIFY (property_modifier_clause)[PUBLISH]
ADD property_def {,property_def}[PUBLISH]
DROP property_name {,property_name}[PUBLISH]
ALTER TYPE type_name ALLOW ASPECTS
ADD|SET|REMOVE DEFAULT ASPECTS aspect_list
ALTER TYPE type_name ENABLE PARTITION
ALTER TYPE type_name SHAREABLE [PUBLISH]
Arguments
Table 10. ALTER TYPE argument descriptions
type_name Identifies the type to alter. Use the name defined for
the type when it was created.
If you are altering a type to allow aspects, type_name

must be the top‑most type in the type’s hierarchy.
Refer to Allowing aspects, page 57, for more
information.
If you are altering the type to add default aspects, the

type may not be lightweight object type and the type
must have the r_aspect_name property.
If you are altering the type to enable data partitioning,

type_name must be the top‑most type in the type’s

Alter Type
hierarchy. Refer to Allowing Partitioning, page 59,
for more information.
policy_id Identifies the default lifecycle for the type. Use the
policy’s object ID.
Including the FOR POLICY clause requires at least

Version permission on the lifecycle identified by
policy_id.
state_name Identifies one state in the default lifecycle. Use the
state’s name as defined in the dm_policy object.
type_modifier_list Lists one or more specifications that set or alter type
data dictionary information for the type. Valid type
modifiers are:
update_modifier
component_specification
type_drop_clause
Separate multiple type modifiers with commas.
Refer to Type modifiers, page 95 for information

about the syntax and use of each specification.
property_modifier_clause Defines the change you want to make to the property.
The syntax for this clause is:
property_name domain
or
property_name (property_modifier_list)
domain is any valid DQL datatype.
property_modifier_list lists one or more modifiers

that set or alter data dictionary information for the
property. Valid property modifiers are:
update_modifier
property_drop_clause

Alter Type
Refer to Property modifiers, page 89 for information

about the syntax and use of each property modifier.
property_def Defines the properties you want to add to the type.
property_def has the following syntax:
[[NOT]QUALIFIABLE]
(property_modifier_list)
property_name is the name of the property and

domain is any valid DQL datatype. The keyword
property.
By default, a property is qualifiable. Include NOT

QUALIFIABLE if you wish to define the property as
non‑qualifiable. The length of a NOT QUALIFIABLE
property with a string datatype must be less than
the value in the max_nqa_string key in the server.ini
file if that is set. Refer to QUALIFIABLE and
NOT QUALIFIABLE properties, page 55, for more
information about QUALIFIABLE.
property_modifier_list lists one or more modifiers

that define data dictionary information for the
property. Refer to the preceding description of
property_modifier_clause for a list of valid property
modifiers.

property_name For the DROP option, property_name identifies the
property that you want to remove from the specified
type.
aspect_list Comma‑separated list of aspects. Use the value of
the object_name property of their dmc_aspect_type
objects. You are not required to quote the aspect list;
however, if you do, use single quotes.
Adding and setting default aspects, page 57, describes

how default aspects are added to an object type.
Removing default aspects, page 58, describes how
default aspects are removed from an object type.

Alter Type
Permissions
To issue an ALTER TYPE statement that changes locale‑specific data dictionary

information, your session locale must match exactly one of the locales identified in the
dd_locales property of the docbase config.
Table 11, page 54, lists the ALTER TYPE operations and describes who can perform
them and on which types.
Table 11. Alter Type operations
Alteration Who can do it To which types

Set default ACL Type owner or Superuser All types
Set default storage area Type owner or Superuser All types
Set or drop data dictionary Type owner or Superuser All types, with the
information exception that value
assistance and constraints
may not be added to
system‑defined object
types.
Add read/write properties Type owner or Superuser User‑defined only
Add read‑only properties Superuser User‑defined only
Drop read/write properties Type owner or Superuser User‑defined only
Lengthen character string Type owner or Superuser User‑defined only
properties
Allow aspects Superuser Only user‑defined
object types that have
no supertype (that is,
user‑defined object types
that are the top‑most type
in their hierarchy).
Add, set, or remove default Superuser Any object type that is not a
aspects lightweight object type and
that has the r_aspect_name
property.

Alter Type
Alteration Who can do it To which types

Enable type to be Type owner or Superuser Only user‑defined
partitionable object types that have
no supertype (that is,
user‑defined object types
that are the top‑most type
in their hierarchy).
Make type shareable Type owner or Superuser User‑defined only
(For the definition of a read and write or read‑only property, refer to the Object Reference
Manual.)
Description
This section contains information about using the statement.
General notes
You cannot change the definition of a system‑defined type. You can only set a variety of
defaults and data dictionary information. You can change the definition of a user‑defined
type. (Refer to Table 11, page 54 for a summary of valid operations, the types on which
they can be performed, and who can perform them.)
You cannot issue an ALTER TYPE statement in an explicit transaction.
After you execute an ALTER TYPE statement, the changes are not reflected to users
until the global type cache is updated. The updating is automatic but may take several
minutes. Users currently in a session with the repository will not see the type change
if they performed operations on any instance of the type in their session, prior to the
change. (When a user performs an operation on an object, the system caches the object
type definition for that object.)
QUALIFIABLE and NOT QUALIFIABLE properties

A qualifiable property is a standard property. It is stored in a column in the appropriate
table in the database in which the repository resides. Queries can reference qualifiable
properties in selected value lists and in expressions in qualifications. Properties are
qualifiable by default.
A property defined as NOT QUALIFIABLE is stored in a property bag. A non‑qualifiable
property can be referenced in selected value lists, but may not be referenced in
expressions or qualifications in a query.
If a property is a string datatype and it is defined as NOT QUALIFIABLE, its length must
be less than the value in the max_nqa_string key in the server.ini file if that key is set.

Alter Type
Localization
If you change data dictionary information that is locale‑specific, such as label_text, it is
changed only in the current locale (defined in the session’s session_locale property).
If you change data dictionary information that is not locale‑specific, such as a constraint
definition, it is changed in all locales.
PUBLISH
Including PUBLISH causes the server to publish the data dictionary information for the
object type or property immediately. Including PUBLISH publishes the changes made
in the ALTER TYPE statement and any other changes to the type or property that are
not yet published.
If you do not include PUBLISH, the information is published the next time the Data
Dictionary Publish job runs.
It is not necessary to include PUBLISH if you are dropping a property from the type
definition. The data dictionary information for the property is automatically removed
in such cases.
Modifying a type definition

You can modify the definition of a user‑defined type by:
• Adding a new property
• Lengthening a character string property
• Dropping a property defined for the type
Adding a new property
Use the following syntax to add a new property to a user‑defined type:
ALTER TYPE type_name ADD property_def {,property_def}
property_def defines the new property and has the following syntax:
[[NOT]QUALIFIABLE](property_modifier_list)
The property name must following the naming rules outlined in the Object Reference
Manual.
domain is any valid DQL datatype. The keyword REPEATING defines the property as a
repeating property. The keyword QUALIFIABLE identifies the property as a qualifiable
property. If you include NOT QUALIFIABLE, the property is a non‑qualifiable property.
QUALIFIABLE is the default. For information about this property characteristic, refer to
QUALIFIABLE and NOT QUALIFIABLE properties, page 55.
Valid property modifiers are described in Property modifiers, page 89.

Alter Type
Do not add more than 30 properties in one ALTER TYPE statement. If the repository is
running against DB2, the sum total of the lengths of all properties defined for the type
is constrained by the page size defined for the tablespace. Table 16, page 87 lists the
tablespace page sizes and the corresponding maximum row length allowed.
Lengthening a character string property
The character string property must be defined for the object type. It cannot be an
inherited property. The only valid change that you can make is to lengthen the property.
The change is applied to all the type’s subtypes and to all existing objects of the type
and its subtypes.
For example, if a string property called employee_name is currently 24 characters, the
following statement would change the length to 32 characters:
ALTER TYPE "test_result" MODIFY ("patient_name" char(32))
If you are running against Sybase, you can lengthen only one property in each execution
of the statement.
Dropping properties from the type
Only properties that are defined for the type can be dropped. You cannot drop an
inherited property. Dropping a property also removes the property from all subtypes of
the type and removes all data dictionary information for the property.
The drop operation fails if the property is an indexed property for the type and there are
existing indexed objects of the type or its subtypes. (An indexed property is a property
whose value is stored in the full‑text index.)
Note: Some relational database management systems (for example, DB2) don’t support
dropping columns from a table (an property is a column in a table in the underlying
RDBMS). For those databases, if you drop a property, the corresponding column in the
table representing the type is not actually removed. If you later try to add a property
to that type that has the same name as the dropped property, you will receive an error
message.
Allowing aspects
Altering an object type to allow instances of the type to accept aspects performs the
following actions on the object type:
• Adds the repeating property, r_aspect_name, to the type definition if the type does
not have the property already
• Adds the i_property_bag property to the type definition if the type does not have the
property already
Adding and setting default aspects

A default aspect is an aspect that is associated with an object type and, by default,
associated with each instance of the type that is created after the aspect is added to the
type. Default aspects defined for an object type are also default aspects for subtypes of
that type.

Alter Type
ALTER TYPE supports two key words to add default aspects to an object type definition:
ADD and SET. The ADD keyword appends the specified aspect or aspects to any others
already associated with the object type. The SET keyword replaces the object type’s
existing defined default aspects with the aspects specified in the statement. The SET
keyword replaces only the default aspects explicitly defined for the type. It does not
replace any inherited default aspects.
For example, suppose you have an object type named “my_custom_type” with two
default aspects, one that is inherited, named full_validation, and one that is defined
for the type: quick_validation. You want to add an aspect named correct_figures. The
following statement adds the correct_figures aspect to the object type definition while
retaining the other two default aspects:
ALTER TYPE my_custom_type ADD DEFAULT ASPECT correct_figures
After the statement completes, my_custom_type has three default aspects:

full_validation, which is inherited, and quick_validation and correct_figures, which are
defined explicitly for my_custom_type.
Now, suppose that your application developers have created a new version of the
correct_figures aspect that also performs a quick validation. This new version is called
correct_figures_v2. To remove the current correct_figures and quick_validation aspects
and replace them with the new, combined aspect, use the following statement:
ALTER TYPE my_custom_type SET DEFAULT ASPECT correct_figures_v2
my_custom_type now has the following default aspects: full_validation and

correct_figures_v2. The SET keyword replaced both aspects defined for the type with the
one aspect specified in the statement, but left the inherited aspect alone.
When you add an aspect to an object type, only the new instances of the type created
after the addition are affected. The aspect is not attached to existing instances of the type.
Removing default aspects

Use the REMOVE keyword to remove default aspects from an object type definition.
You can remove any default aspect defined specifically for the object type. You cannot
remove a default aspect inherited by the object type.
The statement removes the aspects specified in aspect_list. For example, the following
statement removes the aspect named conditional_validation from my_custom_type:
ALTER TYPE my_custom_type REMOVE DEFAULT ASPECT conditional_validation
An error is returned if the specified aspect is not associated with the specified object
type definition.
When you remove a default aspect from an object type, existing instances of the type
are not affected. The aspect remains attached to those instances of the type. You must
remove the aspect from the existing type instances explicitly after removing the default
aspect from the type definition.

Alter Type
Allowing Partitioning
Altering an object type to be partitionable adds an additional attribute, i_partition, to
the type and its subtypes. Since an object creates database entries in the tables for its
type and all its supertypes, the whole type hierarchy must be either partitionable or
non‑partitionable. Predefined types are already partition enabled (or not), so only
user‑defined supertypes can be modified to be partitionable. For example, the following
statement makes my_custom_type a partitionable type:
ALTER TYPE my_custom_type ENABLE PARTITION
An error is returned if the type is already partitionable, or the type is not a user‑defined
type that has no supertype.
If you alter a type to be partitionable, you must use the Administrative method
GENERATE_PARTITION_SCHEME_SQL to generate an SQL script and run that script
against your database to take advantage of data partitioning.
Making a type shareable

Altering a type to be shareable adds additional attributes, i_sharing_type, i_orig_parent,
and allow_propagating_changes to the type, and marks it as a shareable type. An error
will occur if you attempt to alter an already shareable type or a lightweight type to
be shareable.
Type modifiers
Type modifiers set or change some properties of the type info object and data dictionary
information for the type. For example, you can set the default storage area, ACL, or
default lifecycle or add constraints to the type. You can also drop data dictionary
information.
You cannot include a type modifier if the ALTER TYPE statement is executing inside an
explicit transaction.
update_modifiers
Update modifiers set or remove property values in the dm_nls_dd_info, dm_dd_info,
and dmi_type_info objects for the type. The dm_nls_dd_info and dm_dd_info objects
hold data dictionary information for the type. The dmi_type_info object holds
non‑structural information about the type. You can set properties in the dmi_type_info
object that define the type’s default ACL, default permissions, default storage area,
and default group.
An update modifier is also used to define a default lifecycle for the type.

Alter Type
Setting or removing data dictionary values

You can set any property in the dm_nls_dd_info and dm_dd_info objects that are
applicable to types. Use one of the following statement clauses:
SET property_name[[index]]=value
APPEND property_name=value
INSERT property_name[[index]]=value
REMOVE property_name[[index]]
TRUNCATE property_name[[index]]
The property_name is the name of a property defined for the dm_nls_dd_info or

dm_dd_info object type. The nls_dd_info or dm_dd_info property must be applicable to
object types and settable by users.
Include index if the property is a repeating property. Its interpretation varies:
• For a SET operation, the index defines which value to set.
If the operation is adding a new value to the property, the index must identify the
next available position in the list. If the SET operation is replacing an existing value,
specify the index of the existing value.
• For an INSERT operation, the index defines where to insert the new value.
Existing values are renumbered after the insertion.
• For a REMOVE operation, the index defines which value to remove.
• For a TRUNCATE operation, the index defines the starting position for the truncation.
All values in the list, beginning at that position, are truncated.
The APPEND statement clause doesn’t require an index value for repeating properties
because it automatically puts the new value at the end of the repeating property’s
value list.
You must enclose the index in square brackets.
value is a literal value. If you use a SET statement clause and the property is single‑valued,
value can be NULL.
You cannot use the SET, INSERT, or APPEND statement clauses to alter any of the
following properties:
• From dm_dd_info type
parent_id, default_value, cond_value_assist, cond_computed_expr, val_constraint,
unique_keys, foreign_keys, primary_key
• From the dm_nls_dd_info type
parent_id
Defining the default ACL
A type’s default ACL does not define access to the type. Users can assign a type’s
default ACL to any object of the type they create. Use the following syntax to set a
type’s default ACL:

Alter Type

SET DEFAULT ACL acl_name [IN acl_domain]
The value of acl_name is the ACL’s object name. The acl_domain value is the name of its
owner. The owner’s name is either the user who created the ACL or the alias dm_dbo,
representing the repository owner. The combination of the ACL name and domain
uniquely identifies the ACL within the repository. (For more information about ACLs
and their names and implementation, refer to the Content Server Administration Guide
or Content Server Fundamentals.)
If either the name or domain includes a character (such as a space) that requires you to
enclose the string in single quotes, then you must enclose both strings in single quotes.
If the default ACL is NULL, the server uses the default ACL defined for the type’s
supertype as the default. To set the default ACL to NULL, use the following syntax:
ALTER TYPE type_name SET DEFAULT ACL NULL
If you set the default ACL to NULL, the server automatically sets the
default_owner_permit, default_group_permit, and default_world_permit properties for
the type to NULL also.
Defining the default storage area
The default storage area for a type is where Content Server stores all content files
associated with objects of that type. (Users can change the storage area for an individual
object.)
To set the default storage area for a type, use the following syntax:
ALTER TYPE type_name SET DEFAULT STORAGE[=]storage_area_name
storage_area_name is the name of the storage object representing the storage area.
Defining the default group
To set the default group for a type, use the following syntax:
ALTER TYPE type_name SET DEFAULT GROUP[=]group_name
group_name can be a character string literal or an identifier. If it is a character string

literal, you must enclose it in single quotes.
To set the default group to NULL, use:
ALTER TYPE type_name SET DEFAULT GROUP[=]NULL
Defining a default lifecycle
A lifecycle describes the life cycle of an object. Typically, the SysObject type and its
subtypes have default lifecycles. If an object type has a default lifecycle defined for it,
users or applications can attach the default simply by specifying the keyword Default in
the Attach method. (An object is not attached to a default lifecycle automatically. Users
or the application must explicitly issue an Attach method. Defining a default lets users
or applications attach an object to the default without requiring them to know the name
or object ID of the default. Also, it allows you to change the default without requiring
you to rewrite and recompile any applications that reference the default.)

Alter Type
To set the default lifecycle for a type, use the following syntax:
SET DEFAULT BUSINESS POLICY[=]chronicle_id
[VERSION version_label]
chronicle_id is the object ID of the root version of the lifecycle. The VERSION clause
identifies which version of the lifecycle you want to apply to the type. If you do not
specify a version, the default is the CURRENT version.
mapping_table_specification
A mapping table specification is typically used to map a user‑friendly character string
value to an underlying value that may not be as readable or easy to understand. A
mapping table can also be used to map localized or type‑specific values to an underlying
value.
For example, Desktop Client uses a mapping table defined at the type level to display a
list of the display config objects appropriate for the object type. The actual names of the
display config objects are mapped to more user‑friendly strings. (Display config objects
represent subsets of type properties that have a common display definition.)
If you define a mapping table at the type level, the mappings apply to that object type
and its subtypes.
constraint_specification
You can define the following constraints in a type modifier list:
• Primary key
• Unique key
• Foreign key
• Check
You must have Sysadmin or Superuser user privileges to create a foreign key constraint.
You cannot add a constraint to a system‑defined object type.
The syntax for adding a constraint to a type is:
ADD constraint_specification
You cannot include the FOR POLICY clause for primary, unique, or foreign constraints.
The FOR POLICY clause can only be included when you are defining a check constraint.
The clause defines the check constraint as applicable only when instances of the type
are in the specified lifecycle state. You must have at least Version permission on the
lifecycle identified by policy_id.
If you include the FOR POLICY clause, type_name must be the primary type for the
lifecycle identified in policy_id. The policy_id is the object ID of the dm_policy object for

Alter Type
the lifecycle. state_name is the name of the state for which you are defining the constraint.
State names are defined in the lifecycle’s dm_policy object.
To define a check constraint that applies to all states for an object, do not include the FOR
POLICY clause. Any string literals in the check constraint must be ASCII characters.
For an explanation of each constraint specification, refer to constraint_specification,
page 92.
component_specification
Component specifications identify which components can operate on objects of the type.
Use the following syntax to identify a component for a type:
Include the optional FOR POLICY clause to define the component as applicable only
when objects of the type are in the specified state. You must have at least Version
permission on the lifecycle identified by policy_id to include the FOR POLICY clause.
If you include the clause, type_name must be the primary type for the lifecycle identified
in policy_id. policy_id is the object ID of the dm_policy object for the lifecycle. state_name
is the name of the state for which you are defining the component. State names are
defined in the lifecycle’s dm_policy object.
The format of a valid component specification is described in component_specification,
page 99.
type_drop_clause
A type drop clause removes constraint and component definitions defined for a type.
You cannot remove inherited constraints and component definitions.
• To drop a primary key constraint, use:
DROP PRIMARY KEY
• To drop a unique key constraint, use:
DROP UNIQUE KEY [(property_list)]
property_list identifies the type properties that constitute the key. If there is more
than one property, separate them with a comma.

Alter Type
• To drop a foreign key constraint, you must have Sysadmin or Superuser user
privileges. Use the following syntax:
DROP FOREIGN KEY [(property_list)]
REFERENCES type_name [(attr_list)]
property_list identifies the type properties that constitute the key. If there is more
than one property, separate them with a comma. In the REFERENCES clause,
type_name identifies the object type that contains the referenced properties and
attr_list names the referenced properties.
• To drop check constraints, use:
DROP CHECK
DROP CHECK drops all check constraints defined for the type. If you include the
FOR POLICY clause, the statement removes the check constraints defined for the
specified state. You must have at least Version permission on the lifecycle identified
by policy_id to include the FOR POLICY clause.
Note: To drop a single check constraint, use an update modifier to remove or
truncate the val_constraint[x], val_constraint_enf[x], and val_constraint_msg[x]
properties, where x is the index position of the check constraint you want to remove.
• To drop a component, use:
DROP COMPONENTS
DROP COMPONENTS drops all components defined for the type. If you include
the FOR POLICY clause, the statement removes the components defined for the
by policy_id to include the FOR POLICY clause.
Property modifiers
Property modifiers set or drop data dictionary information for a property. Data
dictionary information includes constraints, value assistance, default value definitions,
and mapping information. Property modifiers set properties of dm_nls_dd_info and
dm_dd_info objects.
You cannot include a property modifier if the ALTER TYPE statement is executing in an
explicit transaction.

Alter Type
update_modifiers
An update modifier lets you directly set a property in a dm_dd_info or nls_dd_info
object. Use the following syntax to include an update modifier:
MODIFY (property_name (update_modifier))
Including the FOR POLICY clause makes the change to the property effective only when
instances of the type are in the specified lifecycle state. You must have at least Version
permission on the lifecycle identified by policy_id.
in policy_id. The policy_id is the object ID of the dm_policy object for the lifecycle. The
state_name is the name of the state for which you are defining the assistance. State names
are defined in the lifecycle’s dm_policy object.
For a description of valid update modifiers for a property, refer to update_modifier,
page 89.
value_assistance_specification
A value assistance specification identifies one or more values for a property. Typically,
value assistance is used to populate a pick list of values for the property when it appears
as a field on a dialog box.
You cannot add value assistance to a system‑defined object type.
Use the following syntax to add or change the value assistance specification for a
property:
MODIFY (property_name (value_assistance_specification))
Including the FOR POLICY clause provides value assistance only when objects of the
type are in the specified lifecycle state. You must have at least Version permission on the
lifecycle identified by policy_id.
state_name is the name of the state for which you are defining the assistance. State names
For a description of valid value assistance specifications, refer to value_assistance_
modifier, page 90.
A mapping table specification typically maps a list of character string values to a list of
integer values. This is useful when you want to provide users with an easily understood

Alter Type
list of values for a property that is an integer data type. Use the following syntax to add
or change a mapping table specification:
MODIFY (property_name (mapping_table_specification))
If you include the FOR POLICY clause, the mapped values are only available when
instances of the type are in the specified lifecycle state. You must have at least Version
permission on the lifecycle identified by policy_id.
When you include the clause, type_name must be the primary type for the lifecycle
identified in policy_id. The policy_id is the object ID of the dm_policy object for the
lifecycle. The state_name is the name of the state for which you are defining the mapping.
State names are defined in the lifecycle’s dm_policy object.
For a description of valid mapping table specifications, refer to mapping_table_
specification, page 91.
default_specification
A default specification defines the default value for a property. When a new object of
the type is created, the server automatically sets the property to the default value if no
other value is specified by the user.
You cannot add a property and specify a default value for it in the same ALTER TYPE
statement. You must use two ALTER TYPE statements: one to add the property and one
to set its default value.
Use the following syntax to set or change a default specification:
MODIFY (property_name ([SET] default_specification))
The default value can be specified as:

• A literal value
• One of the following keywords: USER, NOW, TODAY, TOMORROW, YESTERDAY
• NULL (This option is not valid for repeating properties.)
For a single‑valued property, the default specification syntax is:
DEFAULT[=]default_value
For a repeating property, the default specification syntax is:

DEFAULT[=](default_value {,default_value})
For example, the following ALTER TYPE statement sets the default value for one
single‑valued property and one repeating property in the object type mytype:
ALTER TYPE "mytype"
MODIFY ("single_attr" (SET default=NOW)),
MODIFY ("rep_attr" (SET default=(USER)))

Alter Type
The default value must be appropriate for the datatype of the property. For example,
you cannot specify the keyword USER for a date property. You cannot specify NULL
for a repeating property.
You can specify the following constraints in a property modifier list:
• Primary key
• Unique key
• Foreign key
• Not null
• Check
You must have Sysadmin or Superuser user privileges to create a foreign key constraint.
You cannot add a constraint to a system‑defined object type.
The syntax for adding a constraint to a property is:
MODIFY (property_name (ADD constraint_specification))
You cannot include the FOR POLICY clause for primary key, unique key, or foreign key
constraints. The FOR POLICY clause can only be included when you are defining a NOT
NULL or check constraint. The clause defines the constraint as applicable only when
instances of the type are in the specified lifecycle state. To define a NOT NULL or check
constraint that applies to all states for the object, do not include the FOR POLICY clause.
If you include the clause, you must have at least Version permission on the lifecycle
identified by policy_id. The type_name must be the primary type for the lifecycle identified
state_name is the name of the state for which you are defining the constraint. State names
For an explanation of each constraint specification, refer to constraint_specification,
page 92.
property_drop_clause
An property drop clause removes constraints, value assistance, or mapping information
defined for the property. You cannot drop inherited constraints, value assistance, or
mapping information.
• To drop a primary key constraint, use:
MODIFY (property_name (DROP PRIMARY KEY))

Alter Type
• To drop a unique key constraint, use:

MODIFY (property_name (DROP UNIQUE KEY
[(property_name)]))
property_name identifies the property you are removing from the unique key.
• To drop a foreign key constraint, you must have Sysadmin or Superuser user
privileges. Use the following syntax:
MODIFY (property_name (DROP FOREIGN KEY
[(property_name)] REFERENCES type_name [(attr_name)]))
property_name identifies the property you are removing from the foreign key.
In the REFERENCES clause, type_name identifies the object type that contains the
referenced properties and attr_name identifies the referenced property. If attr_name is
not included, r_object_id is the default.
• To drop check constraints, use:
DROP CHECK
DROP CHECK drops all check constraints defined for the type. If you include the
FOR POLICY clause, the statement removes the check constraints defined for the
by policy_id.
Note: To drop a single check constraint, use an update modifier to remove or
truncate the val_constraint[x], val_constraint_enf[x], and val_constraint_msg[x]
properties, where x is the index position of the check constraint you want to remove.
• To drop value assistance, use the following syntax:
MODIFY (property_name (DROP VALUE ASSISTANCE))
• To drop mapping information, use the following syntax:
MODIFY (property_name (DROP MAPPING TABLE))
Related statements
Alter Aspect, page 47

Create Type, page 83
Drop Type, page 109

Alter Type
Examples
This example sets the owner’s object‑level permission and the default group for the
user‑defined type called legal_document:
ALTER TYPE "legal_document"
SET OWNER PERMIT browse,
DEFAULT GROUP lawyers
This example adds a property to the user‑defined type called report_doc:

ALTER TYPE "report_doc"
ADD "monthly_total" integer
The next example changes the length of the client_comments property in the user‑defined
type called case_report:
ALTER TYPE "case_report"
MODIFY ("client_comments" string(255))
This next example sets the default ACL for the document object type:
ALTER TYPE "dm_document"
SET DEFAULT ACL generic_doc IN dm_dbo
This next example demonstrates the use of single quotes in setting the ACL:
ALTER TYPE "dm_document" SET DEFAULT ACL 'mktg default'
IN 'marketing'
This final example changes the type my_super to a partitionable type:

ALTER TYPE "my_super" ENABLE PARTITION

Begin Tran
Begin Tran
Purpose Opens an explicit transaction.
Syntax
BEGIN TRAN[SACTION]
Permissions
Anyone can execute the BEGIN TRAN statement.
Description
The BEGIN TRAN or BEGIN TRANSACTION statement opens an explicit transaction.

When you are working in an explicit transaction, none of the changes you make to files
or property values in objects are saved until you issue a COMMIT statement to commit
the changes.
Related statements
Abort, page 44
Commit, page 75

Change...Object
Change...Object
Purpose Changes the object type of one or more objects.
Syntax
CHANGE current_type [(ALL)] OBJECT[S]

TO new_type[update_list]
[IN ASSEMBLY document_id [VERSION version_label] [DESCEND]]
[SEARCH fulltext search condition]
[WHERE qualification]
Arguments
Table 12. CHANGE...OBJECT argument descriptions
current_type Identifies the object type of the objects to change. Use
the type’s name.
new_type Specifies the new object type for the objects. Use the
type’s name. Valid new types depend on the object’s
current type. Refer to Rules and constraints on
changing types, page 72 for a complete description.
update_list Specifies one or more change operations to perform
on the objects you are changing.Valid formats are:
set property_name = value set property_
name[[index]] = value append [n]
property_name = value insert property_
name[[index]] = value remove property_
name[[index]] truncate property_
name[[index]]
If you specify more than one operation, use commas

to separate the clauses. Refer to The update
operations, page 182 for details of these options.
IN ASSEMBLY clause Limits the statement to those objects that belong to a
particular assembly. For details about the syntax and
use, refer to The IN ASSEMBLY clause, page 156.

Change...Object
SEARCH clause Restricts the candidates for change to those that
satisfy the full‑text search condition. Refer to The
SEARCH clause, page 157 for a description of its
syntax and use.
WHERE clause Defines a qualification used to restrict what objects
are changed. Refer to The WHERE clause, page
161 for a description of a valid qualification.
Return value
The CHANGE...OBJECT statement returns a collection identifier. The collection has one
query result object, with one property called objects_changed. The property contains
the number of objects changed.
Permissions
To use this statement, you must have Delete permission for the objects you want to
change.
To use the update_list option to change an object’s owner (owner_name property), you
must be have Superuser user privileges or Change Ownership privilege.
Description
The CHANGE...OBJECT[S] statement lets you change one or more objects from one
custom object type to another.
Note that when you change an object from a subtype to a supertype, you lose the values
of the properties that are inherited from the supertype.
Objects that meet the criteria in the statement are deleted from the repository and
recreated as objects of the specified new type. The recreated objects retain their old
object IDs and all their previous relationships. For example, if a document is annotated,
changing that document to another type of document does not delete its annotations.
You cannot execute CHANGE...OBJECT on an object that is immutable.
Rules and constraints on changing types

There are some constraints when you change an object’s type:

Change...Object
• The object’s current type and the new type must have the same type identifier.
The type identifier is the first two characters in an object ID. This value is inherited
from the type’s supertype. For example, all dm_document subtypes have 09 as
their type identifier.
• The old and new types cannot be at the same level in the type hierarchy. The new
type must be a supertype or subtype of the current type. That is, the new type must
be in a direct hierarchical line from the current type.
You can move objects up or down in the object hierarchy but not laterally. For
example, suppose TypeA and TypeB are both subtypes of mybasetype, and TypeC is
a subtype of TypeB. You can change objects of Type B to mybasetype or to TypeC.
You cannot change objects of TypeA directory to TypeB because these two types are
peers in the hierarchy. Nor can you change objects of TypeC to TypeA because
TypeA is not a supertype or subtype of TypeC.
When you change an object to a type that is higher in the hierarchy, the server drops any
properties from the old type that are not in the new type. Similarly, when you move an
object to a type that is lower in the hierarchy, the server adds any properties in the new
type that were not in the old type. Unless you use the update_list option to set these new
properties, the server assigns them default values appropriate for their datatypes.
The optional clauses are applied in the following order:
• The SEARCH clause
• The IN ASSEMBLY clause
• The WHERE clause
Using the (ALL) option

Including (ALL) directs Content Server to consider all versions of the object for the
change. If you do not include (ALL), the server only considers the CURRENT version for
the change. ALL must be enclosed in parenthesis.
Related statements
Create...Object, page 79
Delete...Object, page 103
Update...Object, page 178
Examples
This example changes all special_document documents for which the subject is new
book proposal to the document subtype book_proposal:

Change...Object
CHANGE "special_document" OBJECTS TO "book_proposal"

SET "department" = 'marketing'
WHERE "subject" = 'new book proposal'

Commit
Commit
Purpose Commits the changes made during an explicit transaction and closes the
transaction.
Syntax
COMMIT [TRAN[SACTION]]
Permissions
Anyone can execute the COMMIT statement.
Description
The COMMIT statement closes a transaction that was opened with the BEGIN TRAN
statement and commits to the repository any changes made to objects or files during
the transaction.
You can include either TRAN or TRANSACTION.
Related statements
Abort, page 44
Begin Tran, page 70

Create Group
Create Group
Purpose Creates a user group.
Syntax
CREATE [PUBLIC|PRIVATE] GROUP group_name

[WITH][ADDRESS email_address] [MEMBERS members]
Arguments
Table 13. CREATE GROUP argument descriptions
group_name Defines the name of the group that you are creating.
This name must be unique among all group names
and user names in the repository. You can specify the
name as an identifier or as a character string literal.
Note: Content Server stores all group names in
lowercase.
email_address Specifies the electronic mail address of the group.
Use a character string literal. You can specify any
email address that is valid for your environment.
members Specifies users to be included in the group. You can
specify user names representing individual users,
names representing other groups, or both. The names
must appear as a comma‑separated list. Alternatively,
you can use a SELECT statement to populate the
group.
When you are specifying an individual user, the name

must be the value of the user’s user_name property.

Create Group
Return value
The CREATE GROUP statement returns a collection whose result object has one property,
new_object_id, which contains the object ID of the new group.
Permissions
You must have Create Group, Sysadmin, or Superuser user privileges to create a group.
Description
When you create a group, you are its owner and can alter or delete the group.
Public and private groups

The PUBLIC keyword creates the group as a public group. The PRIVATE keyword
creates the group as a private group. When a user with Sysadmin or Superuser user
privileges creates a group, the group is public by default. When a user with Create
Group user privileges creates a group, the group is private by default.
The public or private setting is stored in the is_private property for the group. The
setting is not used by Content Server. All groups, public or private, are visible in the
dm_group type. This property is provided for use by user‑written applications.
Related statements
Alter Group, page 45

Drop Group, page 107
Examples
The following example creates a group called supers whose members are all the users
with the Superuser user privilege:
CREATE GROUP supers MEMBERS
(SELECT "user_name" FROM "dm_user"
WHERE "user_privileges" >= 16)
The next example creates a group that includes all of Ron’s co‑workers but not Ron:
CREATE GROUP rons_baby_gift WITH MEMBERS

Create Group

WHERE "user_name" != 'Ron')
This final example creates a group and defines an email address for that group:
CREATE GROUP client_group
WITH ADDRESS 'john@jaguar.docu.com'
MEMBERS john,regina,kendall,maria

Create...Object
Create...Object
Purpose Creates an object.
Syntax
CREATE type_name OBJECT update_list

[,SETFILE 'filepath' WITH CONTENT_FORMAT='format_name']
{,SETFILE 'filepath' WITH PAGE_NO=page_number}
Arguments
Table 14. CREATE...OBJECT argument descriptions
type_name Identifies the type of object to create. Specify the
name of the object type. You can use any valid type in
the repository with the exception of the object types
that represent aspect properties. type_name cannot
be the name of a type representing a type describing
aspect properties.
update_list Specifies one or more operations you want to perform
on the new object. Valid formats are:
set property_name = value set
property_name[[index]] = value
append [n]property_name = value
insert property_name[[index]] = value
remove property_name[[index]] truncate
property_name[[index]] [un]link 'folder
path' move [to] 'folder path'
If you include multiple clauses in the update list, use

commas to separate the clauses.

Create...Object
SETFILE clause WITH Adds the first content file to the new object. Refer
CONTENT_ FORMAT option to WITH CONTENT_FORMAT option, page 81 for
details.
SETFILE clause WITH Adds additional content to the object. Refer to WITH
PAGE_NO option PAGE_NO option, page 81 for details.
Return value
The CREATE...OBJECT statement returns a collection whose result object has one
property, object_created, which contains the object ID of the new object.
Permissions
Anyone can issue the CREATE...OBJECT statement. However, you must have Superuser
privileges to include the SETFILE clause.
Description
The CREATE...OBJECT statement creates and saves a new object. As part of the process,
you can set some of the object’s properties, specify a storage location for the object, and
associate one or more content files with the object.
If you do not use the link update option to define a storage location, the new object is
stored in your default folder or cabinet.
The SETFILE clauses

A SETFILE clause adds content to the new object. You must have Superuser privileges to
include the clause in the statement. Using the SETFILE clause is subject to the following
conditions:
• The content must be a file. It cannot be a block of data in memory.
• The content file must be located in a directory visible to Content Server.
• You cannot add a file created on a Macintosh machine.
• The content cannot be stored in content‑addressed storage or in a turbo store storage
area.
Any object capable of having content may have multiple associated content files. All
files must have the same content format. The content format is defined when you

Create...Object
add the first content file to the object. All subsequent additions must have the same
format. Consequently, specifying the format for content additions after the first file is
not necessary. Instead, you must specify the content’s position in the ordered list of
content files for the object.
To add the first content, use the SETFILE clause with the WITH CONTENT_FORMAT
option.
To add additional content, use the SETFILE clause with the PAGE_NO option.
You can’t include both options in a single SETFILE clause.
WITH CONTENT_FORMAT option
Use this SETFILE option to add the first content file to a new object. The syntax is:
SETFILE 'filepath' WITH CONTENT_FORMAT='format_name'
The filepath must identify a location that is visible to Content Server.

The format name is the name found in the name property of the format’s dm_format
object.
WITH PAGE_NO option
Use this SETFILE option to add additional content to a new object. The syntax is:
SETFILE 'filepath' WITH PAGE_NO=page_number

The page number identifies the file’s position of the content file within the ordered
contents of the new object. You must add content files in sequence. For example, you
cannot add two files and specify their page numbers as 1 and 3, skipping 2. Because the
first content file has a page number of 0, page numbers for subsequent additions begin
with 1 and increment by 1 with each addition.
You cannot use the SETFILE clause with the PAGE_NO option in a CREATE...OBJECT
statement unless the statement contains a prior SETFILE clause with the
CONTENT_FORMAT option.
Related statements
Change...Object, page 71
Examples
The following example creates a new document and sets its title and subject:

Create...Object
CREATE "dm_document" OBJECT

SET "title" = 'Grant Proposal',
SET "subject" = 'Research Funding'
This example creates a new document, sets its title, and adds two content files. The
example is shown for both Windows and UNIX platforms.
On Windows:
SETFILE 'c:\proposals\grantreq.doc'
WITH CONTENT_FORMAT='msww',
SETFILE 'c:\proposals\budget.doc' WITH PAGE_NO=1
On UNIX:
SETFILE 'u12/proposals/grantreq.doc
WITH CONTENT_FORMAT='msww',
SETFILE 'u12/proposals/budget.doc' WITH PAGE_NO=1

Create Type
Create Type
Purpose Creates an object type.
Syntax
To create a type:
CREATE TYPE type_name
[WITH] SUPERTYPE parent_type
[type_modifier_list] [PUBLISH]
To create a partitionable type:

CREATE PARTITIONABLE TYPE type_name
[WITH] SUPERTYPE NULL
To create a shareable type:

CREATE SHAREABLE TYPE type_name
[WITH] SUPERTYPE parent_type [PUBLISH]
To create a lightweight type:

CREATE LIGHTWEIGHT TYPE type_name
SHARES shareable_type
[AUTO MATERIALIZATION |
MATERIALIZATION ON REQUEST |
DISALLOW MATERIALIZATION]
[FULLTEXT SUPPORT NONE |
FULLTEXT SUPPORT |
FULLTEXT SUPPORT LITE | BASE [ADD attribute_list | ALL]
]
[PUBLISH]

Create Type
Arguments
Table 15. CREATE TYPE argument descriptions
type_name Names the new type. Use any valid name that is
unique among the other user‑defined type names in
the repository. Types with names beginning with dm
can only be created by a user with Superuser user
privileges.
The type name must consist of ASCII characters.

property_def Defines a property for the new type. You can define
up to 30 properties. Each property definition has the
following format:
property_name domain [REPEATING] [[NOT]
QUALIFIABLE] [(property_modifier_list)]
property_name names the property and domain defines

its datatype. The property name must consist of
ASCII characters. The domain can be any valid
DQL datatype. If the datatype is a character string
datatype, the domain specification must also include
the length.

property.
By default, a property is qualifiable. Include NOT

QUALIFIABLE if you wish to define the property as
non‑qualifiable. The length of a NOT QUALIFIABLE
property with a string datatype must be less than
the value in the max_nqa_string key in the server.ini
file if that is set. Refer to QUALIFIABLE and
NOT QUALIFIABLE properties, page 87, for more
information about QUALIFIABLE.

Create Type
property_def continued property_modifier_list defines data dictionary
information for the property. Valid property
modifiers are:
update_modifier
You cannot include a property modifier if the

statement is inside an explicit transaction.
Refer to Property modifiers, page 89 for descriptions

of the property modifiers.
parent_type Identifies the supertype of the new type. Valid
supertypes for non‑shareable types are:
• dm_category
• dm_email_message
Note: dm_email_message is a deprecated object
type.
• dm_message_archive
• dm_relation
• dm_state_extension
• dm_state_type
• dm_sysobject and its subtypes
• dm_taxonomy
• dm_user and its subtypes
• user‑defined types
Valid supertypes for shareable types are:
• dm_sysobject and its subtypes
• user‑defined types
To create a type with no supertype, specify parent_type

as NULL. This requires the Superuser user privilege.

Create Type
type_modifier_list Defines data dictionary information for the type.
Valid type modifiers are:
update_modifier
mapping table specification
You cannot include a type modifier if the statement is

inside an explicit transaction.
Refer to Type modifiers, page 95 for descriptions of

the type modifiers.
shareable_type A previously defined shareable type that will be the
parent of the lightweight type.
Return value
The CREATE TYPE statement returns a collection whose result object has one property,
new_object_ID, which contains the object ID of the new object type.
Permissions
You must have Create Type, Sysadmin, or Superuser privileges to create a new object
type.
To define read‑only properties for a new type (properties whose names begin with r_) or
to create a type that has no supertype, you must have Superuser privileges.
If the statement sets locale‑specific information for the new type or properties, your
session locale must match exactly one of the locales defined in the dd_locales property of
the docbase config object.
Description
The user who creates a type becomes the type’s owner.

Create Type
You cannot include a CREATE TYPE statement in an explicit transaction.

Do not define more than 30 properties in a single CREATE TYPE statement. If the type
has more than 30 properties, use ALTER TYPE to add the additional properties. The
total number of properties in the new type cannot exceed the supported number of
columns in a table in the underlying RDBMS. On DB2, the sum total of the lengths of
the properties defined for the type cannot exceed the maximum row length set by the
page size of the tablespace. Table 16, page 87 lists the tablespace page sizes and the
corresponding maximum row length allowed.
Table 16. DB2 tablespace page sizes and associated maximum row lengths
Tablespace Page Size Maximum Row Length, in bytes

4K 4005
8K 8101
16K 16,293
32K 32,677
Additionally, be sure to follow the naming rules for properties described in the Object
Reference Manual.
QUALIFIABLE and NOT QUALIFIABLE properties

A qualifiable property is a standard property. It is stored in a column in the appropriate
table in the database in which the repository resides. You can reference qualifiable
properties in selected value lists and in expressions in qualifications in queries.
Properties are qualifiable by default.
A property defined as NOT QUALIFIABLE is stored in a property bag. A non‑qualifiable
property can be referenced in selected value lists, but not in qualifications except under
certain circumstances.
If a property is a string datatype and it is defined as NOT QUALIFIABLE, its length must
be less than the value in the max_nqa_string key in the server.ini file if that key is set.
Specifying an ACL for the type

If one or more servers in the repository is using type‑based ACL inheritance, it is
recommended that you make sure that the object type has an ACL defined for the type.
The ACL does not determine who can use the type, but serves as the default ACL for
objects of the type when users create the objects without naming an ACL for the objects.
After you create the object type, use ALTER TYPE to set the acl_name and acl_domain
properties for the object type if needed.

Create Type
Note: Default ACL inheritance is defined in the server config object, in the default_acl
property. If that property is set to 2, for type‑based ACL inheritance, when a user creates
an instance of the type and does not explicitly assign an ACL to the object, the server will
assign the ACL associated with the object type.
Localization
When you create a new type, any data dictionary information that you define for the type
or its properties in the statement is published in all locales identified in the dd_locales
property of the docbase config object.
PUBLISH
Including PUBLISH causes the server to publish the data dictionary information for
the object type immediately. Publishing creates the dd type info , dd attr info, and dd
common info objects that store the published data dictionary information for the object
type.
If you don’t include PUBLISH, the information is published the next time the Data
Dictionary Publish job runs.
PARTITIONABLE Types
A partitionable type (and its subtypes) has an additional attribute, i_partition. Since an
object creates database entries in the tables for its type and all its supertypes, the whole
type hierarchy must be either partitionable or non‑partitionable. Predefined types are
already partition enabled (or not), so only user‑defined supertypes can be created as
partitionable.
If you create a partitionable type, you must use the Administrative method
GENERATE_PARTITION_SCHEME_SQL to generate an SQL script and run that script
against your database to take advantage of data partitioning.
SHAREABLE Type
A shareable type is created for use with lightweight SysObjects. A shareable object acts
as the parent to the lightweight SysObject. Creating a shareable type creates additional
non‑inherited properties, i_sharing_type, i_orig_parent, and allow_propagating_changes
to the type, in addition to the properties explicitly specified, and marks it as a shareable
type. See Content Server Fundamentals for a discussion of shareable and lightweight
SysObjects.
LIGHTWEIGHT Type
A lightweight object shares its SysObject properties with other lightweight objects,
reducing storage requirements for the object. A shareable object acts as the parent to
the lightweight SysObject, and contains the properties shared among the lightweight
types. Creating a lightweight type creates the i_sharing_parent property, in addition
to the custom properties explicitly specified, and marks it as a lightweight type. This

Create Type
property links the child lightweight object with its shareable parent. See Content Server
Fundamentals for a discussion of shareable and lightweight SysObjects.
Property modifiers
Property modifiers define data dictionary information for a property. Defining property
modifiers sets properties in data dictionary‑related objects for the type. It does not set
any dm_type or dm_type_info properties for the type.
update_modifier
An update_modifier specification can be:
SET property_name[[index]]=value
APPEND property_name=value
INSERT property_name[[index]]=value
REMOVE property_name[[index]]
TRUNCATE property_name[[index]]
property_name is the name of a property defined for the dm_nls_dd_info or dm_dd_info

object type. The dm_nls_dd_info or dm_dd_info property must be applicable to object
type properties and settable by users. If the property is a dm_nls_dd_info property, only
the dm_nls_dd_info object specific to the current locale is updated.
Include index if the property is a repeating property. Its meaning varies:
• For a SET operation, the index defines which value to set.
If the operation is adding a new value to the property, the index must identify the
next available position in the list. If the SET operation is replacing an existing value,
specify the index of the existing value.
• For an INSERT operation, the index defines where to insert the new value.
Existing values are renumbered after the insertion.
• For a REMOVE operation, the index defines which value to remove.
• For a TRUNCATE operation, the index defines the starting position for the truncation.
All values in the list, beginning at that position, are truncated.
The APPEND statement clause doesn’t require an index value for repeating properties
because it automatically puts the new value at the end of the repeating property’s
value list.
You must enclose the index in square brackets.
value is a literal value. If you use a SET statement clause and the property is single‑valued,
value can be NULL.
You cannot use the SET, INSERT, or APPEND formats against the following properties:

Create Type
• From dm_dd_info type

parent_id, default_value, cond_value_assist, cond_computed_expr, val_constraint,
unique_keys, foreign_keys, primary_key
• From the dm_nls_dd_info type
parent_id
value_assistance_modifier
A value assistance modifier identifies one or more values for the property. Typically,
value assistance is used to populate a pick list of values for the property when it appears
as a field on a dialog box. A value assistance modifier has the following format:
VALUE ASSISTANCE IS
[IF (expression_string)
va_clause
(ELSEIF (expression_string)
va_clause)
ELSE]
va_clause
[DEPENDENCY LIST ([property_list])
You can include multiple ELSEIF clauses.

expression_string
expression_string defines a Boolean condition. If it returns TRUE, the server executes
the associated va_clause to return values for the property. expression_string can be an
expression or a complete user‑defined routine. It must be written in Docbasic and must
return a Boolean value. Any string literals in the expression or routine must consist of
ASCII characters. You must have Sysadmin or Superuser user privileges to provide a
user‑defined routine for expression_string.
For expressions, the syntax is:
expression [LANGUAGE docbasic]
For user‑defined routines, the syntax is:

routine_name
([routine_parameter {,routine_parameter}])
FROM OBJECT(object_id)
[LANGUAGE docbasic]
routine_parameter is a property name.

The FROM clause must identify an object whose content file contains the source code
for the routine.
va_clause
The va_clause provides the values for the property. It has two possible formats. One
format provides a list of literal values. The second defines a query to return the values.
Each format allows you to provide an estimate of the expected number of property
values and indicate whether the values represent the complete list of allowed values for
the property.

Create Type
• To provide a list of literal values, use the syntax:

LIST (literal_list)
[VALUE ESTIMATE=number]
[IS [NOT] COMPLETE]
• To provide values from a query, use the syntax:
QRY 'query_string'
[QRY ATTR = property_name]
[ALLOW CACHING]
[VALUE ESTIMATE=number]
[IS [NOT] COMPLETE]
query_string is a DQL query. You can use the special token, $$, in the query string.
When the query is executed, a single dollar sign will appear in the query in place
of the token.
The QRY ATTR clause defines which of the properties in the selected values list to
display. Typically, query_string has only one property in its selected values list—the
property for which you are providing the value assistance. However, some situations
may require you to put more than one property in the selected values list. In such
cases, the server assumes that the first property selected is the property for which
you are providing value assistance. If this is not the case, you must include the QRY
ATTR clause to define which property is the property for which you are providing
assistance.
The ALLOW CACHING clause permits clients to cache the query results.
dependency clause
The DEPENDENCY LIST clause identifies the properties on which expression_string
depends. The default is all properties named in the expression_strings.
A mapping table specification most commonly maps a list of descriptive character
strings to a corresponding list of integers. For example, assume an object type has an
integer property called country in which each value represents a different country. If
you display that property in a dialog box, you want users to see a name for each country
rather than an integer value. Using a mapping table specification, you can map the
integer values to corresponding country names.
The syntax is:
MAPPING TABLE (map_element {,map_element})
where map_element is:

VALUE=value_string
[DISPLAY=display_string]
[COMMENT=description_string]
For example:
MAPPING TABLE (VALUE=4

Create Type
DISPLAY=Spain
COMMENT='Added to list in first quarter 98')
The default for DISPLAY is the data value as a character string literal. The default for
COMMENT is a NULL string.
default_specification
A default specification provides a default value for a property. When a user creates a
new instance of the type, Content Server automatically sets the property to the default
value if no other value is specified by the user.
The default value can be specified as:
• A literal value
• One of the following keywords: USER, NOW, TODAY, TOMORROW, YESTERDAY
• NULL (This option is not valid for repeating properties.)
For a single‑valued property, the syntax is:
DEFAULT[=]default_value
For a repeating property, the syntax is:

DEFAULT[=](default_value {,default_value})
If you specify the default value with a keyword that indicates a date or time, the keyword
is specified using the DATE function:
DATE(keyword)
For example, the following statement creates object type mytype with one single‑valued
date property and one repeating string property and defines a default value for each:
CREATE TYPE "mytype" ("single_attr" date (default=date(NOW)),
"rep_attr" string(32) repeating (default=(USER)))
WITH SUPERTYPE "dm_document"
The default value must be appropriate for the datatype of the property. For example,
you cannot specify the keyword USER for a date property. You cannot specify NULL
for a repeating property.
A constraint_specification defines constraints for a property. For example, you can define
a check constraint to provide data validation for the property. Or you can make the
property a unique key for the type. Constraints are not enforced by Content Server. If
you define a constraint for a property, it must be enforced by your client application.
You can define five kinds of constraints in a property modifier list:
• Primary key
• Unique key
• Foreign key

Create Type
• Not null
• Check
If you define a primary key, unique key, foreign key, or check constraint in a property
modifier list, only the single property for which the constraint is defined can be part of
the constraint. If the constraint must include multiple properties, define it in the type
modifier list.
For each constraint, you can define an error message to display if the constraint is
violated. You can also indicate whether the constraint is enforced by the application or
disabled. Enforcement information is stored in the data dictionary but not used by
Content Server.
Any constraint you define is inherited by all the type’s subtypes.
Refer to Content Server Fundamentals for expanded information about the constraints
and what they do.
Primary key
You can define a primary key constraint only on single‑valued properties. The property
must also have a NOT NULL constraint. You can define only one primary key for a
type. (A type may have more than one primary key if it inherits a primary key from
its supertype.)
To define a primary key constraint in a property modifier list, use:
PRIMARY KEY
[REPORT 'message_string '[ON VIOLATION]]
[DISABLE|ENFORCE [BY] APPLICATION]
message_string is a string literal that contains the error message you want displayed if
the constraint is violated. You can include the following special tokens in the message
to parameterize it:
• $value(property_name)
When the message is displayed, $value(property_name) is replaced with the value
entered by the user in the field associated with the property. The property name
must be enclosed in parentheses with no spaces before the opening parenthesis.
For example:
The security type must be folder" or cabinet and you
entered $value(security_val).
• $$
Use $$ in a message string to display a single dollar sign in the message.
The DISABLE|ENFORCE clause lets you specify that the constraint is either disabled or
enforced by the client application. Content Server does not enforce constraints.
Unique key
The syntax for a unique key constraint specification in a property modifier list is:
UNIQUE KEY

Create Type
Refer to the preceding description of a primary key constraint for information about the
error message and enforcement clauses.
Foreign key
You must have Sysadmin or Superuser user privileges to create a foreign key. To define
a foreign key constraint in a property modifier list, use:
FOREIGN KEY REFERENCES type_name [(property_name)]
type_name identifies the foreign object type that contains the referenced property.
property_name identifies the referenced property in type_name. The referenced property
must have the same datatype as the property for which you are defining the constraint.
If property_name is not included, the server assumes that the referenced property is
r_object_id. In this case, the property for which you are defining the foreign key must
have an ID datatype.
Refer to Primary key, page 93 for information about the error message and enforcement
clauses.
Not null
A NOT NULL constraint means that the property can’t have a NULL value. To define a
NOT NULL constraint specification, use:
NOT NULL
Refer to Primary key, page 93 for information about the error message and enforcement
clauses.
Check
Check constraints are used most commonly for data validation. The constraint consists
of an expression or routine that must return TRUE. If it returns FALSE, the property’s
value violates the constraint. To define a check constraint, use:
CHECK(expression_string)
expression_string can be an expression or a complete user‑defined routine. The expression

or routine must be written in Docbasic and return a Boolean value. Any string literals
in the expression or routine must consist of ASCII characters. To specify a routine, you
must have Sysadmin or Superuser user privileges.
[REPORT 'message_string' [ON VIOLATION]]
For user‑written routines, the syntax is:

routine_name

Create Type
FROM OBJECT(object_id |
PATH folder_path[VERSION version_label])
[LANGUAGE docbasic]

The FROM clause must identify an object whose content file contains the source code for
the routine. Identify the object using the object’s ID or a folder path for an object. If you
use a folder path, you can include a version label. If you don’t include a version label,
the label CURRENT is assumed.
Refer to Primary key, page 93 for information about the error message clause.
Type modifiers
Type modifiers define data dictionary information for the type. For example, you can set
the type’s default lifecycle or define constraints for the type. Type modifier set properties
in the data dictionary objects for the type. No properties are set in the dm_type or
dm_type_info objects for the type.
update_modifier
You can use the same update modifiers for types as for properties (refer to Property
modifiers, page 89). In addition, you can use the following to set the default lifecycle
for a type:
SET DEFAULT BUSINESS POLICY[=]
chronicle_id [VERSION version_label]|
NULL|
NONE
chronicle_id is the object ID of the root version of the lifecycle. The VERSION clause
identifies which version of the lifecycle you want to use. The default is the CURRENT
version.
If you set the default lifecycle to NULL, the type inherits the default lifecycle from its
supertype.
If you set the default lifecycle to NONE, the type has no default lifecycle.
value.

Create Type
and its subtypes.
You can define four kinds of constraints in a type modifier list:
• Primary key
• Unique key
• Foreign key
• Check
For each constraint, you can define an error message to display if the constraint is
violated. You can also indicate whether the constraint is enforced by the application or
disabled. Enforcement information is stored in the data dictionary but not used by
the Content Server.
Constraints are defined in a type modifier list if the constraint includes multiple
properties. For example, if two properties make up the primary key for a type, the
primary key constraint must be defined in the type modifier list. If only a single property
defines the constraint, the constraint is typically defined in the property modifier list for
the property rather than the type modifier list.
Refer to Content Server Fundamentals for more information about the constraints and
their use.
Primary key
You can define only one primary key for a type. (A type may have more than one
primary key if it inherits a primary key from its supertype.) To define a primary key
constraint in a type modifier list, use:
PRIMARY KEY (property_list)
property_list is a comma‑separated list of the properties that make up the key. The
properties must be single‑valued properties and each must have a NOT NULL constraint.
Additionally, all the properties must be defined for the same object type.
message_string is a string literal that contains the error message you want displayed if the
constraint is violated. You can include two special tokens in the message to parameterize
it:

Create Type
• $value(property_name)
When the message is displayed, the server replaces $value(property_name) with the
value entered by the user in the field associated with the property. The property
name must be enclosed in parentheses with no space before the opening parenthesis.
For example:
The security type must be folder or cabinet and you
entered $value(security_val).
• $$
Use $$ in a message string to display a single dollar sign in the message.
The DISABLE|ENFORCE clause lets you specify that the constraint is either disabled or
enforced by the client application. Content Server does not enforce constraints.
Unique key
To define a unique key constraint, use:
UNIQUE KEY (property_list)
property_list is a comma‑separated list of the properties that make up the key. The
properties can be either single‑valued or repeating properties, but all must be defined
for the same object type.
Refer to the description of a primary key constraint on Primary key, page 96 for
information about the error message and enforcement clauses.
Foreign key
You must have Sysadmin or Superuser user privileges to define a foreign key constraint.
Use the following syntax:
FOREIGN KEY (property_list)
REFERENCES type_name [(attr_list)]
[REPORT 'message_string'[ON VIOLATION]]
property_list is a comma‑separated list of the properties that make up the key.

type_name identifies the foreign object type that contains the referenced properties and
attr_list identifies the properties in the foreign type that are referenced by those in the
foreign key. The properties defined in property_list and attr_list must match in number
and datatypes.
If an attr_list is not included, the server assumes that the referenced property is
r_object_id. In this case, only one property can be specified in property_list and it must
have an ID datatype.
Refer to the description of a primary key constraint on Primary key, page 96 for
information about the optional error message and enforcement clauses.

Create Type
Check
Check constraints are used most commonly for data validation. The constraint consists
of an expression or routine that must return TRUE. If it returns FALSE, the property’s
value violates the constraint. Check constraints are defined at the type level when
expression_string references two or more properties. To define a check constraint, use:
CHECK(expression_string)
expression_string can be an expression or a complete user‑defined routine. The expression

or routine must be written in Docbasic and return a Boolean value. To specify a routine,
you must have Sysadmin or Superuser user privileges.
For user‑written routines, the syntax is:

routine_name
FROM OBJECT (object_id |
PATH folder_path[VERSION version_label])
[LANGUAGE docbasic]

The FROM clause must identify an object whose content file contains the source code for
the routine. Identify the object using the object’s ID or a folder path for an object. If you
use a folder path, you can include a version label. If you don’t include a version label,
the label CURRENT is assumed.
Refer to Primary key, page 96 for information about the error message clause.
value.
and its subtypes.

Create Type
component_specification
Component specifications identify which components can operate on objects of the
type. The syntax is:
COMPONENTS (component_id_list)
component_id_list contains one or more entries with the following syntax:

component_classifier=object_id|NONE
component_classifier is a character string that represents a qualified component (a

dm_qual_comp object). It consists of the component’s class name and an acronym for the
build technology used to build the component. For example, an component classifier
might be Checkin.ACX or Checkin.HTML.
object_id is the object ID of the qualified component represented by the classifier. If you
specify NONE instead of an object ID, the component is not available for the type.
Related statements
Alter Type, page 51

Drop Type, page 109
Examples
The following example creates a new subtype called employee, sets the label text for
most properties and constraints in the property modifier list and the type modifier list,
and publishes the data dictionary information.
CREATE TYPE "employee"
(
"emp_ssn" string(10)
(PRIMARY KEY,
CHECK ('Len(emp_ssn)=10'
LANGUAGE docbasic)
REPORT 'The SSN must have exactly 10 digits.'
ENFORCE BY APPLICATION,
SET "label_text"='Social Security Number'),
"emp_first_name" string(32)
(SET "label_text"='First Name',
NOT NULL),
"emp_middle_name" string(32)
(SET "label_text"='Middle Name'),
"emp_last_name" string(32)
(SET "label_text"='Last Name',
NOT NULL),
"emp_disambiguator" integer,
"emp_department" integer
(FOREIGN KEY REFERENCES "department" ("department_id")

Create Type
REPORT'The dept. code must be a valid code.',

NOT NULL,
SET "label_text"='Department Code'),
"emp_job_title" string(64)
(CHECK (validate_job_title ("emp_job_title")
FROM '\Admin\Scripts'
VERSION 'approved'
LANGUAGE docbasic
REPORT '$value is not a valid job title.')
)
WITH SUPERTYPE NULL
UNIQUE ("emp_first_name","emp_middle_name",
"emp_last_name","emp_disambiguator"),
SET "label_text"='Employee Record'
PUBLISH
The following example creates a subtype of dm_document and publishes its information
in the data dictionary:
CREATE TYPE "legal"
("lawyer" CHAR(30),"case_number" INT,
"defendants" CHAR(30) REPEATING)
WITH SUPERTYPE "dm_document" PUBLISH
The following example creates a user‑defined type with no supertype:

CREATE TYPE "my_base_type"
("author" CHAR(30), "title" CHAR(145), "doc_id" ID)
WITH SUPERTYPE NULL
The following example creates a subtype of the user‑defined type my_base_type:

CREATE TYPE "acctg" ("accounting" CHAR(30) REPEATING)
WITH SUPERTYPE "my_base_type"
Delete
Delete
Purpose Removes rows from a registered table.
Syntax
DELETE FROM table_name WHERE qualification
Arguments
Table 17. DELETE argument descriptions
table_name Identifies the registered table from which you
are removing rows. Use the name of table in the
underlying RDBMS.
qualification Defines the conditions used to restrict the rows that
are deleted. Refer to The WHERE clause, page 161 for
a description of the valid forms of a qualification.
Return value
The DELETE statement returns a collection whose result object has one property,
rows_deleted, that contains the number of rows deleted.
Permissions
To delete a row, the following conditions must be true:

• Your object‑level permission for the dm_registered object in the repository that
represents the RDBMS table must be at least Browse.
• Your table permission for the dm_registered object that represents the table must be
DM_TABLE_DELETE.
Delete
• The user account under which Content Server is running must have the appropriate
RDBMS permission to delete from the specified table. (The actual name of this
permission will depend on your RDBMS.)
(For more information about security and object‑level and table permissions, refer to
the Content Server Administration Guide.)
Description
The DELETE statement deletes rows from a registered table. A registered table is a
table in the underlying RDBMS that has been registered with Content Server. (Refer to
Register, page 123 for information about registering tables.) All rows for which the
WHERE clause qualification evaluates to TRUE are deleted.
Related statements
Insert, page 120

Register, page 123
Select, page 130
Unregister, page 173
Update, page 175
Examples
The following example deletes the rows in the registered table authors_table that contain
the name of any author who is not also found in the authors property of a document:
DELETE FROM "authors_table"
WHERE NOT EXISTS (SELECT * FROM "dm_document"
WHERE ANY "authors" = authors_table.name)
Delete...Object
Delete...Object
Purpose Deletes objects from the repository.
Syntax
DELETE [PUBLIC]type_name[(ALL)]
[correlation_variable]
[WITHIN PARTITION (partition_id {,partition_id})
OBJECT[S]
[IN ASSEMBLY document_id [VERSION version_label]
[NODE component_id][DESCEND]]
Arguments
Table 18. DELETE...OBJECT argument descriptions
type_name Identifies the type of object to remove from the
repository. Valid type_names are:
dm_assembly and its subtypes

dm_user and its subtypes
dm_group and its subtypes
dm_sysobject and its subtypes
user‑defined types with NULL supertypes and their
subtypes
correlation_variable Defines a qualifier for the type name that is used to
clarify property references.
WITHIN PARTITION clause Restricts the statement to objects in particular
partitions. partition_id identifies the object partition.
The property, i_partition, contains the partition value
for an object.
Delete...Object
IN ASSEMBLY clause Restricts the statement to objects in a particular
assembly.
document_id identifies the document with which the

assembly is associated. Use a literal object ID:
ID('object_id')
version_label specifies a particular version of the

document. Use a symbolic or an implicit version label.
If you do not include a version label, the server uses
the version identified by the document_id argument.
component_id specifies a particular component in the

assembly. Including the NODE option restricts the
statement to the specified component. Use a literal
object ID to identify the component:
ID('object_id')
The DESCEND keyword directs the server to delete

not only all directly contained node components, but
also any indirectly contained components that meet
the criteria. If you do not include this keyword, the
server deletes only the directly contained components
that meet the criteria in the statement.
SEARCH clause Restricts the statement to objects that meet the
SEARCH clause fulltext search condition. Refer to The
SEARCH clause, page 157 for a detailed description
of the SEARCH clause.
WHERE clause Restricts the statement to objects that meet the
qualification. The qualification is an expression that
evaluates to TRUE or FALSE. Refer to The WHERE
clause, page 161 for a description of the valid forms of
a qualification.
Return value
The DELETE...OBJECT statement returns a collection whose result object has one
property, objects_deleted, that contains the number of objects deleted.
Delete...Object
Permissions
You must have Delete permission on an object to delete the object.
Description
This section contains information about using this statement.
General notes
Deleting objects is subject to the following conditions:
• The object cannot belong to a frozen assembly or a frozen or immutable virtual
document.
• If the compound_integrity property in the server’s server config object is set to TRUE,
the object cannot belong to any virtual document, regardless of the whether the
document is immutable or not.
The type_name argument specifies the type of object to delete. The server searches all
objects of the specified type and any subtypes for objects that meet any additional
criteria you define in the statement.
The keyword PUBLIC restricts the query to those objects with the r_is_public property
set to TRUE. If the query contains a SEARCH clause, the full‑text search is restricted to
those documents for which ISPUBLIC is TRUE. When the server queries or searches only
public objects, it uses only the setting of r_is_public for security checks.
The keyword ALL directs the server to consider all versions of each object. If you do not
include ALL, the server only considers versions with the symbolic label CURRENT. You
must enclose ALL in parentheses.
After the server finds all objects that meet the defined criteria, it deletes those for which
you have Delete permission. If any of the objects that are otherwise eligible for deletion
belong to a frozen assembly or an unchangeable virtual document, then the entire
statement is rolled back and no objects are deleted.
The optional clauses, WITHIN PARTITION, IN ASSEMBLY, SEARCH, and WHERE,
restrict the statement’s scope. The WITHIN PARTITION clause restricts the operation to
particular partitions. The IN ASSEMBLY clause restricts the operation to a particular
virtual document assembly or node (component) within the virtual document. The
SEARCH clause restricts the operations to indexed objects that meet the fulltext search
condition. The WHERE clause restricts the operations to objects that meet the specified
qualification. The clauses are applied in the following order:
• SEARCH
• IN ASSEMBLY
• WHERE
Delete...Object
You cannot use DELETE...OBJECT to destroy record objects. Use the Destroy API
command instead.
The IN ASSEMBLY clause

Including the IN ASSEMBLY clause generates an error if the compound_integrity
property in the server’s server config object is set to TRUE. This property controls
whether objects contained in a virtual document may be deleted from the repository.
If the document identified by document_id does not have an associated assembly, the
statement fails with an error.
Related statements
Examples
This example deletes all old documents owned by Joe:

DELETE "dm_document" OBJECTS
WHERE "r_modify_date" < date('01/01/1970')
AND "owner_name" = 'joe'
The following statement deletes all documents that contain the word yeast but not the
word rolls:
SEARCH DOCUMENT CONTAINS 'yeast' AND NOT'rolls'
This statement deletes all documents that contain the words yeast and bread and those
that contain the words cake and wedding:
SEARCH DOCUMENT CONTAINS 'yeast' AND 'bread'
OR 'cake' AND 'wedding'
The following statement deletes all workflows that have either Janine or Jeremy as
a supervisor:
DELETE "dm_workflow" OBJECTS
WHERE "supervisor_name" = 'janine' OR
"supervisor_name" = 'jeremy'
This example also deletes all workflows that have Janine or Jeremy as a supervisor:
DELETE "dm_workflow" OBJECTS
WHERE "supervisor_name" IN ('janine','jeremy')
Drop Group
Drop Group
Purpose Removes a group from the repository.
Syntax
DROP GROUP group_name
Syntax description
Table 19. DROP GROUP syntax description
group_name Identifies the group to remove from the repository.
You can specify the name as an identifier or as a
character string literal.
Permissions
You must be the owner of a group or have Superuser user privileges to drop a group.
General notes
When you drop a group, Content Server also removes any registry objects that identify
the group as the subject of an audit or event notification request.
Related statements
Alter Group, page 45

Create Group, page 76
Drop Group
Example
This example drops the group called rons_baby_gift:

DROP GROUP rons_baby_gift
Drop Type
Drop Type
Purpose Removes a user‑defined object type from the repository.
Syntax
DROP TYPE type_name
Arguments
Table 20. DROP TYPE argument descriptions
type_name Identifies the object type to remove.
Permissions
You must own the type or have Superuser privileges to drop a type.
Description
The type you identify must meet the following conditions:

• No objects of the type can exist in the repository.
• The type cannot have any subtypes.
Dropping a type also removes data dictionary information for the type and its properties.
The information is removed when one of the following occurs:
• The IDfSession.publishDataDictionary method is executed for the entire repository.
• The Data Dictionary Publisher job runs.
Note: After you drop a type, you may not be able to create a type by the same name
immediately. Allow time for the system to synchronize the type cache before attempting
to recreate the type.
Drop Type
Related statements
Alter Type, page 51

Create Type, page 83
Examples
DROP TYPE "my_base_type"
Execute
Execute
Purpose Executes administration methods.
Syntax
EXECUTE admin_method_name [[FOR] object_id]

[WITH argument = value {,argument = value}]
Arguments
Table 21. EXECUTE argument descriptions
Argument Description
admin_method_name Specifies which administration method you want to
execute. Table 22, page 112 lists the methods.
Administration method names are not case sensitive.

object_id Identifies the object on which you want the function
to operate. Use the object’s object ID.
WITH clause Defines one or more arguments and their values for
the administration method.
Valid arguments differ for each method. Refer to

Chapter 3, Administration Methods, for a description
of each administration method and its arguments.
Return value
The EXECUTE statement returns a collection. The properties of the query result object
in the collection depend on which administration method was executed. Refer to the
description of each method in Chapter 3, Administration Methods, for details.
Execute
Permissions
The privileges required depend on the administration method you are executing. Refer
to the description of the individual method in Chapter 3, Administration Methods,
for information.
Description
The EXECUTE statement is the DQL equivalent of the IDfSession.apply method. You can
use EXECUTE to invoke any of the administration methods that you can invoke using
the apply method except PING and WEBCACHE_PUBLISH. These cannot be executed
using the EXECUTE statement.
Table 22, page 112, lists the administration methods that you can invoke with the
EXECUTE statement and briefly describes the task that each performs.
Table 22. Administration methods by category for the EXECUTE statement
Category of Operation Function Description

Process Management CHECK_SECURITY, Checks a user or group’s
page 205 permissions level for one or
more objects.
GET_INBOX, page 247 Returns items in user’s Inbox.
MARK_AS_ARCHIVED, Sets the i_is_archived
page 288 property of a dm_audittrail,
dm_audittrail_acl, or
dm_audittrail_group object
to T.
PURGE_AUDIT, page Deletes audit trail entries
318 from the repository.
RECOVER_AUTO_ Recovers work items claimed
TASKS, page 331 by a workflow agent master
session but not yet processed.
ROLES_FOR_USER, Returns the roles assigned to
page 347 a user in a particular client
domain.
Execute procedures DO_METHOD, page 218 Executes system‑defined
procedures such as lpq
or who or user‑defined
procedures.
Execute

HTTP_POST, page 257 Directs the execution of a
method to an application
server.
Content storage CAN_FETCH, page 196 Determines whether content
management in a distributed storage area
component can be fetched by
the server.
CHECK_RETENTION_ Finds SysObjects in
EXPIRED, page 201 content‑addressed storage
that have an expired retention
period or no retention period.
CLEAN_LINKS — Provides maintenance for
Deprecated, page 210 linked store storage areas.
This method is On Windows platforms,

deprecated. DFC cleans up unneeded link
Version 6 does not record objects and resets file
support linked storage storage object security.
areas or link record
objects. Consequently, On UNIX platforms, cleans
linked storage areas, up unneeded linkrecord
link records and this objects, directories, and
supporting method are links associated with linked
deprecated. storage areas.
DELETE_REPLICA , Removes a replica from a

page 214 distributed storage area.
DESTROY_CONTENT, Removes a content object
page 216 and its associated file from
the repository. (Do not
use this for archiving; use
PURGE_CONTENT instead.)
GET_FILE_URL, page Returns the URL to a content
245 file.
GET_PATH, page 253 Returns the path to a
particular content file in
a particular distributed
storage area component.
IMPORT_REPLICA, Imports an external file as a
page 262 replica of content already in
the repository.
Execute

MIGRATE_CONTENT, Moves content files from one
page 292 storage area to another.
PURGE_CONTENT, Deletes a content file from a
page 326 storage area. (Used as part of
the archiving process.)
PUSH_CONTENT_ Sets the content metadata in
ATTRS, page 328 a content‑addressed storage
system for a document stored
in that storage system.
REGISTER_ASSET, page Queues a request for the
333 creation of a thumbnail,
proxies, and metadata for a
rich media content file. The
request is queued to Media
Server.
This method is only

available or useful if you
have Documentum Media
Transformation Services
running.
REPLICATE, page 340 Copies content in one
component of a distributed
storage area to another area.
RESTORE_CONTENT, Moves a file or files from
page 345 archived storage to the
original storage location.
SET_CONTENT_ATTRS, Sets the content_attr_name
page 352 and content_attr_value
properties in the content
object associated with the
content file.
SET_STORAGE_STATE, Sets the state of a storage
page 361 area to off‑line, on‑line, or
read‑only.
Execute

TRANSCODE_ Queues a request for a
CONTENT, page 365 content transformation to
Media Server.
This method is only

available or useful if you
have Documentum Media
Transformation Services
running.
Database Methods DB_STATS, page 212 Provides database operation
statistics for a session.
DROP_INDEX, page 227 Drops an index.
EXEC_SQL, page 232 Executes SQL statements.
EXPORT_TICKET_KEY, Exports a repository’s login
page 234 ticket key.
FINISH_INDEX_ Completes an interrupted
MOVES, page 236 object type index move
operation.
GENERATE_ Creates an SQL script to
PARTITION_SCHEME_ partition a repository.
SQL, page 239
IMPORT_TICKET_KEY, Imports a login ticket to the
page 264 repository.
MAKE_INDEX, page 284 Creates an object type index.
MOVE_INDEX, page 314 Moves an object type index
from one tablespace to
another.
Note: Not supported on DB2.
REORGANIZE_TABLE, Reorganizes a database table
page 337 for query performance.
RESET_TICKET_KEY, Generates a login ticket key
page 343 for the repository.
UPDATE_STATISTICS, Updates the statistics for a
page 369 database table.
Full‑Text Methods ESTIMATE_SEARCH, Returns the number of
page 229 results matching a particular
SEARCH condition.
Execute

MARK_FOR_RETRY, Finds all queue items
page 290 representing objects that
failed indexing and marks
them as pending indexing.
MODIFY_TRACE, page Sets the tracing level for
312 full‑text querying operations.
Session Management CHECK_CACHE_ Requests a consistency check
CONFIG, page 198 on a particular cache config
object.
GET_LAST_SQL, page Returns the last SQL
251 statement issued.
GET_SESSION_DD_ Returns the locale in use for
LOCALE, page 255 the current session.
LIST_AUTH_PLUGINS, Lists the authentication
page 266 plugins loaded by Content
Server.
LIST_RESOURCES, page Provides information about
268 the server operating system
environment.
LIST_SESSIONS, page Provides information about
273 current, active sessions.
LIST_TARGETS, page Lists the connection brokers
278 defined as targets for the
server.
The information is returned

in a collection with one result
object whose properties
list the connection brokers
defined as targets for the
server.
LOG_ON, page 282 and Turn server logging of
LOG_OFF, page 280 information about RPC calls
on or off.
SET_APIDEADLOCK, Sets a deadlock trigger on
page 349 a particular API method or
operation.
Execute

SET_OPTIONS, page 357 Turn various tracing options
on or off.
SHOW_SESSIONS, page Provides information about
363 current, active sessions and
a user‑specified number of
timed‑out sessions.
The EXECUTE statement is not case sensitive. Also, you do not have to specify the
datatype of the arguments for each function. The statement determines the datatype
from the value you assign to the argument.
Examples
Refer to the individual descriptions of the method in Chapter 3, Administration

Methods, for examples.
Grant
Grant
Purpose Gives one or more user privileges to one or more users.
Syntax
GRANT privilege {,privilege} TO users
Arguments
Table 23. GRANT argument descriptions
privilege Identifies the privilege you want to grant. Valid
privileges are
SUPERUSER
SYSADMIN
CREATE TYPE
CREATE CABINET
CREATE GROUP
CONFIG AUDIT
PURGE AUDIT
VIEW AUDIT
users Identifies the users to whom you want to a privilege
or privileges. The user name must belong to an
individual user. You can specify one or more users
as a comma‑separated list of user names or use a
SELECT statement to identify the user names. (Refer
to Examples, page 119, for the use of a SELECT
statement.)
The user name must be the value is found in the

user_name property of the dm_user object associated
with the user.
Grant
Permissions
To grant Superuser or Sysadmin user privileges, you must have Superuser privileges.
To grant Create Group, Create Type, or Create Cabinet user privileges, you must have
Superuser or Sysadmin user privileges.
To grant Config Audit, Purge Audit, Or View Audit privileges, you must be the
repository owner or a Superuser. Repository owners and Superusers cannot grant these
privileges to themselves.
Description
Granting a privilege to a user who already has that particular privilege does not generate
an error.
Related statements
Revoke, page 128
Examples
The following example grants the Create Type user privilege to the users donna and carol:
GRANT CREATE TYPE TO donna,carol
This example grants the Create Cabinet user privilege to all individual users (that is, to
those user names that do not represent a group):
GRANT CREATE CABINET TO
WHERE "r_is_group" = FALSE)
The final example grants two privileges to the users jim and mike:
GRANT SYSADMIN,SUPERUSER TO jim,mike
Insert
Insert
Purpose Inserts a row into a registered table.
Syntax
INSERT INTO table_name [(column_name {,column_name})]

VALUES (value {,value}) | dql_subselect
Arguments
Table 24. INSERT argument descriptions
table_name Identifies the registered table in which you want to
insert new rows.
column_name Identifies a column in the table to receive an assigned
value.
value Specifies the value assigned to a column. The number
of values specified must equal the number of columns
named or the number of columns in the table. Refer
to Assigning values to columns, page 121 for more
information.
dql_subselect Specifies a SELECT statement. The returned values
are inserted into the table.
Return value
The INSERT statement returns a collection whose result object has one property,
rows_inserted, that contains the number of rows inserted into the table.
Permissions
To use the INSERT statement, the following conditions must be true:
Insert
• Your object‑level permission for the dm_registered object representing the RDBMS
table must be at least Browse.
• Your table permission for the dm_registered object representing the table must be
DM_TABLE_INSERT.
RDBMS permission to insert data into the specified table. (The actual name of this
permission will depend on your RDBMS.)
For more information about security and object‑level and table permissions, refer to
the Content Server Administration Guide.
Description
Use the information in this section to execute this statement.
Assigning values to columns

Which value is inserted in each column you specify is determined by position. That is,
the first column you specify in the statement receives the first value. The second column
receives the second value, and so forth. Consequently, if you are inserting a value in
every column, it is not necessary to specify the columns; the server automatically inserts
the values in each column in turn. However, if you omit the column names, the number
of values must equal the number of columns in the table.
If you specify column names, you can insert values into a subset of the table’s columns.
Also, it is not necessary to specify the column names in the same order in which they
appear in the table. Columns that are not specified in the INSERT statement receive
default values. (Refer to the documentation for your underlying RDBMS for information
about the default values assigned to columns in this situation. Different systems have
different rules. For example, some database management systems only allow you to
default nullable columns. In such systems, all non‑nullable columns must be specified.)
Defining values
There are two possible ways to define the values to assign to columns. You can use the
VALUES clause or you can use a DQL subselect statement.
The VALUES clause has the syntax:
VALUES value {,value}
One value must be specified for each column named in the statement. Each value
must be a literal value appropriate for the datatype of the column to which it is being
assigned. For example, assume there is a registered table called customer_accounts and
that you want to insert values into four of its columns: customer_name, acct_number,
open_date, and balance. The customer_name and acct_number columns are character
Insert
string datatypes. The open_date column is a date datatype, and the balance column is a
floating point datatype. The following statement inserts values into these columns:
INSERT INTO "customer_accounts" ("customer_name","account_number","open_date,
balance") VALUES ('Henrietta Hornsby','01264',date('4/2/1993'),125.00)
The value Henrietta Hornsby is inserted into the customer_name column, the value
01264 is inserted into the account_number column, and so forth.
Similarly, when you use a subselect statement, the returned values must be equal in
number to the number of columns named in the INSERT statement and the values must
be appropriate for the column into which they will be inserted. (Refer to Select, page
130 for the subselect statement’s syntax.)
Related statements
Delete, page 101

Register, page 123
Select, page 130
Update, page 175
Examples
This example saves the object names and creation dates of the contents of the flowers
folder into the objects table:
INSERT INTO "objects" ("o_name", "c_date")
SELECT "object_name", "r_creation_date"
FROM "dm_document"
WHERE FOLDER ('/public/subject/flowers')
Register
Register
Purpose Registers a table from the underlying RDBMS with the repository.
Syntax
REGISTER TABLE [owner_name.]table_name

(column_def {,column_def})
[[WITH] KEY (column_list)]
[SYNONYM [FOR] 'table_identification']
Arguments
Table 25. REGISTER argument descriptions
owner_name Identifies the table’s owner.
Use the owner’s RDBMS user name. If the owner is a

repository user, this value may be found in the user’s
user_db_name property.
If the RDBMS is Oracle or DB2 and the owner is the

DBA, you can use the alias dm_dbo.
If the RDBMS is MS SQL Server or Sybase and the

owner is the DBA, you can use either dbo or dm_dbo
as an alias.
owner_name is optional if the current user is the table’s

owner. The default value is the current user.
Register
table_name Identifies the RDBMS table to register with the
repository.
You can specify the table’s actual name or a synonym.

The name must consist of ASCII characters.
If you specify the table’s actual name, do not include

the SYNONYM clause in the statement.
For Oracle or DB2, if you specify a synonym, that

synonym must be previously defined through the
RDBMS. Including the SYNONYM clause in the
REGISTER statement is optional.
For MS SQL Server or Sybase, if you specify a

synonym, you must include the SYNONYM clause in
the statement.
For MS SQL Server, you cannot register a remote

table.
(Refer to The SYNONYM clause, page 126 for details.)
If you do not have Superuser user privileges, you

must be the owner of the table.
column_def Describes columns in the table. The format for a
column definition is:
column_name datatype [(length)]
where column_name is the name of the column in

the table and datatype is the DQL datatype that
corresponds to the column’s RDBMS datatype. The
column name must consist of ASCII characters. Valid
datatypes in a column definition are:
float, double
integer, int
char, character, string
date, time
You must also specify a length for columns that have

a character, char, or string datatype (for example,
char(24)).
Register
column_list Identifies the columns in the table on which indexes
have been built. Use a comma‑separated list of
column names.
table_ identification The name of the table in the underlying RDBMS.
You must include the SYNONYM clause if you run

against MS SQL Server or Sybase and you specify a
synonym as the table name in the statement.
Including the SYNONYM clause is optional if you are

running against Oracle or DB2 and specify a synonym
as the table name in the statement.
(Refer to The SYNONYM clause, page 126 for details.)
Return value
When issued through IDQL, the REGISTER statement returns the object ID of the
dm_registered object for the table. If you issue the statement through IAPI (using the
Query method), the statement returns a collection whose result object has one property,
called new_object_id, that contains the object ID of the dm_registered object for the table.
Note: IAPI is a deprecated feature.
Permissions
To register a table, you must own the table or have Superuser user privileges. If folder
security is enforced in the repository, you must also have at least Write permission on
the System cabinet.
Description
This section contains usability notes.
General notes
When you execute the REGISTER statement, the server creates an object of type
dm_registered (a SysObject subtype) that represents the RDBMS table in the repository.
This object is automatically linked to the system (/system) cabinet.
Register
A dm_registered object can be manipulated like any other SysObject or SysObject

subtype with one exception: you cannot version a dm_registered object.
You do not have to include all of the columns in the underlying RDBMS table in the
statement. You can specify a subset of the underlying table’s columns. The column
definitions you provide need not match the column definitions for the underlying table.
When the server creates the dm_registered object for the table, it uses your column
definitions.
The REGISTER statement automatically assigns a default ACL to the dm_registered
object. (The default is determined by the value in the default_acl property of the server’s
server config object.)
The statement also sets default table permissions. The table permissions are set to
SELECT for the owner. The group and world are not given any default table permissions.
You can change these by setting the properties directly. Note that table permissions for
registered tables are not hierarchical. (For a complete description of registered table
permits, refer to the Content Server Administration Guide.)
Changes to the definition of an underlying table are not automatically reflected in its
corresponding dm_registered object. If the underlying table is modified and you want
the dm_registered object to match the underlying table definition, you must unregister
the table and then register it with new column definitions.
The SYNONYM clause

Use the SYNONYM clause to register RDBMS tables that have synonyms in the
underlying tables. (A synonym for an RDBMS table must be created independently in the
RDBMS before you register the table. The Register statement does not create a synonym.)
The SYNONYM clause records the actual name of the table that corresponds to the table’s
synonym. The name is stored in the synonym_for property of the table’s dm_registered
object.
When you run against Oracle or DB2, Content Server passes the synonym directly to
the database server. The actual table name, as specified in the SYNONYM clause and
recorded in the synonym_for property is purely informational. For example, suppose
johndoe has a table called myremotetable in the remote Oracle database londonremote,
and that this table has the synonym remote1. To register this table, he uses:
REGISTER TABLE johndoe."remote1" ("columnA" int)
SYNONYM FOR johndoe.myremotetable@londonremote
After he registers the table, he can use the synonym in DQL statements and it is passed
directly to the database server. For example, issuing the following DQL:
SELECT * FROM johndoe."remote1"
generates the following SQL:

Register
When you run against MS SQL Server or Sybase, Content Server substitutes the value
you specified in the SYNONYM clause (recorded in the synonym_for property) for the
table name in the SELECT, INSERT, UPDATE and DELETE statements. For example,
suppose johndoe issues the following REGISTER statement:
REGISTER TABLE johndoe."remote1" ("columnA" int)
SYNONYM FOR londonserver.londonremote.johndoe.myremotetable
After he registers the table, he issues the following SELECT statement:

Content Server substitutes the actual table name for the synonym and the following
SQL is generated:
SELECT * FROM londonserver.londonremote.johndoe.myremotetable
Special note for Oracle platforms
If you create a database link between the database on which the Documentum repository
is installed and another database, and then the use SYNONYM feature to obtain
information from that second database, both databases must be in the same codepage.
Related statements
Delete, page 101

Insert, page 120
Update, page 175
Examples
The following statement registers the RDBMS table named departments:

REGISTER TABLE "departments"
("dept_name" CHAR(30), "dept_code" INT)
KEY ("dept_code")
Revoke
Revoke
Purpose Removes one or more user privileges from one or more users.
Syntax
REVOKE privilege {,privilege} FROM users
Arguments
Table 26. REVOKE argument descriptions
privilege Specifies the privilege to revoke. Valid privileges are:
SUPERUSER
SYSADMIN
CREATE TYPE
CREATE CABINET
CREATE GROUP
CONFIG AUDIT
PURGE AUDIT
VIEW AUDIT
users Specifies the users from whom you are revoking
the specified privilege or privileges. The user name
must belong to an individual user. You can specify
one or more users as a comma‑separated list of user
names or use a SELECT statement to identify the user
names. (Refer to Examples, page 129 for the use of a
SELECT statement.)
The user name must be the value is found in the

user_name property of the dm_user object associated
with the user.
Revoke
Permissions
To revoke the Sysadmin or Superuser user privilege, you must have Superuser user
privileges.
To revoke the Create Group, Create Type, or Create Cabinet user privilege, you must
have either Superuser or Sysadmin user privileges.
To revoke Config Audit, Purge Audit, Or View Audit privileges, you must be the
repository owner or a Supersuser. Repository owners and Superusers cannot revoke
these privileges from themselves.
Description
The statement succeeds even if a user does not have the privilege being revoked.
Related Statements
Grant, page 118
Examples
The following example revokes the Create Cabinet and Create Type privileges from the
users john and howard:
REVOKE CREATE CABINET, CREATE TYPE FROM john, howard
The next example demonstrates the use of a subselect statement to identify the users.
This example revokes the Superuser user privilege from all users except haroldp:
REVOKE SUPERUSER FROM
WHERE "user_privilege" >= 16 AND "user_name" != 'haroldp')
Select
Select
Purpose Retrieves information from the repository, the database, or both.
Syntax
A SELECT statement may be either a standard SELECT or an FTDQL SELECT statement.

The syntax for an FTDQL SELECT statement is a subset of the standard syntax. For a
brief description of an FTDQL SELECT statement, refer to FTDQL SELECT statements,
page 135.
The syntax for a standard SELECT statement is:
SELECT [FOR base_permit_level][ALL|DISTINCT] value [AS
name] {,value [AS name]}
FROM [PUBLIC] source_list
[WITHIN PARTITION (partition_id{,partition_id})
| IN DOCUMENT clause
| IN ASSEMBLY clause]
[SEARCH [FIRST|LAST]fulltext_search_condition
[IN FTINDEX index_name{,index_name}]
[GROUP BY value_list]
[HAVING qualification]
[UNION dql_subselect]
[ORDER BY value_list]
[ENABLE (hint_list)]
The syntax for an FTDQL SELECT statement is:

[SEARCH fulltext_search_condition
[ORDER BY SCORE]
Select
Arguments
Table 27. SELECT argument descriptions
base_permit_level Defines a minimum permission level for the returned
objects. If specified, the query returns only those
objects for which the user has at least the specified
permit level.
Valid values are: NONE, BROWSE, READ, NOTE,

VERSION, WRITE, and DELETE.
If unspecified, the default is BROWSE.
There are no FTDQL constraints on this value.

value Identifies the information to retrieve. Valid values are:
• Property and column names
• Scalar, aggregate, and date functions
• MFILE_URL function
• Arithmetic expressions
• The keywords CONTAIN_ID, CONTENTID,
DEPTH, ISCURRENT, ISPUBLIC, ISREPLICA,
OBJTYPE, PARENT, SCORE, SUMMARY,
SYSOBJ_ID, TEXT, THUMBNAIL_URL, USER
• An asterisk (*)
Multiple values can appear in any order. If the

SELECT statement is a subselect or a subquery, you
can only include one value.
There are constraints on the values in the selected

values list for FTDQL queries. For details, refer to the
Usage Notes sections describing each kind of selected
value.
Select
AS name Defines a name for the result object property that
will contain the retrieved value. This argument
is optional. If you omit it, the system provides a
default name. (Refer to The AS clause, page 149 for
information about the default name.)
name must consist of ASCII characters
You may include the AS name option in an FTDQL

SELECT statement.
source_list Identifies the object types and RDBMS tables to
search. You can specify any combination of object
types and RDBMS tables in a standard SELECT
statement.
Types are specified using the following syntax:

type_name [(ALL)|(DELETED)|(LITE)]
[correlation_variable] [WITH passthrough_
hint_list]
type_name cannot reference an object type that

represents aspect properties.
Tables are specified using the following syntax:

[owner_name.]table_name [correlation_
variable] [WITH passthrough_hint_list]
passthrough_hint_list is a list of hints for one or more

databases. The hint list for an individual database
has the following format:
db_keyword('hint'{,'hint'})
Valid db_keywords are: ORACLE, SQL_SERVER,

SYBASE, and DB2. hint is any valid hint accepted by
the particular RDBMS.
If you include hints for multiple databases, the

hint lists for each must be separated by commas
and the entire set (for all databases) enclosed in
parentheses. Passthrough hints, page 405 describes
using passthrough hints fully.
On Oracle and DB2, a passthrough hint in the source

list in a subquery is applied to the entire SELECT
statement.
The RDBMS table must be a registered table unless

the user issuing the SELECT is a superuser. Only
superusers can query unregistered RDBMS tables.
Additionally, there are several constraints on
specifying more than one type in the source list.
Select
For complete information about specifying type and

table names refer to Source list, page 150. For a
description of the constraints imposed on the source
list by an FTDQL query, refer to FTDQL constraints
on the source list, page 153.
for an object.
IN DOCUMENT clause Identifies the target of the SELECT statement as a
particular virtual document. This clause can assemble
a virtual document or identify the components of
a virtual document. If you include this clause, you
cannot specify the IN ASSEMBLY clause. Refer to The
IN DOCUMENT clause, page 153 for the syntax and
usage of the IN DOCUMENT clause.
This clause may not be included in an FTDQL

SELECT statement.
IN ASSEMBLY clause Identifies the target of the SELECT statement as an
assembly of a virtual document. The server uses the
components of the assembly as the definition of the
virtual document and applies any other specified
conditions to those components, rather than searching
the document’s hierarchy for components.
This clause may not be included in an FTDQL

SELECT statement.
fulltext_search_condition Defines criteria for searching of the full‑text index.
Refer to The SEARCH clause, page 157 for a
description of its syntax and use.
You can include a fulltext search condition in an

FTDQL SELECT statement.
index_name Identifies the index to be searched. Use the index
name as defined in the associated fulltext index
object. Currently, only one index for a repository is
supported.
You can include the IN FTINDEX clause only if the

SELECT statement includes a SEARCH clause.
Select
qualification Restricts returned results to objects meeting the
conditions in the qualification. Refer to The WHERE
clause, page 161 for a full description of the valid
forms of a qualification for a WHERE clause or a
HAVING clause.
dql_subselect Defines an additional DQL SELECT statement. The
columns returned by the statement must correspond
to those returned by the outermost SELECT statement
in number and datatype.
A dql_subselect may not be included in an FTDQL

SELECT statement.
value_list Defines an order in which to group or sort the
returned results. The values in this list must also be
selected values. Refer to The GROUP BY clause, page
165 for the specific use of this in each clause.
A GROUP BY clause may not be included in an

FTDQL SELECT statement.
hint_list One or more standard or passthrough DQL hints.
Refer to the description of the source list for the

format of a passthrough hint.
Standard hints are the following:
SQL_DEF_RESULT_SET N
FORCE_ORDER
RETURN_TOP N
OPTIMIZE_TOP N
FETCH_ALL_RESULTS N
OPTIMIZATION_LEVEL level_1 level_2
UNCOMMITTED_READ
FTDQL
NOFTDQL
TRY_FTDQL_FIRST
ROW_BASED
GROUP_LIST_LIMIT N
HIDE_SHARED_PARENT
N is an integer value and level_1 and level_2 are

optimization levels.
For a brief description of the standard hints, refer to

Table 28, page 168. The ROW_BASED hint affects
the selected values list and the WHERE clause
qualification. For information about its effects, refer
to the descriptions of those portions of the syntax.
Information about ROW_BASED is also found in
Select
Appendix A, Using DQL Hints, which contains full
information about all the standard hints.
ROW_BASED may not be included in an FTDQL

query, nor may it be used in queries that reference a
lightweight object type in the FROM clause. All other
hints are acceptable in FTDQL queries or in queries
against a lightweight object type.
Description
This section contains usability information for the Select statement.
General notes
The SELECT statement retrieves information from object types and RDBMS tables.
By default, the statement returns only objects for which the user has at least Browse
permission. If you want to enforce a higher level of permission on the returned objects,
you can include the FOR base_permit_level clause. For example, suppose you issue the
following SELECT statement:
SELECT FOR VERSION "r_object_id","object_name","owner_name"
FROM "dm_document" WHERE "subject"='budget_proposal'
The query returns all budget proposal documents for which the currently logged‑in user
has at least Version permission.
You can execute the statement as a standalone statement and indirectly, as part of a
variety of other DQL statements. For example, the following CREATE GROUP statement
uses a SELECT statement to select the users that will populate the new group:
CREATE GROUP supers MEMBERS
(SELECT "user_name" FROM "dm_users"
WHERE "user_privilege" >= 16)
(For more information about CREATE GROUP, refer to Create Group, page 76 .)
FTDQL SELECT statements

An FTDQL SELECT statement is a SELECT statement whose syntax conforms to a
particular set of rules that allow the query to be executed directly against the fulltext
index. If the statement conforms to FTDQL syntax, the statement is run solely against the
fulltext index; the repository is not queried.
This feature provides enhanced performance for the query. The general syntax accepted
for an FTDQL query is shown in the formal syntax description. The syntax constraints
Select
on particular clauses enforced for an FTDQL query are listed in the Usage Notes sections
describing each clause. (A summary of the rules is found in Table 107, page 428.)
An FTDQL SELECT statement must be a standalone statement. That is, SELECT
statements embedded as a subselect in another DQL statement are never executed as
FTDQL SELECT statements. Nor are unioned SELECT statements executed as FTDQL
SELECT statements. All FTDQL SELECT statements must include one of the following:
• A SEARCH clause
• The keyword SCORE, SUMMARY, or TEXT in the list of selected values
• The DQL hint ENABLE(FTDQL)
A query that conforms to the FTDQL syntax rules is automatically executed as an FTDQL
query. If you are wondering whether a particular query conforms to the rules, you can
include the ENABLE(FTDQL) hint in the query. If the query conforms, the hint has no
effect and the query is executed as an FTDQL query. If the query does not conform,
Content Server returns an error.
If you do not want a particular query to execute as an FTDQL query even though it
conforms to the FTDQL syntax, include the ENABLE(NOFTDQL) in the query.
Note: A query that does not conform to the FTDQL syntax and does not include the
ENABLE(FTDQL) hint is executed as a standard SELECT query. It does not return
an error.
If an FTDQL query contains references to aspect properties, those properties must be
indexed. Aspect properties are not indexed by default. You must explicitly declare them
for indexing. Use Documentum Application Builder or an ALTER ASPECT statement
to do so.
FTDQL metadata queries that contain LIKE predicates with pattern matching or
on metadata that contains underscores in the values may return different results
than non‑FTDQL queries on the same metadata. This occurs because the index
server processes FTDQL queries against metadata and the database server processes
non‑FTDQL queries against metadata.
FTDQL queries are not affected by the distinct_query_results key in the server.ini.
Setting this key to T (TRUE) does not affect how an FTDQL query is processed.
Referencing nonqualifiable properties

Non‑qualifiable properties (those stored in a property bag) can be referenced in SELECT
statements. They may appear in the selected values list. However, they may not be
referenced in an expression. Nor may they appear in a WHERE clause unless the query
is an FTDQL query.
Referencing aspect properties

To reference an aspect property in a SELECT statement, you must qualify the property
name with the name of the aspect for which it is defined. For example, suppose you have
Select
an aspect named grant_validation, with a property defined for it named grant_amount.

To select the grant amount, reference the property as follows in the selected values list:
grant_validation.grant_amount
For example:
SELECT grant_validation.grant_amount FROM education_grants
....
If the query has multiple object types in the FROM clause, any aspect properties
referenced in the selected values must be also qualified with the type name. For example,
assuming that grant_validation and salary_calc are names of aspects:
SELECT education_grants.grant_validation.grant_amount,
dm_user.research_personnel.salary_calc
FROM education_grants, dm_user
...
The query result column that contains the selected aspect property value is named with
the fully qualified name as specified in the selected values list.
The ALL and DISTINCT keywords

The optional ALL and DISTINCT keywords determine whether the SELECT statement
returns duplicate rows. ALL returns all rows, including any duplicates. DISTINCT does
not return duplicate rows. If neither keyword is included, the default is determined
by the server’s default behavior. (The server’s default behavior is determined by the
distinct_query_results flag in the server’s server.ini start‑up file.)
The DISTINCT keyword is ignored if the SELECT statement also includes an IN
DOCUMENT or IN ASSEMBLY clause. The server issues a warning if the statement
includes both the DISTINCT keyword and an IN DOCUMENT or IN ASSEMBLY clause.
The warning is also issued if the server’s default setting is not to return duplicates and
the query contains an IN DOCUMENT or IN ASSEMBLY clause.
Selecting property values
Select object property values by specifying the property’s name as a selected value. The
properties you specify must belong to an object type identified in the FROM clause. The
properties can be either single‑valued or repeating properties. Repeating properties,
page 138, contains guidelines for selecting repeating property values.
You cannot select any of the following properties if you are querying audit trail entries
unless you have Superuser or View_audit privileges:
• acl_name • object_name
• acl_domain • object_type
Select
• property_list • owner_name
• property_list_id • session_id
• chronicle_id • version_label
The following statement returns the value of title, a single‑valued property, for all
documents in the repository:
SELECT "title" FROM "dm_document"
This next example returns the value of authors, a repeating property, from all documents
that have bread as their subject:
SELECT "authors" FROM "dm_document"
WHERE "subject"='bread'
You can use an asterisk (*) to select a predefined set of system‑defined properties for the
object. Refer to The asterisk (*) as a selected value, page 148 for details.
Selecting nonqualifiable properties

Non‑qualifiable properties can be referenced in the selected values list. However, you can
reference them only as an individual selected value, by name. They cannot be referenced
in expressions or functions, such as an aggregate function, in the selected values list.
Selecting aspect properties

You can select values of properties defined for aspects attached to objects. If the
properties are repeating properties, there are some constraints on the query. For a listing
of these, refer to Repeating properties, page 138.
Repeating properties
Including a repeating property in the selected values list is subject to the following
constraints:
• You cannot select a repeating property and the name of a column from a registered
table unless you also include the DQL hint, ROW_BASED.
Note: The ROW_BASED hint may not be included in FTDQL queries or queries that
reference a lightweight object type in the FROM clause.
• You cannot select a repeating property if there are multiple object types identified in
the FROM clause unless you also include the DQL hint, ROW_BASED.
Select
• If the repeating property is an aspect property or from a lightweight object or its

shared parent, the following constraints also apply:
— If the property is used in an expression, all properties referenced in the
expression must be repeating properties from the same aspect or the same
lightweight object type.
— If the property is referenced in an aggregate function, you must include a
GROUP BY clause that references r_object_id and only r_object_id.
— The query must include r_object_id in the selected values list.
— The query may not be a subquery.
You can select both repeating and single‑valued properties in the same statement. If you
do, the format of the returned results varies depending on how the query is written. The
results can be returned with a separate result row for each value returned for a selected
repeating property or the result rows can be returned in a master‑detail format, with
each row representing the values, including all repeating values, for one object.
To return results by object ID
To obtain query result objects that include all selected repeating property values for one
object in one query result object, include the r_object_id property in the selected values
list. Additionally, the source list in the FROM clause may contain only item.
To ensure that the results are ordered in either ascending or descending order, you can
include an ORDER BY clause also. Typically, results are returned in ascending order
by default.
Note: Refer to The ORDER BY clause, page 167 for more information about using the
ORDER By clause.
For example, the following statement returns one result object that contains the names of
all three authors in the authors property:
SELECT "r_object_id","object_name","authors"
FROM "dm_document"
WHERE "title" = 'Breads of France'
ORDER BY "r_object_id"
This statement returns the following object:
r_object_id object_name authors

object_id French_breads Jean Connie Corwin
To return each repeating value in an individual result object
To obtain result objects that contain one repeating property value in each object, include
the DQL hint, ROW_BASED, in the query.
Select
For example, suppose you want to obtain the object ID and authors of a document whose
object_name is French Bread, and you want the results in a separate row for each author.
The following query that includes the ROW_BASED hint returns a separate row for each
returned value for the authors property:
SELECT "r_object_id","authors" FROM dm_document
WHERE "title" = 'Breads of France'
ENABLE(ROW_BASED)
Assuming that there are three authors, named Jean, Connie, and Corwin, the returned
rows are:
r_object_id authors
0900000334fa21c3 Jean
0900000334fa21c3 Connie
0900000334fa21c3 Corwin
Additionally, if the query has a WHERE clause qualification that references a value in the
selected repeating property, then the query will return only the row that contains that
value. For example, suppose you execute the following statement:
SELECT "r_object_id","title","authors" FROM dm_document
WHERE "authors" = 'JPierpont'
ENABLE(ROW_BASED)
The query returns one row:
r_object_id title authors

0900000334fa21c3 English Muffins JPierpont
FTDQL requirements
The requirements for single or repeating properties in a selected values list for an FTDQL
query are the same as those for a standard query.
Selecting column values
Select column values by specifying column names as values. The columns must belong to
a RDBMS table that you identify in the FROM clause. You can use column names to select
some or all of the column values, or you can use an asterisk to retrieve all column values.
Note: The account from which Content Server was installed must have SELECT
privileges on the underlying table in the RDBMS before you can use DQL to select
from an RDBMS table. Additionally, to query a registered table, you must have
DM_TABLE_SELECT table permission and at least Browse object‑level permission for
Select
the dm_registered object representing the table. If the SELECT statement includes a
SEARCH clause, your object‑level permission must be at least Read.
FTDQL requirements
The requirements for column values in a selected values list for an FTDQL query are
the same as those for a standard query.
Scalar, aggregate, and date functions as selected values
You can include scalar, aggregate, and date functions to manipulate returned values.
A scalar function operates on one value. The DQL SELECT statement accepts three
scalar functions:
• UPPER, which returns the uppercase form of a character string
• LOWER, which returns the lowercase form of a character string
• SUBSTR, which returns a subset of a specified character string
An aggregate function operates on a set of values and returns one value. The DQL
SELECT statement accepts five aggregate functions:
• COUNT, which returns the number of values in a group of values
• MIN, which returns the minimum value in a group of values
• MAX, which returns the maximum value in a group of values
• AVG, which returns the average value of a group of values
• SUM, which returns the total of all values in a group of values
For example, the following statement returns the number of documents owned by the
user horace:
WHERE "owner_name"='horace'
If an aggregate function references a repeating property from a lightweight object or its

shared parent or from an aspect, the query must also have r_object_id in the selected
values list and must include a GROUP BY clause that references r_object_id and only
r_object_id.
An aggregate function cannot reference a non‑qualifiable property.
You cannot include an aggregate function if your statement includes an IN DOCUMENT
clause unless the statement also includes the USING ASSEMBLIES clause and an
assembly exists for the virtual document itself. (Refer to Content Server Fundamentalsfor
information about assemblies.) However, in this case, you may prefer to use the IN
ASSEMBLY clause instead of the IN DOCUMENT clause with USING ASSEMBLIES.
Refer to The IN ASSEMBLY clause, page 156 for more information.
Select
A date function manipulates a date in some manner. To use a date function in the
selected values list, use the AS clause to provide an alias for the returned value in the
result object. For example:
SELECT DATETOSTRING("r_modify_date",'yymmdd") AS ModifyDate
FROM "dm_document"
It is recommended that you use the AS clause to alias a return value for any function
referenced in the selected values list. The AS clause, page 149, has information about
the AS clause.
FTDQL requirements
You can include scalar, aggregate, and date functions in the selected values list of an
FTDQL query.
MFILE_URL function as a selected value
The MFILE_URL function returns URLs for the content files and renditions associated
with the objects returned by the SELECT statement. The function has three arguments
that are used to control which URLs are returned. For a description of the function and
its arguments, refer to The MFILE_URL function, page 28.
You can include the MFILE_URL function in the selected values list of an FTDQL query.
Arithmetic expressions as selected values
You can include arithmetic expressions to perform calculations on the returned values.
Arithmetic expressions are expressions that use arithmetic operators to form the
expression, such as:
property A + property B
column C * column D
(2 * column B) property F
property X + 4
The following statement returns the total of all rental charges paid in June, including
regular rents and late charges:
SELECT "rent_received" + "late_charge_total" AS month_total
FROM "yearly_rent_records"
WHERE "mon" = 'june'
The expression cannot reference a non‑qualifiable property.
FTDQL requirements
Arithmetic expressions are not allowed in the selected values list in an FTDQL query.
Select
Keywords as selected values
Keywords are words that have a special meaning for the server. The majority are full‑text
keywords. That is, the values they return are property values stored in the full‑text index
or values computed during a full‑text search. Three keywords return information about
an object’s relationships to other objects in a virtual document. The remaining keywords
determine whether an object is a replica, return the current user name, and return the
URL to an object’s thumbnail file.
It is not necessary to include a SEARCH clause in the query to include a full‑text key in
the selected values list. However, for some keywords such as TEXT, the returned values
are not useful unless a SEARCH clause is included.
FullText keywords
The following keywords return information about full‑text indexes.
• CONTENTID
The CONTENTID keyword returns the object ID of the content object representing
the content file that matches the select criteria. (A content object links a content file
to all documents that contain the file.)
• ISCURRENT
The ISCURRENT keyword is a Boolean keyword that returns 1 (TRUE) if the object
is the current version and 0 (FALSE) if the object is not the current version.
• ISPUBLIC
The ISPUBLIC keyword is a Boolean keyword that returns 1 (TRUE) if the object is a
public object (its r_is_public property is TRUE) and 0 (FALSE) if the object is not a
public object.
• OBJTYPE
The OBJTYPE keyword returns the r_object_type of the selected object.
• SCORE
The SCORE keyword returns a document’s relevance ranking as determined by the
index server. If an ORDER BY clause is not included in the query, the returned
document order is by descending score.
• SYSOBJ_ID
The SYSOBJ_ID keyword returns the object ID of the objects returned with a fulltext
search. It is the object ID stored in the fulltext index for the object.
Select
• SUMMARY
The SUMMARY keyword returns a summary of each document returned by the
SELECT statement. The summary is up to 4096 bytes from the document, chosen by
the Full‑Text Engine. For example, the following statement returns a summary of the
document whose name is Company History:
SELECT SUMMARY FROM "dm_document"
WHERE "object_name"='Company History'
• TEXT
The TEXT keyword returns the variant text forms to which a specified term was
match, to return a particular document. The values are returned as a repeating
property. For example, if the search string specifies “talk”, the index server may
return documents that contain the words “talking” or “talked”. If so, then TEXT
would return those forms of the word “talk”.
FTDQL requirements
All the keywords classified as fulltext keywords can be included in an FTDQL query.
Virtual document keywords

The following keywords return information about relationships in a virtual document.
• CONTAIN_ID
The CONTAIN_ID keyword returns the object IDs of the containment objects
associated with the components of a virtual document. The CONTAIN_ID keyword
cannot return containment IDs for components that are found by searching an
assembly. Consequently, if the SELECT statement includes an IN DOCUMENT
clause with the USING ASSEMBLIES option, the containment IDs of any components
found using an assembly will be zeros (’0000000000000000’).
For example, suppose you have a virtual document, A, with one component,
B. B is also a virtual document with four components and an assembly. If you
execute a SELECT statement to retrieve the containment IDs of the components of
A and include the DESCEND keyword, you receive the containment IDs for A’s
components at all levels. If the SELECT statement includes DESCEND and USING
ASSEMBLIES, you receive only the containment ID for B. (B’s containment object
links it to A.) Because the direct components of B are found using an assembly,
their containment IDs are not returned.
Select
• DEPTH
The DEPTH keyword returns a component’s level within a virtual document.
You can only use the DEPTH keyword if the SELECT statement includes the IN
DOCUMENT clause and the clause includes the DESCEND keyword.
To illustrate its use, suppose the following query is executed against the virtual
document shown in Figure 1, page 145 :
SELECT "r_object_id", DEPTH FROM "dm_document"
IN DOCUMENT ID('object_id_A') DESCEND
Figure 1. Sample virtual document
The statement returns
Object ID DEPTH
A 0
B 1
D 2
C 1
Select
• PARENT
The PARENT keyword returns the object ID of the object that directly contains
a direct or indirect component of a virtual document. You can only include
the PARENT keyword in the value list if the SELECT statement contains an IN
DOCUMENT clause.
For example, suppose the following query is executed against the virtual document
shown in Figure 1, page 145:
SELECT "r_object_id", PARENT FROM "dm_document"
IN DOCUMENT ID('object_id_A') DESCEND
The statement returns the object IDs and parents of each component of the virtual
document:
Object ID PARENTS
A A
B A
D B
C A
Note that a virtual document is always considered to be its own parent.

FTDQL requirements
You may not use any of the keywords classified as virtual document keywords in
an FTDQL query.
Miscellaneous keywords
The following keywords return miscellaneous information.
• ISREPLICA
The ISREPLICA keyword is a Boolean keyword that returns 1 (TRUE) if the returned
object is a replica and 0 (FALSE) if the object is not a replica. (Replica is the term
used to describe any object in the repository that has been placed in the repository
as a copy of an object from another repository. Only environments using object
replication have replicas.)
You can only include the ISREPLICA keyword in the value list of the outermost
SELECT statement. You cannot use ISREPLICA in a subquery.
Select
• THUMBNAIL_URL
The THUMBNAIL_URL keyword returns the URL to a thumbnail file. Use
THUMBNAIL_URL in a SELECT statement’s selected values to return the URL to the
thumbnail associated with the returned objects. For example:
SELECT object_name,THUMBNAIL_URL FROM dm_document
WHERE FOLDER('/Corporate Objectives')
The statement returns the documents in the folder Corporate Objectives. If the
content of any of returned document has an associated thumbnail, the URL to
that thumbnail is returned also. If a document has multiple content pages with
thumbnails, the keyword returns only the thumbnail associated with the first content
page that has a thumbnail.
The URL contains the following information:
— The base URL defined for the thumbnail storage area
— A path relative to the storage area identified in the store property that points to
the thumbnail file
— A store property that identifies the storage area containing the thumbnail
If the storage area’s require_ticket property is TRUE, the URL also contains a
ticket that contains an encryption of the path plus a time stamp. The ticket is
valid for five minutes, which means that the URL is good only for five minutes.
For example:
http://myserver.documentum.com:8080/getThumbnail?
path=00232803/80/00/01/Ob.jpg&store=thumbnail_store_01&ticket=8002DWR670X
http://myserver.documentum.com:8080/getThumbnail? is the base URL.
path=00232803/80/00/01/Ob.jpg specifies the path to the file.
store=thumbnail_store_01 identifies the storage area.
ticket=8002DWR670X is the optional ticket.

• USER
The USER keyword returns the current user’s user name.
FTDQL requirements
The THUMBNAIL_URL keyword is the only keyword in the miscellaneous category
that is acceptable in an FTDQL query. You may not use the IS_REPLICA or USER
keywords in an FTDQL query.
Select
The asterisk (*) as a selected value
If the FROM clause references only registered tables or only object types, you can use
an asterisk (*) in the values list.
For registered tables, the asterisk returns all columns in the table.
For lightweight object types:
• If the LITE keyword is included in the query, the asterisk returns all single‑valued
properties of the lightweight object.
• If the LITE keyword is not included in the query, the asterisk returns all single‑valued
properties of both the lightweight object and its shared parent.
For non‑lightweight object types, what is returned by an asterisk depends on whether
or not the ROW_BASED hint is included in the query. If the hint is not included, an
asterisk returns values only for the first object type listed in the FROM clause. The values
returned depend on the object type:
• For objects that are subtypes of persistent object type, the asterisk returns:
— All read/write single‑valued properties
— The r_object_id property
• If the object type is SysObject or a SysObject subtype, in addition to the properties
returned for a persistent object, the asterisk also returns:
— r_object_type
— r_creation_date
— r_modify_date
— a_content_type
If the query includes the ROW_BASED hint, the asterisk returns the values of all
properties of all object types in the FROM clause. For example, the following query
returns all property values from both object types for returned objects:
SELECT * FROM dm_user,dm_group
If you want to limit the returned values to only the property values for a particular type
in the FROM clause, qualify the asterisk with the type. For example:
SELECT a.*, b.r_object_id FROM dm_document a, mydoc b
WHERE a.subject = b.title ENABLE(ROW_BASED)
In the above example, the asterisk returns the values only for properties from
dm_document objects. You can use an asterisk in this manner only when the
ROW_BASED hint is included in the query.
An asterisk does not return values of properties defined for any aspects attached to
an object.
Select
FTDQL requirements
You may not use an asterisk as a selected value in an FTDQL query.
The AS clause
The AS clause lets you name the properties of the query result objects that represent the
returned results. For example, suppose you issue the following SELECT statement:
SELECT "a"+"b" AS total FROM "accts"
Total is assigned as the name of the query result object property that contains the
returned a + b values.
When the statement returns the value of a property or column name, providing a name
for the query result property is optional. The system assigns the property or column
name as the default name. If you provide a name, the name must consist of ASCII
characters.
When the statement includes a function, arithmetic expression, or a keyword, you must
specify a name if you are running against MS SQL Server or Sybase, and we recommend
that you also do so if you are running against Oracle or DB2.
MS SQL Server and Sybase do not provide default names when values are functions,
arithmetic expressions, or keywords. For example, suppose you issue the following
statement:
WHERE "subject" = 'cake'
Your return value would be:

______________
integer
Notice that there is no name above the integer return value.
For DB2, if you don’t provide a name, the returned column is named with its position in
the selected values list. For example, in the above SELECT example, the count would be
returned in a column named 1.
Because the server does not allow duplicate property names in an object, if you assign
the same name to more than one property, the system ignores all subsequent occurrences
of the name and assigns those properties different names.
Oracle provides a default name, but it is difficult to predict what forms the names
for selected functions, arithmetic expressions, or keywords will have. Consequently,
explicitly assigning a name is recommended.
Select
FTDQL requirements
You may use the AS clause in an FTDQL query.
The FROM clause
The FROM clause defines which items are searched. Both the PUBLIC keyword and
the source list restrict the search.
PUBLIC keyword
The PUBLIC keyword restricts the search to objects for which the r_is_public property is
those documents for which ISPUBLIC is TRUE. When the server searches public objects
only, it uses the setting of r_is_public for security checks.
You may include PUBLIC in an FTDQL query.
Including PUBLIC increases the search performance.
Source list
A source list defines which object types and which RDBMS tables to search. The source
list for a standard query can include:
• One or more object types, to a maximum of 10 types
Any object type except those internal object types that represent aspect properties
may be specified.
• One or more RDBMS table names
The total number of object types and tables that you can include in the FROM clause
is constrained by the RDBMS. Each relational database has a limit on the number of
tables that can joined in one query. In the underlying RDBMS query, for each object type
in the FROM clause, all the _s tables in the type’s hierarchy plus any needed indexes
are candidates for inclusion in the underlying query. If the query references repeating
properties, the _r tables are included also.
For registered tables, all object types included in the view’s definition are included in
the query.
DQL passthrough hints included in the source list are applied only to the type or
table after which the hint appears. For portability, you can include hints for multiple
databases. If you include hints for multiple databases, only the hints that are applicable
to the database receiving the request are used.
For more information about using passthrough hints, refer to Passthrough hints, page
405.
Select
Including type names in the source list

Use the following syntax to specify a type name:
type_name [(ALL)|(DELETED)|(LITE)] [correlation_variable]
The type name argument identifies the object type to search. The server searches objects
of the specified type and all subtypes. For example, to search all SysObjects, specify
dm_sysobject. The server searches dm_sysobject and all of its subtypes, such as
dm_document, dm_process, and so forth.
The keyword ALL directs the server to search all versions of each object. The keyword
DELETED directs the server to search all versions of each object including any versions
for which i_is_deleted is set to TRUE. (This property is set to TRUE if you delete the
object and it is the root version of a version tree). The keyword LITE directs the server to
search only the properties in the lightweight type, otherwise the server also searches the
properties in the shareable parent and the supertype(s). If you specify LITE, then you
must only specify properties in the lightweight type. You must enclose ALL, DELETED,
and LITE in parentheses.
If the FROM clause includes neither ALL nor DELETED, the server searches only the
CURRENT version.
The value of correlation_variable is a qualifier for the type name that is used to clarify
property references in the query.
Any user can specify any object type in a query with two exceptions. The first exception
is the type dmi_audittrail_attrs. To specify that type, you must have either Superuser or
View Audit privileges. The second exception are the object types representing aspect
properties. These types cannot be referenced in the FROM clause by any user.
The server searches only objects within that specified type that are owned by the user
or objects to which the user has access. Whether a user has access depends on the
object‑level permissions of the objects. The user must have at least Browse permission on
an object for the object to be included in a query run by the user. If the query includes a
SEARCH clause, the user must have at least Read permission on the object. (For a full
description of server security, refer to the Content Server Administration Guide.)
Including multiple object types is subject to the following constraints:
• The selected values list cannot contain repeating properties unless the ROW_BASED
hint is included in the query.
Select
• If the selected values list contains an asterisk (*), only the first type’s properties will
be expanded unless the ROW_BASED hint is included in the query.
The asterisk (*) as a selected value, page 148, contains details about including an
asterisk in the selected values list.
• The query cannot include a SEARCH clause.
• Unqualified property names in the query are disambiguated from left to right, as the
object types appear in the FROM clause.
• It the query includes an IN DOCUMENT clause, the object types must join in
one‑to‑one relationship.
• If the query includes an IN DOCUMENT or IN ASSEMBLY clause or a TYPE or
FOLDER predicate, the clause or predicate is applied to only one type in the join,
and that type will be the first object type identified in the FROM clause.
Including table names in the source list
You can include one or more RDBMS table names in the FROM clause of a standard
query. The syntax is:
[owner_name.]table_name [correlation_variable]
The owner_name argument identifies the owner of the table. You must include the owner
name if you are not the owner of the table. If the owner is the DBA of the database,
you can use the alias dm_dbo as the owner name. (Using dm_dbo when appropriate
makes your statement portable across databases.) If the owner name is unspecified, the
current user is assumed.
You must be a superuser to include an unregistered RDBMS table in the list. Any user
with appropriate permissions can include a registered table.
table_name is the name of the table that you want to search.
correlation_variable is a qualifier for the table name used to clarify column references
in the query.
Clarifying type and table names
Type and table names can be the same. In such instances, the server must distinguish
which name identifies a type and which identifies a table. The server uses the following
rules for distinguishing between type and table names:
• If (ALL) or (DELETED) is present, the name is a type name.
• If ownername is present, the name is a table name.
• All other cases are ambiguous references. In such cases, the server checks to see
whether the name is a type name. If it is, the name is assumed to be a type.
The values in the source_list argument are processed from left to right. Consequently,
if you include tables and types with the same name in the FROM clause, be sure to
Select
qualify the table name with its owner’s name. This will ensure that the server does not
mistakenly assume that the table name is the type name.
To illustrate, suppose you have an object type named legal_docs and a registered table
of the same name. The following statement shows one correct way to include them
both in one SELECT statement:
SELECT a."r_object_id", b."client"
FROM "legal_docs" a, jolenef."legal_docs" b
The first legal_docs (with correlation name a) is a type name. The server knows the
second is a registered table because an owner name is specified. Note that correlation
variables should be used in this case to clarify column references.
The following statement is valid because billing_docs is not found to be a type and so is
assumed to be a registered table:
SELECT a."r_object_id", b."client"
FROM "dm_document" a, "billing_docs" b
In the following statement, the server assumes that the query references the legal_docs
type, not the registered table, because no owner name is specified and there is a type
called legal_docs:
SELECT a."object_id", b."client"
FROM "legal_docs" b, "dm_document" a
FTDQL constraints on the source list
Observe the following rules if you want to execute the query as an FTDQL query:
• You can only reference one object type and that type must be dm_sysobject or a
dm_sysobject subtype.
• You cannot reference a registered table in the source list.
The IN DOCUMENT clause

Note: You may not include an IN DOCUMENT clause in an FTDQL SELECT statement.
The IN DOCUMENT clause lets you use the SELECT statement to perform the following
operations:
• Identify only the directly contained components of a virtual document
• Identify the indirectly contained components that reside in the current repository
with the virtual document
If a component is a folder that doesn’t reside in the current repository, the query
returns the object ID of the folder’s mirror object in the repository, but not any folders
or documents that the remote folder contains.
• Assemble a virtual document
• Identify the virtual documents that directly contain a particular object
Select
If the value list for the SELECT statement contains a repeating property and the
statement contains an IN DOCUMENT clause, the server automatically removes any
duplicates of the repeating property.
You cannot include an ORDER BY clause when you include an IN DOCUMENT clause.
The syntax of the IN DOCUMENT clause is:
IN DOCUMENT object_id [VERSION version_label]
[DESCEND][USING ASSEMBLIES]
[WITH binding condition]
[NODESORT BY property {,property} [ASC|DESC]]]
Specifying the virtual document

To identify which virtual document to search, use either the document’s object ID or the
combination of an object ID and a version label. When you use only the object ID, the
server searches the version identified by that object ID. When you use a version label
in addition to an object ID, the server searches that version of the object. Note that this
version may not be the same as the version identified by the object ID.
If the SELECT statement is not a subquery, specify the object_id using the special ID
function and the actual object ID of the virtual document. For example:
IN DOCUMENT ID('object_id')...
If the SELECT statement is a subquery, you can also specify the object_id using a
correlated r_object_id property reference. For example:
SELECT "r_object_id" FROM "dm_document" x
WHERE EXISTS
(SELECT * FROM "dm_document"
IN DOCUMENT x."r_object_id"
WHERE "object_name"='Chapt1')
The VERSION option lets you specify a version label. This label can be assigned to any
version in the version tree that contains the specified virtual document. If you do specify
a label, the server searches the specified version rather than the version identified by
the object ID.
The DESCEND option

The keyword DESCEND directs the server to search the virtual document’s hierarchy,
including all components directly or indirectly contained in the virtual document.
Otherwise, the server searches only those components that are directly contained.
You cannot use the DESCEND keyword in the IN DOCUMENT clause if the SELECT
statement is a subquery.
The USING ASSEMBLIES option

An assembly defines the components of a particular version of a virtual document at a
particular time (the time the assembly was created). Creating an assembly ensures that a
Select
particular version of a virtual document always contains the same material. (Refer to
Content Server Fundamentals for information about creating assemblies.)
If a component selected for inclusion is a virtual document and the USING ASSEMBLIES
clause is included, the server determines whether an assembly is defined for that
component. If so, the server uses the information in the assembly as the definition of the
component’s composition.
Refer to in Content Server Fundamentals for a full discussion of assemblies.
The WITH option

The WITH option lets you identify which version of a virtual document’s component you
want to include in the document. The syntax of the WITH option is:
WITH binding condition
where binding condition is one or more expressions that resolve to a single Boolean
TRUE or FALSE. The expressions can include comparison operators, literals, qualifiable
property names, column names, scalar and date functions, arithmetic expressions, and
any predicates except SysObject predicates. Multiple expressions in the condition are
joined using logical operators.
The condition defined by the WITH option is applied to any component of the virtual
document that was added without a version being specified at the time of its addition.
For example, suppose you add component C to virtual document A without specifying
a particular version of component C. Later, when you assemble virtual document A,
you can use the WITH clause condition to determine which version of component C
to include in the document. You may want to include the version that has the word
accounting as a keyword or the version that carries the symbolic label CURRENT. Each
time you assemble the document, you can select a different version of component C.
Choosing a version for inclusion at the time of actual assembly is called late binding.
(For more information about late binding, refer to Content Server Fundamentals.)
More than one version of a component may qualify for inclusion in the virtual document.
To resolve this, you can include the NODESORT BY option in the IN DOCUMENT
clause or you can allow the server to make a default choice. If you allow the server to
make the choice, the server includes the version with the smallest object ID; that is, the
earliest version of the component.
The NODESORT BY option

The NODESORT BY option works in conjunction with the WITH option to identify
one version of a particular component for inclusion in a virtual document. (In some
instances, more than one version of a component may fulfill the condition imposed by
the WITH option.) The NODESORT BY option sorts the versions by the value of one
or more properties. The server includes the first version.
The syntax of the NODESORT BY option is:
Select
NODESORT BY property {,property} [ASC|DESC]
where property is any qualifiable property belonging to the component. You can sort
in ascending (ASC) or descending (DESC) order. If you do not specify a sort order,
the default is ascending (ASC).
If you use the NODESORT BY option and two or more versions still qualify for inclusion,
the server picks the version having the smallest object ID. This situation could occur if
two or more versions have exactly the same values in the properties specified in the
NODESORT BY option.
The IN ASSEMBLY clause

Note: You may not include the IN ASSEMBLY clause in an FTDQL SELECT statement.
The IN ASSEMBLY clause allows you to identify an assembly associated with a particular
document. An assembly is a snapshot of a virtual document at a particular point in time
and under conditions defined when the assembly was created. Using the IN ASSEMBLY
clause means that the SELECT statement queries the virtual document represented by
the assembly; however, the server uses only the components found in the assembly,
rather than recursively searching the virtual document’s hierarchy.
You can also use this clause to identify a single component of a virtual document and
any components contained by that component. The component must be contained in
the assembly.
The IN ASSEMBLY clause is more flexible than the IN DOCUMENT clause. For example,
you can include aggregate functions such as COUNT or MAX in the value list when you
use the IN ASSEMBLY clause. You cannot include aggregate functions when a SELECT
statement includes an IN DOCUMENT clause.
The syntax of the IN ASSEMBLY clause is:
IN ASSEMBLY [FOR] document_id [VERSION version_label]
[NODE component_id] [DESCEND]
where document_id identifies the document with which the assembly is associated. Use
the document’s object ID for this argument, specified as an ID literal:
ID('object_id')
Note: You can create an assembly for a virtual document and assign that assembly to
another document. In such cases, the value of the document_id argument identifies the
document to which the assembly is assigned, not the virtual document that the assembly
represents.
If the specified document does not have an associated assembly, the statement fails
with an error.
The VERSION option lets you specify a particular version of a document. If you include
a version label, the server finds the version of the document carrying that label and
Select
uses the assembly associated with that version. You can specify either a symbolic label
or an implicit label.
The NODE option allows you to identify a particular component of a virtual document.
Use the component’s object ID, specified as an ID literal:
ID('component_id')
The component must be contained in the assembly.

You cannot include the NODE option if the SELECT statement contains an aggregate
function in the value list or if the SELECT statement is a subselect or subquery.
The DESCEND keyword directs the server to return not only directly contained
components but also any indirectly contained components that meet the criteria in the
statement. If you do not include this keyword, the server returns only directly contained
components of the document or component.
The SEARCH clause
The SEARCH clause identifies a subset of the full‑text indexed documents. When
you include a SEARCH clause, Content Server submits the query to the index server,
which returns all objects that meet the SEARCH clause condition. The index server
searches both content files and indexed metadata (property values) for matches with
the specified condition.
The syntax of the SEARCH clause for a standard query is:
SEARCH [FIRST|LAST]fulltext_search_condition
[IN FTINDEX index_name {,index_name}]
The syntax of the SEARCH clause for an FTDQL query is:

SEARCH fulltext_search_condition
[IN FTINDEX index_name {,index_name}]
The FTDQL SEARCH clause may not contain either the FIRST or LAST keywords.
The fulltext_search_condition has two variants. The first, preferred syntax is described in
SEARCH DOCUMENT CONTAINS, page 158. The second syntax variant is described in
SEARCH TOPIC, page 160.
FIRST and LAST keywords

The FIRST and LAST keywords determine when the search is conducted. These
keywords are only valid in standard SELECT queries. You may not include them if
the query is an FTDQL query.
If you include FIRST, the server runs the full‑text search query first and then applies
the SELECT statement. For example, suppose legal_documents is a subtype of
dm_document. The following statement first searches the full‑text index for all
Select
documents that have the word fiduciary in their content and then finds the members of
that group that are also legal_documents:
SELECT "object_name" FROM "legal_documents"
SEARCH FIRST DOCUMENT CONTAINS 'fiduciary'
If you include LAST, the server first searches the repository for all objects that meet the
SELECT criteria and then applies the criteria in the SEARCH clause. For example, the
following statement first finds all legal_documents authored by G. Oliphant and then
finds the members of that group that contain the word fiduciary:
SELECT "object_name" FROM "legal_documents"
SEARCH LAST DOCUMENT CONTAINS 'fiduciary'
WHERE ANY "authors"='G.Oliphant'
The default behavior is to search the full‑text index first. If you include a full‑text
keyword in the selected values list, the full‑text search is conducted first even if LAST is
specified in the SEARCH clause.
SEARCH DOCUMENT CONTAINS

The SEARCH DOCUMENT CONTAINS syntax is the preferred way to specify a fulltext
search condition in a SEARCH clause.
The syntax is:
SEARCH [FIRST|LAST]DOCUMENT CONTAINS [NOT] search_string
where search_string has the following syntax:

[NOT]'word' {AND|OR [NOT] 'word'}
word may be a word, a phrase. It may also be a list of words or phrases, or both,
separated by spaces and quoted appropriately. For more information about this syntax,
refer to Specifying words and phrases in SEARCH DOCUMENT CONTAINS, page 158.
The complex syntax using logical operators is not recommended as future support may
be dropped for this syntax and replaced with a different syntax. However, this syntax
is currently supported.
Specifying words and phrases in SEARCH DOCUMENT CONTAINS
Including a list of words or phrases in a SEARCH DOCUMENT CONTAINS clause
returns those documents whose content contains the one or more of the specified words
or phrases. The documents are returned in order of importance.
A word can be any character string that does not include spaces or punctuation. For
example, the following statement finds all indexed documents that contain the word
yeast:
SELECT * FROM "dm_documents"
SEARCH DOCUMENT CONTAINS 'yeast'
To search for multiple words, separate each word in the list with a space. For example,
the following query returns documents that have yeast or cake or both words in their
content or metadata:
Select

SEARCH DOCUMENT CONTAINS 'yeast cake'
If you want to include a single quote in the search string, you must escape the quote
with another single quote. For example:
SEARCH DOCUMENT CONTAINS 'O''Malley'
To search on a phrase, enclose the phrase in double quotes inside the quoted search
string. For example, the following query returns all documents that include the phrase
“blend butter and sugar”:
SEARCH DOCUMENT CONTAINS '"blend butter and sugar"'
Note: You can use single quotes to enclose a phrase, but if you do so, you must escape
the quotes with single quotes.
You can combine words and phrases in the same search string. For example, the
following query returns documents that contain the word “yeast” or the phrase “blend
butter and sugar” or both:
SEARCH DOCUMENT CONTAINS 'yeast "blend butter and sugar"'
The following example searches for documents that contain yeast but not butter:
SEARCH DOCUMENT CONTAINS 'yeast' AND NOT 'butter'
Case sensitivity
All searches conducted by the index server are case insensitive.
For example, suppose you issue the following query:
SELECT owner_name,r_creation_date FROM dm_document
SEARCH DOCUMENT CONTAINS 'budget'
The query returns all documents that contain, either in content or metadata, the word
budget in lowercase or uppercase or in any combination (Budget, buDget, budgeT,
and so forth).
Accent and diacritical marks
Some languages use accents and diacritical marks on some characters or syllables in
words. Searches are insensitive to accent and diacritical marks. When you search on a
word or phrase, the search returns all objects that contain the word or phrase, even if
some matches also contain an accent or diacritical mark. Similarly, when you search on a
word or phrase that contains such marks, the search ignores the marks and returns all
objects that contain the word or phrase, spelled with or without the accent or diacritical
mark.
For example, suppose you issue the following query:
SEARCH DOCUMENT CONTAINS 'cote'
Select
The query returns all documents that contain, in metadata or content, the word cote,
including those with instances of the word with accents or diacritical marks (côte, côté,
and so forth).
Now, suppose you issue the following query that specifies a search term that includes
an accent:
SEARCH DOCUMENT CONTAINS 'coté'
That query also returns all documents that contain, in metadata or content, the word
cote, including those with instances of the word with accents or diacritical marks (côte,
côté, and so forth).
Asterisk as wildcard character
You can use the asterisk (*) as a wildcard character in a search string. The asterisk
matches any string of letters. You can use it in any position in the string. For example,
foo* matches any word that begins with “foo”. The string *foo* matches any word that
contains “foo” in its sequence of letters. The string faa*foo matches any word that begins
with faa and ends with foo.
You may also use the asterisk as a wildcard in a phrase search. For example, suppose
you provide the following search string:
'"n* is th* time*"'
That string matches phrases such as “now is the time”, “nothing is thoroughly timed”,
and “November is thinking time”.
SEARCH TOPIC
Note: Although the SEARCH TOPIC syntax is supported for backwards compatibility,
queries are not guaranteed to behave exactly as in releases prior to Release 5.3 because
the syntax in the topic_query_string is translated by the new index server introduced in
Release 5.3. It is strongly suggested that new applications use the SEARCH DOCUMENT
CONTAINS syntax.
The syntax of the clause is:
SEARCH [FIRST|LAST]TOPIC 'topic_query_string'
The query string is passed to the index server, which translates and executes the query.
The IN FTINDEX option

The IN FTINDEX option is included for future use. It allows you to identify which
index to search. However, Content Server only supports one index for a repository. If
you include this clause, specify the name of the index associated with the repository.
The index name is the name of its fulltext index object. If the index name begins with a
digit, enclose the name in single quotes.
Select
The WHERE clause
Use the WHERE clause to restrict which objects are returned. For example, the following
statement selects the title of every document but only returns the titles of documents
owned by the current user:
SELECT "title" FROM "dm_document"
WHERE "user_name" = USER
The syntax of the WHERE clause is:

WHERE qualification
The qualification argument consists of one or more expressions that resolve to a single
Boolean TRUE or FALSE. The expressions can include comparison operators, literals,
qualifiable property names, column names, scalar and date functions, arithmetic
expressions, predicates, and full‑text keywords. Multiple expressions are joined together
using the logical operators. (Chapter 1, DQL Language Elements, contains descriptions
of all accepted comparison and arithmetic operators, predicates, functions, and logical
operators. Full‑text keywords are described in Full‑Text keywords, page 143.)
A qualification can also include a subquery:
WHERE ANY "authors" IN
WHERE "r_is_group" = TRUE)
The qualification can be simple or as complex as necessary. For example, the following
WHERE clause is simple:
SELECT * FROM "dm_workflow"
WHERE "supervisor_name" = 'horace'
This next example contains a more complex qualification:

SELECT "r_object_id", "title," FROM "dm_document"
WHERE "r_creation_date" >= DATE('01/01/99','mm/dd/yy')
AND "r_modify_date" <= NOW
The next example references an aspect property. Note that the property name is fully
qualified with the name of the aspect. All references to aspect properties must be
qualified with the aspect name.
SELECT "r_object_id", "title" FROM "dm_document"
WHERE ANY AUTHOR IN ("JohnDoe") and grant_validation.grant_amount>100000
General constraint on the qualification

A qualification cannot reference any of the following properties of audit trail objects
unless you have Superuser or View_audit privileges:
Select
• acl_name • object_name
• acl_domain • object_type
• property_list • owner_name
• property_list_id • session_id
• chronicle_id • version_label
Using repeating properties in qualifications

Referencing repeating properties in a qualification is supported. However, there are
some rules and guidelines. This section discusses those rules and guidelines.
ANY keyword use
If an expression references a repeating property, you must include the ANY keyword in
the expression unless the ROW_BASED hint is included in the query. For example, the
following query includes the ANY keyword because it does not include ROW_BASED:
SELECT "r_object_id","title","subject" FROM "dm_document"
WHERE ANY "authors" IN ('gillian')
If ROW_BASED is included, the query may be written without the ANY predicate:
SELECT "r_object_id","title","subject" FROM "dm_document"
WHERE "authors" IN ('gillian') ENABLE(ROW_BASED)
If you are referencing a repeating property and including a subquery, you can use the
IN or EXISTS keyword after the ANY keyword to control the generated SQL query.
The syntax is:
WHERE ANY [IN|EXISTS] attr_name IN subquery
Including IN or EXISTS may change the generated SQL query and consequently, enhance
performance. IN and EXISTS, page 400 contains an example that shows the differences
between the options in the generated query.
Referencing repeating properties in compound expressions
A compound expression is multiple expressions linked by logical operators. For
example, the following is a compound expression:
object_name = 'book_proposal' AND owner_name = 'john doe'
If two or more expressions in a compound expression reference repeating properties, the

properties must be from the same object type unless the ROW_BASED hint is included in
the query. For example, the following query contains a compound expression that has
two expressions referencing repeating properties from dm_document:
SELECT r_object_id, object_name FROM dm_document
WHERE ANY authors IN ('joe','john') AND ANY keywords LIKE 'eng%'
Select
However, suppose you want to select from two object types and use a compound
expression that referenced repeating properties from both types. To do that, you must
include the ROW_BASED hint:
SELECT a.r_object_id, b.i_acceptance_date
FROM dm_document a, dmi_package b
WHERE a.authors IN ('john doe') AND b.r_package_label = 'APPROVED' ENABLE(ROW_BASED)
Without the ROW_BASED hint, the query would fail with an error stating that the two
repeating properties it references, authors and r_package_label, are not from the same
type.
Additionally, when ROW_BASED is included, it is not necessary to include the ANY
predicate. Including ANY does not generate an error in such cases, but it is not necessary.
Referencing repeating properties in comparison expressions
A comparison expression is an expression that uses a comparison operator, such as = or
>, to compare the values of two properties. The following rules apply when comparing a
repeating property to another property in a qualification:
• You can compare a repeating property to a single‑valued property from the same or
a different object type.
For example, the following queries are legal:
SELECT r_object_id, title FROM dm_document
WHERE ANY authors=object_owner
SELECT a.r_object_id, b.user_name

FROM dm_document a, dm_user b
WHERE ANY a.authors=b.user_name
• You cannot compare a repeating property to another repeating property unless you
include the ROW_BASED hint.
For example, the following query is illegal:
SELECT a.r_object_id,b.r_object_id,a.title
FROM dm_document a,dm_sysobject b
WHERE ANY a.authors = b.keywords
To make that example a legal statement, you must include the ROW_BASED hint:
SELECT a.r_object_id,b.r_object_id,a.title
FROM dm_document a,dm_sysobject b
WHERE ANY a.authors = b.keywords
ENABLE(ROW_BASED)
FTDQL requirements for where clauses

A WHERE clause in an FTDQL query is subject to the following rules:
Select
• Any repeating properties referenced in the clause must be of type string or ID.
• Only the DQL UPPER and LOWER functions are allowed. The functions SUBSTR
and MFILE_URL and all aggregate functions are not acceptable.
• The following predicates are not allowed:
— BETWEEN
— NOT LIKE
— NOT FOLDER
— [NOT] CABINET
— ONLY
— TYPE
• The IN and EXISTS keywords are not allowed.
• Any valid form of the FOLDER predicate (except NOT FOLDER) may be used. The
DESCEND option is also allowed.
• The following rules apply to the LIKE predicate:
— The LIKE predicate may be used with pattern matching characters.
— The LIKE predicate may not be used with an escape clause.
• The keywords TODAY, YESTERDAY, TOMORROW may not be used in the DATE
function.
• The following rules apply to all expressions in the WHERE clause:
— Expressions may not contain the ISREPLICA or USER keywords.
— Expressions may use any comparison operator.
— Expressions may use an arithmetic operator, but they may not be used to form a
compound expression.
— Expressions that compare one property to another are not allowed. For example,
subject=title is invalid.
— Expressions in the following format are not allowed:
property_name operator('literal' operator 'literal)
— Expressions that force index correspondence between repeating properties

are not allowed. Such expressions AND together expressions that reference
repeating properties in the format:
predicate(repeating_attr_expr AND repeating_attr_expr)
(For more information about forcing index correspondence, refer to Forcing

index correspondence in query results, page 385.)
Select
• The following additional rules apply to expressions in the format first_expression

operator second_expression
— The first_expression is limited to one of the following:
property name
upper(property name)
lower(property name)
— The second_expression is limited to one of the following:

literal value
upper(literal value)
lower(literal value)
the DATE() function
— The operator may be any valid operator.
The GROUP BY clause

Note: You may not include a GROUP BY clause in an FTDQL SELECT statement.
The GROUP BY clause groups results. Use it when you include a function in the value
list for the SELECT statement. The value_list argument for the GROUP BY clause must
contain all of the values in the value list for the SELECT statement that are not aggregate
function values.
For example, the following statement returns the names of all documents, their owners,
and a count of the documents that each owner owns. The results are grouped by owner
name:
SELECT "owner_name", count(*)
FROM "dm_document"
GROUP BY "owner_name"
This next example selects the names of all documents, their owners, and their subjects,
and groups them first by owner and then, within each owner group, by subject:
SELECT "owner_name", "subject", count (*)
FROM "dm_document"
GROUP BY "owner_name", "subject"
The HAVING clause

Note: You may not include a HAVING clause in an FTDQL SELECT statement.
The HAVING clause restricts which groups are returned. It is most commonly used in
conjunction with the GROUP BY clause.
For example, the following statement returns owner names and the number of
documents each owner owns, grouped by owner names, for all owners having more
than 100 documents:
Select
SELECT "owner_name", count(*)

FROM "dm_document"
HAVING count(*) > 100
This statement first finds and counts all documents for each owner name. It returns only
those groups (owner’s name and count) for which the count is greater than 100.
You can also use the HAVING clause in a SELECT statement that does not include the
GROUP BY clause when a value in the value list is an aggregate function. For example,
the following statement returns a count of the workflows supervised by haroldk if that
count is greater than or equal to 25:
SELECT COUNT(*) FROM "dm_workflow"
WHERE "supervisor_name" = 'haroldk'
HAVING COUNT (*) >=25
If the number of workflows supervised by haroldk is less than 25, the statement returns
nothing.
Note that if you do not include a GROUP BY clause when you use a HAVING clause, the
only value permitted in the value list for the SELECT statement is one aggregate function.
The UNION clause

Note: You may not include a UNION BY clause in an FTDQL SELECT statement.
The UNION clause lets you obtain results from more than one SELECT statement. The
syntax is:
UNION dql_subselect
The dql_subselect argument must return the same number of properties or columns as the
first SELECT statement, and each property or column must have the same datatype as its
corresponding property or column in that SELECT statement. For example, if the first
SELECT statement returns three properties, then the subselect argument in the UNION
clause must also return three properties. The datatypes of the first properties returned
by each must be the same, as must the datatypes of the second and third properties.
Neither the first SELECT statement nor any subsequent UNION SELECT statements can
contain an IN DOCUMENT clause. The IN ASSEMBLY clause can be included only if the
clause is in the first SELECT statement and all unioned subselect statements.
For all databases except DB2, when you union two or more SELECT statements, the
property names that are returned are derived from the first SELECT statement. For
example, suppose you issue the following statement:
SELECT "name", "address" FROM "current_emp"
UNION SELECT "ret_name", "ret_address" FROM "retired_emp"
The query result objects for this statement have two properties, name and address, taken
from the value list of the first SELECT in the statement.
Select
For DB2 , if corresponding selected values in the unioned SELECT statements don’t
have the same name or alias, the returned property name is an number representing
the property’s position in the selected values list. For example, suppose you issue the
following query:
SELECT "name", "address" FROM "current_emp"
UNION SELECT "ret_name", "ret_address" FROM "retired_emp"
The query result objects for this statement have two properties. The first property is
named 1, representing selected values from name and ret_name. The second property is
named 2, representing selected values from address and ret_address.
The server does not return duplicate rows when you union two or more SELECT
statements. This is true even if the ALL keyword is included in the first SELECT
statement.
The ORDER BY clause
Use the ORDER BY clause to sort the results of the SELECT statements. The syntax of
this clause is:
ORDER BY value [ASC|DESC] {,value [ASC|DESC]}
The value argument must be a property or column name that appears in the value list.
You can sort in ascending (ASC) or descending (DESC) order. If you do not specify a sort
order, the default is ascending.
The primary sort is on the first value specified, the secondary sort is on the second value
specified, and so forth. To illustrate, the following statement returns the owner name,
subject, and title of all documents in the system in ascending order by owner name
and the subject:
SELECT "owner_name", "subject", "title"
FROM "dm_document"
ORDER BY "owner_name", "subject"
You can specify a value either explicitly, by name, or by position. For example, the
following statement returns the same results as the previous example, but notice that the
ORDER BY clause specifies values by their position in the SELECT value list:
SELECT "owner_name", "subject", "title"
FROM "dm_document"
ORDER BY 1, 2
The only exception occurs when you union two or more SELECT statements. In such
cases, you can only specify a value by its position in the value list.
FTDQL requirements for ORDER BY

If you include an ORDER BY clause in an FTDQL query, the sort order must be specified
by SCORE:
Select
ORDER BY SCORE
You cannot reference SCORE by its position in the selected values list. You must
reference it by name. You may sort in either ascending or descending order.
Including DQL hints
You can include processing hints for DQL and the RDBMS servers in SELECT statements.
The hints for DQL are called standard hints and can be added at the end of the
SELECT statement, using the ENABLE keyword. Hints to the RDBMS server are called
passthrough hints and can be added in the FROM clause, after a table or type name, and
at the end of the statement, using the keyword ENABLE.
The ROW_BASED hint may not be included in FTDQL queries or in queries that
reference a lightweight object type in the FROM clause. All other hints are acceptable in
FTDQL queries or when querying lightweight object types.
Table 28, page 168, lists the standard hints and provides brief guidelines for their use. For
detailed information about their implementation, refer to Appendix A, Using DQL Hints .
Table 28. DQL standard hints
Standard hint Description

SQL_DEF_RESULT_SET N Defines a maximum number (N) of rows to
return. Set N to a positive integer number. If set
to 0, all rows are returned.
Guidelines
• On a SQL Server database, this hint forces the

use of default result sets instead of a cursor to
return the rows. On all other databases, the
hint only sets the number of rows to return.
• It is recommended that you set N to a
maximum limit, rather than specifying it as 0.
• If you include SQL_DEF_RESULT_SET and
other hints that control the number of rows
returned, the last one listed in the hints is used.
Select

FORCE_ORDER Controls the join order for the tables and types
listed in the source list. If this hint is included, the
tables are joined in the order they are listed.
Guideline
• This hint is ignored on DB2.

RETURN_TOP N Limits the number of results returned by a query.
Set N to a positive integer number.
Guidelines
• If you include RETURN_TOP and other hints

that control the number of rows returned, the
last one listed in the hints is used.
• This hint is useful because it can limit the effect
of a bad (unbounded) query on the database.
• Sorting the results or including the DISTINCT
keyword reduces or eliminates the benefits of
using RETURN_TOP.
• On a SQL Server database, this hint reduces
the number of rows touched by the query.
• On a DB2 database, using OPTIMIZE_TOP
with RETURN_TOP is recommended.
OPTIMIZE_TOP N Returns N rows very quickly, then continues
with the remainder of the rows. Set N to positive
integer.
Guidelines
• This hint is most useful in conjunction with

RETURN_TOP.
• On an Oracle database, N is ignored.
• This hint is ignored on a Sybase database.
Select

FETCH_ALL_RESULTS N Fetches all results from the cursor immediately
and then closes the cursor. Set N to a positive
integer number or 0 to return all rows.
Guideline
• If you include FETCH_ALL_RESULTS and

other hints that control the number of rows
returned, the last one listed in the hints is used.
OPTIMIZATION_LEVEL level_1 Allows you to change the query optimization
level_2 level. Set level_1 to the optimization level you
want for the current query and level_2 to the
optimization level desired for the connection after
the query completes.
Guideline
• This hint in only useful against DB2 databases.
It is ignored for other databases. For
information about valid values for level_1 and
level_2, refer to your DB2 documentation.
UNCOMMITTED_READ Ensures that a read only query returns quickly
even if another session is holding locks on the
tables queried by the read only query.
This hint is useful only on SQL Server, DB2, and

Sybase databases.
ROW_BASED Directs Content Server to return query results that
contain repeating property values in a row‑based
format—one row for each returned repeating
property value. In addition, the hint also affects
the rules governing:
• Selecting repeating property values
• Using an asterisk as a selected value
• Referencing repeating properties in WHERE
clause qualifications
More information about these effects is found in

Repeating properties, page 138, The asterisk (*) as
a selected value, page 148, and Using repeating
properties in qualifications, page 162.
Select

[NO]FTDQL FTDQL directs Content Server to execute the
query as an FTDQL query. If the syntax of the
query violates the rules for FTDQL syntax, an
error is returned.
NOFTDQL directs Content Server to execute the

query as a standard query.
TRY_FTDQL_FIRST TRY_FTDQL_FIRST directs Content Server to
first execute the query as an FTDQL query and,
if a timeout or resource exceeded error occurs, to
retry the query as a standard query.
If this hint is included, the FTDQL and NOFTDQL

hints are ignored if they are also included.
HIDE_SHARED_PARENT HIDE_SHARED_PARENT directs Content Server
to return only the rows in the query results that
are not shared parents.
GROUP_LIST_LIMIT GROUP_LIST_LIMIT defines the maximum
number of groups that may be referenced in the
generated SQL statement to check permissions
for the user executing the query.
The default limit is 250. Using this hint

overrides the default value and the
DM_GROUP_LIST_LIMIT environment
variable, if that is set.
Examples
The following example returns the names and titles of all documents owned by the
current user:
SELECT "object_name", "title" FROM "dm_document"
WHERE "owner_name" = USER
The next example selects all documents and their authors with the subject
employee_benefits:
SELECT "r_object_id", "authors" FROM dm_document
WHERE "subject" = 'employee_benefits'
ORDER BY 1
The following example returns the names of all objects in the New Books cabinet:
Select
SELECT "object_name" FROM "dm_sysobject"

WHERE CABINET ('/New Books')
ORDER BY "object_name"
The following FTDQL example returns those documents that contain the phrase “for
publication:” for which the user has Write permission:
SELECT FOR WRITE object_name,title,owner_name FROM dm_document
SEARCH DOCUMENT CONTAINS 'for publication'
There are additional examples demonstrating the use of specific clauses in the
descriptions of the clauses.
Unregister
Unregister
Purpose Removes a registered table from the repository.
Syntax
UNREGISTER [TABLE] [owner_name.]table_name
Arguments
Table 29. UNREGISTER argument descriptions
owner_name Identifies the table’s owner. The default value is the
current user.
Use the owner’s RDBMS user name. If the owner is

a repository user, this value is found in the user’s
user_db_name property.
If the RDBMS is Oracle and the owner is the DBA,

you can use the alias dm_dbo.
If the RDBMS is MS SQL Server or Sybase and if the

owner is the DBA, you can use the alias dbo.
table_name Identifies a registered table to remove from the
repository. Use the table name as it appears in the
RDBMS.
Permissions
You must be the owner of the registered table or have Superuser privileges to unregister
a table.
Unregister
Description
Unregistering a table removes the object of type dm_registered that represents the table
in the repository. It does not remove the table from the underlying RDBMS.
If you attempt to unregister a table that is not registered, you receive an error message.
Related statements
Delete, page 101

Insert, page 120
Register, page 123
Examples
The following example unregisters the table called departments:

UNREGISTER TABLE "departments"
Update
Update
Purpose Updates the rows of a registered table.
Syntax
UPDATE table_name SET column_assignments

Arguments
Table 30. UPDATE argument descriptions
table_name Identifies the registered table to update. (Refer to
Register, page 123 for information about registering
tables in the repository.)
SET clause Specifies the columns to update and the new values to
assign to them. The syntax for column_assignments is:
column_name = value expression
Refer to Identifying columns to update, page 176 for

a full description of the syntax.
WHERE clause Restricts the rows that are updated to those that meet
the criteria in the qualification. Refer to The WHERE
clause, page 161 for a full description of WHERE
clauses and qualifications.
Return value
The UPDATE statement returns a collection whose result object has one property,
rows_updated, that contains the number of updated rows.
Update
Permissions
To use the UPDATE statement, the following conditions must be true:

• Your object‑level permission for the dm_registered object in the repository that
represents the RDBMS table must be at least Browse
• Your table permission for the dm_registered object representing the table must be
DM_TABLE_UPDATE
RDBMS permission to update the specified table. (The actual name of this permission
depends on your RDBMS.)
(For more information about security, object‑level and table permissions, refer to the
Content Server Administration Guide.)
Description
This section contains usability information.
General notes
The SET clause identifies which columns are updated and the WHERE clause determines
which rows are updated. The server searches for all rows that meet the qualification
and updates the specified columns. If a WHERE clause is not included, then all rows
are updated.
Identifying columns to update

In the SET clause, column_assignment has the format:
column_name = value_expression
where column_name is the name of a column in the table.

The value_expression can be a simple or complex expression but must resolve to a single
value. It can include literal values, other column names, special keywords, date and
scalar functions, and arithmetic expressions. The resulting value must be appropriate
for the datatype of the specified column.
Identifying rows to update

The WHERE clause qualification determines which rows are updated. The qualification
consists of one or more expressions that resolve to a single Boolean TRUE or FALSE. The
server updates only those rows for which the qualification is TRUE. The expressions in
a qualification can include comparison operators, literals, scalar and date functions,
column names, arithmetic expressions, and column predicates. Multiple expressions are
joined together using logical operators.
Update
Related statements
Delete, page 101

Insert, page 120
Register, page 123
Examples
This example updates the column called chef_name:

UPDATE "recipes" SET "chef_name" = 'carol'
WHERE "chef_name" = 'carole'
Update...Object
Update...Object
Purpose Updates an object in the repository.
Syntax
UPDATE [PUBLIC]type_name [(ALL)][correlation_var]

[WITHIN PARTITION partition_id {,partition_id}]
OBJECT[S] update_list
[,SETFILE filepath WITH CONTENT_FORMAT=format_name]
{,SETFILE filepath WITH PAGE_NO=page_number}
Arguments
Table 31. UPDATE...OBJECT argument descriptions
type_name Identifies the type of the object that you want to
update. Valid values are:
dm_assembly and its subtypes

dm_user and its subtypes
dm_group and its subtypes
dm_relation_type
dm_sysobject and its subtypes
If you have Sysadmin or Superuser user privileges,

you can also update the dmr_content object type.
correlation_var Defines a qualifier for the type name that is used to
clarify property references in the statement.
for an object.
Update...Object
update_list Specifies the update operations to perform on the
object. Valid formats are:
set property_name = value set property_
name[[index]] = value append [n]
property_name = value insert property_
name[[index]] = value remove property_
name[[index]] truncate property_
name[[index]] [un]link 'folder path' move
[to] 'folder path'
If you specify more than one operation, use commas

to separate them.
SETFILE clause WITH Adds the first content file to the new object. Refer
CONTENT_ FORMAT option to WITH CONTENT_FORMAT option, page 182 for
details.
SETFILE clause WITH Adds additional content to the object. Refer to WITH
PAGE_NO option PAGE_NO option, page 182 for details.
IN ASSEMBLY clause Restricts the statement to objects in a particular
assembly.
document_id identifies the document with which the

assembly is associated. Use a literal object ID:
ID('object_id')
version_label specifies a particular version of the

document. Use a symbolic or an implicit version label.
If you do not include a version label, the server uses
the version identified by the document_id argument.
component_id specifies a particular component in the

assembly. Including the NODE option restricts the
statement to the specified component. Use a literal
object ID to identify the component:
ID('object_id')
The DESCEND keyword directs the server to update

not only all directly contained node components,
but also any indirectly contained components that
meet the criteria. If you do not include this keyword,
the server updates only the directly contained
components that meet the criteria in the statement.
Update...Object
SEARCH clause Restricts the statement to objects that meet the
SEARCH clause fulltext search condition. Refer to The
SEARCH clause, page 157 for a detailed description
of a SEARCH clause.
WHERE clause Restricts the statement to objects that meet the
qualification. The qualification is an expression
that evaluates to TRUE or FALSE. It can include
comparison operators, literals, property names, scalar
and date functions, special keywords, predicates, and
arithmetic expressions. Multiple expressions can be
joined together using logical operators.
Refer to The WHERE clause, page 161 for a detailed

description of the clause.
Return value
The UPDATE...OBJECT statement returns a collection whose result object has one
property, called objects_updated, that contains the number of objects updated.
Permissions
To update an object, you must have Write permission on the object.

To include the SETFILE clause in the statement, you must have Superuser privileges.
Description
General notes
To update an object, the object cannot belong to a frozen assembly or a frozen or
immutable virtual document.
The type_name argument specifies the type of objects to update. The server searches
all objects of the specified type and any subtypes for objects that meet any additional
criteria you define in the statement.
Update...Object
The keyword PUBLIC restricts the query to those objects with the r_is_public property
those documents for which ISPUBLIC is TRUE. When the server queries or searches only
public objects, it uses only the setting of r_is_public for security checks.
The keyword ALL directs the server to consider all versions of each object. If you do not
include ALL, the server only considers the version with the symbolic label CURRENT.
You must enclose ALL in parentheses.
The IN ASSEMBLY, SEARCH, and WHERE clauses restrict the scope of the statement.
The IN ASSEMBLY clause restricts the operation to a particular virtual document
assembly or node (component) within the virtual document. The SEARCH clause
restricts the operations to indexed objects that meet the fulltext search condition. The
WHERE clause restricts the operations to objects that meet the specified qualification.
The clauses are applied in the following order:
• SEARCH
• IN ASSEMBLY
• WHERE
If you do not include any of these clauses, the updates are applied to all objects of that
type for which you have Write permission.
If any of the objects that are otherwise eligible for updating belong to a frozen assembly
or an unchangeable virtual document, then the entire statement is rolled back and no
objects are updated.
The SETFILE clauses

A SETFILE clause adds new content to the end of the sequence of content files in the
object or replaces an existing content file. You cannot use SETFILE to insert a content
file between two current files. You cannot store the content file you add in a turbo store
storage area.
You must have Superuser privileges to include the clause in the statement.
Any object capable of having content may have multiple associated content files. All files
must have the same content format and be ordered within the object.
The content format is defined when you add the first content file to the object. All
subsequent additions must have the same format. Consequently, specifying the format
for content additions after the first file is not necessary. Instead, you must specify the
content’s position in the ordered list of content files for the object.
To add the first content, use the SETFILE clause with the WITH CONTENT_FORMAT
option.
To add additional content, use the SETFILE clause with the PAGE_NO option.
You can’t include both options in a single SETFILE clause.
Update...Object
WITH CONTENT_FORMAT option

Use this SETFILE option to add the first content file to an object. The syntax is:
SETFILE 'filepath' WITH CONTENT_FORMAT='format_name'

The format name is the name found in the name property of the format’s dm_format
object.
WITH PAGE_NO option
Use this SETFILE option to add additional content to an object or replace existing
content. The syntax is:
SETFILE 'filepath' WITH PAGE_NO=page_number
The filepath must identify a location that is visible to Content Server. The file must have
the same file format as the existing content associated with the object.
The page number identifies the file’s position of the content file within the ordered
contents of the new object. You must add content files in sequence. For example, you
cannot add two files and specify their page numbers as 1 and 3, skipping 2. Because the
first content file has a page number of 0, page numbers for subsequent additions begin
with 1 and increment by 1 with each addition.
To replace a content file, specify the page number of the file you want to replace.
The update operations

The update_list defines the operations to perform. You can:
• Set the value of a single‑valued or repeating property
• Add a value for a repeating property
• Insert a value into the list of values for a repeating property
• Remove a value from a repeating property
• Truncate a repeating property (remove all values)
• Link an object to a folder or cabinet or unlink an object from a folder or cabinet
• Move an object to a new folder or cabinet
Unless you have Superuser user privileges, you can only update read and write
properties. These properties have names beginning with a_ or have no prefix at all.
If you have Superuser user privileges, you can update read‑only properties. These
properties have names beginning with r_.
You can specify more than one update operation in a single statement. When an
UPDATE...OBJECT statement includes multiple operations, use commas to separate
them. For example, the following statement sets two properties and inserts a value into a
repeating property. Notice the commas at the end of each update operation clause:
UPDATE "dm_document" OBJECTS
SET "title" = 'A Cake Primer',
SET "subject" = 'cake',
Update...Object
INSERT "authors"[3] = 'georgette'

WHERE "r_object_id" = '090007354140004e'
The server processes the update operations in the order listed.

Setting a property value
To set the value of a single‑valued or repeating property, use the following syntax:
set property_name[[index]] = value
The property_name argument is the name of the property. If the property is a repeating
property, the index identifies the position of the new value in the property’s list of values.
The positions of the values for a repeating property are numbered from zero. Enclose the
index value in square brackets.
The value argument is the value to assign to the property. The value can be a literal or a
subquery. If it is a subquery, it cannot return more than one row. If it returns more than
one row, the statement returns an error.
Appending a value to a repeating property
To append a value to a repeating property, use the following syntax:
append [n]property_name = value
The property_name argument is the name of the property to which to append a new value.
The value argument specifies what value to add to the property’s ordered list of values.
The value is automatically added to the end of the repeating property’s list of values.
The value can be either a literal value or a subquery. The subquery can return any
number of rows. By default, the system appends a maximum of 20 rows. To override the
default, use the [n] option to define how many rows to append. You can use any integer
number (to append that number of rows) or an asterisk (*) (to append all rows).
Inserting a value into a repeating property
To insert a value into the list of values for a repeating property, use the following syntax:
insert property_name[[index]] = value
The property_name argument identifies the property. The index argument defines where
to insert the new value. The positions of all values for a repeating property are numbered
from zero. If you do not include the index, the server automatically inserts the new
value in position zero, as the first element in the ordered list. You must enclose the
index in square brackets.
The value defines the value that you want to insert. The value can be either a literal value
or a subquery. If it is a subquery, it cannot return more than one row. If it returns
multiple rows, the statement returns an error.
When you insert a value, all values that follow the inserted value are renumbered. For
instance, when you insert a value at position [5], the value formerly at position [5] is
moved up to position [6]. Consequently, if you are inserting more than one value in the
property (for example, if the statement is in a program loop), be sure to increase the
index number each time you insert a value.
Update...Object
Removing values from repeating properties

To remove a value from a repeating property, use the following syntax:
remove property_name[[index]]
The property_name argument identifies the property. The index argument indicates the
position of the value to remove in the property’s ordered list of values. The positions of
all values for a repeating property are numbered from zero. If you do not include the
index, the server removes the first value (position 0) in the property. Enclose the index
in square brackets.
When you remove a value, the remaining values are renumbered. For instance, when
you remove the value at position [5], the value formerly at position [6] is moved up to
position [5]. Consequently, if you are removing more than one value in the property (for
example, if the statement is in a program loop), be sure to start with the highest index
number and decrement the index number each time you delete a value.
For example, if you want to remove the values at positions 6 and 7, remove 7 first and
then 6. If you remove 6 first, the value at 7 is moved into position 6 and the value at 8
is moved into position 7. When you remove 7, you are actually removing the value
formerly in the position 8.
Truncating a repeating property
To truncate a repeating property (remove its values), use the following syntax:
truncate property_name[[index]]
The property_name argument identifies the property. The index argument specifies where
in the property’s list of values to begin the truncation. For example, if you specify
property_name[4], the server removes all values beginning with property_name[4]. If
you do not specify an index level, the server removes all values.
Linking or unlinking an object
To link an object to a folder or cabinet, use the following syntax in the update_list:
link 'folder path'
Linking an object adds a new link for the object. Current links are not affected.
To unlink an object from a cabinet or folder use the following syntax:
unlink 'folder path'
Unlinking removes only the specified link. Other links are not affected.
The folder path argument specifies the folder or cabinet to which you are linking the
object. A folder path has the following format:
cabinet_name{/folder_name}
Moving an object to a new folder or cabinet
To move an object to a new folder or cabinet, use the following syntax:
move [to] 'folder path'
Update...Object
The folder path argument specifies the folder or cabinet to which to link the object. A
folder path has the following format:
cabinet_name{/folder_name}
Moving an object removes all current links and adds a link to the specified cabinet or
folder.
Related statements
Examples
The following statement deletes all indexed documents that contain the word yeast:
SET "keywords" = 'yeasted'
SEARCH DOCUMENT CONTAINS 'yeast'
This next statement updates all documents that contain the word yeast but not the word
rolls:
SET "keywords" = 'pastries'
SEARCH DOCUMENT CONTAINS 'yeast' AND NOT 'rolls'
The following statement updates all cabinets that have either Janine or Jeremy as their
owner:
UPDATE "dm_cabinet" OBJECTS
SET "is_private" = TRUE
WHERE "owner_name"='janine' OR owner_name='jeremy'
Update...Object
Chapter 3
Administration Methods
Administrative methods are methods that perform a variety of administrative and

monitoring tasks. (Table 32, page 188, lists the methods by task categories.) They are
executed in an application by invoking either the DQL EXECUTE statement or the
IDfSession.apply method. You can also execute them interactively through Documentum
Administrator.
This chapter first describes how to invoke the methods. Then it provides an alphabetical
reference to the methods. For each method, it provides:
• Invoking syntax
Only the DQL syntax is shown. For the IDfSession.apply method syntax, refer to
the Javadocs.
• Arguments
• Return Value
• Permissions
• Description
• Related Administration Methods
• Examples
Invoking administration methods

To execute an administration method manually, use Documentum Administrator. All
the methods (except DO_METHOD, WEBCACHE_PUBLISH, and ROLES_FOR_USER)
are available through the Methods facility in repository Management. Many of the
methods are also available through category‑specific pages.
Note: Because DO_METHOD is used to execute user‑defined procedures, this method is
implemented as part of the Attributes page for user‑defined methods.
To execute an administration method in an application, use either the IDfSession.apply

method or the DQL EXECUTE statement. You can also use EXECUTE to invoke an
administration method through IDQL.
The EXECUTE statement is the DQL equivalent of the API Apply method. You can use it
to execute any of the administration methods except PING or WEBCACHE_PUBLISH.
The EXECUTE statement is not case sensitive. You can enter the administration method
name and argument names in uppercase, lowercase, or any combination. You must
enclose character string values (including an object ID in a FOR clause) in single quotes
when they are included in the EXECUTE statement.
For information about using IDfSession.apply to invoke an administration method,
refer to the Javadocs.
Scope of the administration methods

Administrative methods execute in the context of the current repository scope. You
cannot connect to a repository and execute an administration method against a different
repository.
Administration method operations

Table 32, page 188, lists the administration methods by category and describes the
operation that you can perform with each method.
Table 32. Administration methods by category
Category of Operation Administration Description

Method
Process Management BATCH_PROMOTE, Promotes multiple objects to
page 194 their next lifecyle states.
Note: This method is not
available through Documentum
Administrator or using DQL
EXECUTE.
CHECK_SECURITY, Checks a user or group’s
page 205 permissions level for one or
more objects.

Method
FIX_LINK_CNT, page Updates the r_link_cnt property
238 for a specified folder.
GET_INBOX, page 247 Returns items in user’s Inbox.
MARK_AS_ Sets the i_is_archived
ARCHIVED, page property of a dm_audittrail,
288 dm_audittrail_acl, or
dm_audittrail_group to T.
PURGE_AUDIT, page Removes audit trail entries from
318 the repository.
RECOVER_AUTO_ Recovers work items claimed by
TASKS, page 331 a workflow agent master session
but not yet processed.
ROLES_FOR_USER, Returns the roles assigned to
page 347 a user in a particular client
domain.
Execute methods DO_METHOD, page Executes system‑defined
218 procedures such as lpq or who
or user‑defined procedures.
HTTP_POST, page 257 Directs the execution of a
method to an application server.
Content storage CAN_FETCH, page Determines whether content
management 196 in a distributed storage area
component can be fetched by the
server.
CHECK_ Finds SysObjects in
RETENTION_ content‑addressed storage
EXPIRED, page 201 that have an expired retention
period or no retention period.

Method
CLEAN_LINKS — Provides maintenance for linked
Deprecated, page 210 store storage areas.
This method is On UNIX, this method cleans up

deprecated. DFC unneeded linkrecord objects and
Version 6 does directories and links associated
not support linked with linked storage areas.
storage areas nor
link record objects, On Windows, this method cleans
which consequently, up unneeded linkrecord objects
deprecates this and resets file storage object
method. security.
DELETE_REPLICA , Removes a replica from a

page 214 distributed storage area.
DESTROY_ Removes a content object
CONTENT, page 216 and its associated file from
the repository. (Do not
use this for archiving; use
PURGE_CONTENT instead.)
GET_FILE_URL, page Returns the URL to a content file.
245
GET_PATH, page 253 Returns the path to a particular
content file in a particular
distributed storage area
component.
IMPORT_REPLICA, Imports an external file as a
page 262 replica of content already in the
repository.
MIGRATE_ Moves content files from one
CONTENT, page 292 storage area to another.
PURGE_CONTENT, Deletes a content file from a
page 326 storage area. (Used as part of the
archiving process.)
PUSH_CONTENT_ Sets the content metadata in
ATTRS, page 328 a content‑addressed storage
system for a document stored in
that storage system.

Method
REGISTER_ASSET, Queues a request for the creation
page 333 of a thumbnail, proxies, and
metadata for a rich media
content file. The request is
queued to the Media Server.
This method is only available or

useful if you have Documentum
Media Transformation Services
running.
REPLICATE, page 340 Copies content in one component
of a distributed storage area to
another area.
RESTORE_ Moves a file or files from
CONTENT, page 345 archived storage to the original
storage location.
SET_CONTENT_ Sets the content_attr_name and
ATTRS, page 352 content_attr_value properties
in the content object associated
with the content file.
SET_STORAGE_ Sets the state of a storage area to
STATE, page 361 off‑line, on‑line, or read‑only.
TRANSCODE_ Queues a request for a content
CONTENT, page 365 transformation to the Media
Server.
This method is only available or

useful if you have Documentum
Media Transformation Services
running.
Database Methods DB_STATS, page 212 Provides database operation
statistics for a session.
DROP_INDEX, page Drops an index.
227
EXEC_SQL, page 232 Executes SQL statements.
FINISH_INDEX_ Completes an interrupted move
MOVES, page 236 operation for an object type
index.

Method
GENERATE_ Creates an SQL script to partition
PARTITION_ a repository.
SCHEME_SQL, page
239
MAKE_INDEX, page Creates an object type index.
284
MIGRATE_TO_LITE, Migrates standard SysObjects
page 304 to lightweight SysObjects and
shareable parents.
MOVE_INDEX, page Moves an object type index from
314 one tablespace or segment to
another.
Note: This is not supported on
DB2.
REORGANIZE_ Reorganizes a database table for
TABLE, page 337 query performance.
UPDATE_ Updates the statistics in a
STATISTICS, page database table.
369
Full‑Text Methods ESTIMATE_SEARCH, Returns the number of results
page 229 matching a particular SEARCH
condition.
MARK_FOR_RETRY, Finds all content objects that
page 290 have a particular negative
update_count and marks them
as awaiting indexing.
MODIFY_TRACE, Sets the tracing level for full‑text
page 312 indexing operations.
Session Management CHECK_CACHE_ Requests a consistency check on
CONFIG, page 198 a particular cache config object.
GET_LAST_SQL, page Returns the last SQL statement
251 issued.
GET_SESSION_DD_ Returns the locale in use for the
LOCALE, page 255 current session.
LIST_AUTH_ Lists the authentication plugins
PLUGINS, page 266 loaded by Content Server.

Method
LIST_RESOURCES, Provides information about
page 268 the server operating system
environment.
LIST_SESSIONS, page Provides information about
273 current, active sessions.
LIST_TARGETS, page Lists the connection brokers
278 defined as targets for the server.
The information is returned

in a collection with one result
object whose properties list the
connection brokers defined as
targets for the server.
LOG_ON, page Turn server logging of
282 and LOG_OFF, information about RPC calls on
page 280 or off.
PING, page 316 Determine if a client has an
active server connection.
SET_APIDEADLOCK, Sets a deadlock trigger on
page 349 a particular API method or
operation.
SET_OPTIONS, page Turn various tracing options on
357 or off.
SHOW_SESSIONS, Provides information about
page 363 current, active sessions and
a user‑specified number of
timed‑out sessions.
Web Publishing WEBCACHE_ Invokes the dm_webcache_
Management PUBLISH, page 372 publish method to publish
documents to a Web site.
BATCH_PROMOTE
BATCH_PROMOTE
Purpose Promotes multiple objects to their next state.
Syntax
This method cannot be executed using the DQL EXECUTE statement.
Arguments
Table 33. BATCH_PROMOTE arguments
Argument Datatype Value Description

ARGUMENTS S comma‑separated Identifies the objects to
list of object IDs promote. Use the objects’
object IDs. You must enclose
the list of object IDs in single
quotes.
Return value
BATCH_PROMOTE launches a method, dm_bp_batch. If the method executes

successfully, BATCH_PROMOTE returns a collection with one result object. If the method
is not successfully launched, BATCH_PROMOTE returns nothing. If BATCH_PROMOTE
returns nothing, use IDfSession.getMessage to retrieve the error message.
If BATCH_PROMOTE returns a collection, check the value of the method_return_val
property of the result object. A value of 36 indicates that all objects were successfully
promoted. Any value other than 36 means that an error occurred and processing stopped
at some point. Use an IDfSession.getMessage to retrieve the error message.
Permissions
The user issuing the method must have the necessary permissions to promote the objects
listed in the argument.
BATCH_PROMOTE
Description
BATCH_PROMOTE allows you to promote multiple objects with one command. The
objects can be attached to different lifecycles and can be in different states.
The method checks the permissions on each object specified to ensure that the user
issuing the method has the correct permissions to promote the object. Then the method
checks that associated lifecycle or lifecycles are valid. Finally, the method executes any
entry criteria specified for the objects’ next states. If BATCH_PROMOTE encounters an
error at this stage, the method exits and returns nothing.
If the permissions are correct, the lifecycles are valid, and any entry criteria are fulfilled,
BATCH_PROMOTE launches the dm_bp_batch method. The method performs any
action procedures needed, as a single transaction. If an error occurs, the method exits
and reports an error. Any objects promoted before the action procedure error remain
promoted; the object whose procedure caused the error and any objects in the list after
it are not promoted. For example, if the argument list includes 6 objects and an error
occurs on an action procedure for object 4 in the list, objects 1, 2, and 3 are promoted.
Objects 4, 5, and 6 are not.
There are two limitations on the use of BATCH_PROMOTE:
• BATCH_PROMOTE cannot run actions on behalf of the lifecycle_owner. If the
value in the a_bpaction_run_as property in the docbase config object is set to
lifecycle_owner, BATCH_PROMOTE exits with an error.
• You can specify a maximum of 200 objects in each execution of BATCH_PROMOTE.
Related administration methods
None
CAN_FETCH
CAN_FETCH
Purpose Determines if the server can fetch a specified content file.
Syntax
EXECUTE can_fetch FOR 'content_object_id'
Arguments
CAN_FETCH has no arguments.
Return value
CAN_FETCH returns a collection with one query result object. The object has one
Boolean property that is set to TRUE if the fetch is possible or FALSE if it is not.
Permissions
Anyone can use this method.
Description
If a repository has a distributed storage area, it is possible to configure the servers so

that they can fetch from all distributed storage area components, from a subset of the
components, or only from the local component. (For information about configuring this
capability, refer to the Distributed Configuration Guide.) In such repositories, you can use
the CAN_FETCH method to determine whether a server can fetch from a particular
distributed storage area component.
In a content server configuration, the CAN_FETCH method is executed by the content
server.
CAN_FETCH
GET_PATH, page 253
Examples
The following examples determine whether Content Server can fetch the content file
associated with the content object 06000002472185e1:
EXECUTE can_fetch FOR '06000002472185e1'
CHECK_CACHE_CONFIG
CHECK_CACHE_CONFIG
Purpose Requests a consistency check on a particular cache config object.
Syntax
EXECUTE check_cache_config [FOR 'cache_config_id']

[WITH argument = value ][,argument = value]
Do not include the FOR clause if you include the CONFIG_NAME argument.
Arguments
Table 34. CHECK_CACHE_CONFIG arguments

CONFIG _NAME S name of cache Identifies the cache config
config object object on which to perform
the consistency check. Use the
cache config’s object name.
This is an optional argument.

If you do not include it, you
must include the object ID of
the cache config object.
FORCE _CHECK B T (TRUE) or TRUE directs Content
Server to re‑execute the
F (FALSE) queries regardless of the
server_check_interval value.
(Refer to the General Notes
for a description of the use of
the server_check_interval
in the context of
CHECK_CACHE_CONFIG.)

The default is F (FALSE).
CHECK_CACHE_CONFIG
Return value
The method returns a collection with one query result object. The object has the
properties listed in Table 35, page 199.
Table 35. Properties in the CHECK_CACHE_CONFIG result object
Property Datatype Description

r_object_id ID Object ID of the cache config object
r_last_changed_date Date/time The date and time at which Content
Server last validated the query results
and found that something had changed.
r_last_checked_date Date/time The date and time at which Content
Server last ran the queries to determine
whether the results had changed.
server_check_interval integer How long the server waits between
validations of the query results. The
time is expressed in seconds.
client_check_interval integer The consistency check interval used
by clients when issuing fetch or query
methods that include this cache config
object as an argument.
server_time Date/time Current server time
server_time_secs integer Current server time in seconds
cache_config_exists Boolean F (FALSE) if the specified cache config
object is not found. T (TRUE) otherwise.
If an error occurs, the method returns an error rather than the collection.
Permissions
The cache config object must be owned by a Superuser.

You must have at least Browse permission on the cache config object to issue this method.
To issue the method with FORCE_CHECK set to TRUE, you must be a Superuser or have
Execute Procedure permission on the cache config object.
CHECK_CACHE_CONFIG
Description
CHECK_CACHE_CONFIG directs Content Server to check whether the data defined by

a particular cache config object is current. (Cache config objects define queries whose
results are cached persistently on the client.) To determine if the data is current, the
server compares the current time to the date and time in the object’s r_last_checked_date
property. If the difference is less than the interval defined in server_check_interval,
indicating the interval has not expired, the data is considered current and the server does
not recompute the data. If the interval has expired, the data is considered out of date.
The server executes the dm_CheckCacheConfig method to recompute the data. The
method executes the queries defined in cache_element_queries, computes a hash of the
results, and stores the hash in the i_query_result_hash property. The method returns the
new computation date and time in the query result object’s r_last_checked_date property.
You can use the FORCE_CHECK argument to override the server check interval and
force Content Server to execute the queries.
For information about persistent client caching and cache config objects and their use,
refer to Content Server Fundamentals. You can execute the dm_CheckCacheConfig method
manually, using a DO_METHOD administration method. For an example of using
DO_METHOD to call dm_CheckCacheConfig, refer to the Content Server Administration
Guide. However, explicit calls to the method are not normally necessary. The calls occur
automatically, as a side effect of referencing cache config objects in fetch and query
methods.
None
Examples
The following example identifies the cache config object by its object ID and forces the
recomputation of the data:
EXECUTE check_cache_config FOR '08000002723ae36b'
WITH force_check = true
This next example identifies the cache config object by its owner and name.
EXECUTE check_cache_config
WITH config_name='johndoe.report_app_config'
CHECK_RETENTION_EXPIRED
Purpose Generates a list of objects whose content, stored in content‑addressed storage, has
an expired retention period or a zero retention period.
Syntax
EXECUTE CHECK_RETENTION_EXPIRED
WITH QUERY='where_clause'
[,SELECT_LIST='property_list']
[,INCLUDE_ZERO_RETENTION_OBJECTS=T|F]
Arguments
Table 36. CHECK_RETENTION_EXPIRED arguments

QUERY S where_clause Defines which SysObjects are
to be checked for an expired or
no retention period. Consists
of a DQL SELECT where
clause. Only literal values
and properties defined for
the dm_sysobject type may be
referenced. The string must be
enclosed in single quotes.
SELECT_LIST S property_list Identifies additional properties
whose values are to be returned
in the result object.
Only properties defined for the

dm_sysobject object type may
be included.
Separate multiple property

names with commas and

enclose the entire list in single
quotes.
INCLUDE_ZERO_ B T (TRUE) or F If set to T, the method
RETENTION_ (FALSE) checks objects stored in
OBJECTS content‑addressed storage
areas that allow but do not
require a retention period.
The default is F, meaning

that only objects stored in
content‑addressed storage
areas that require a retention
period are checked.
Return value
CHECK_RETENTION_EXPIRED returns a collection of result objects, each representing

one SysObject whose retention has expired or that had no retention period. The result
objects have five default properties plus any specified in the SELECT_LIST argument.
The default properties of the result object are:
• r_object_id
• object_name
• a_storage_type
• r_creation_date
• retention_date
The retention_date property is a computed property. The date value is the GMT
equivalent of the retention period as it is defined in the time zone of the Centera
storage system. For example, suppose the Centera system is in the Eastern time zone
(EST) and the client on which user is working is in the Pacific time zone (PST). If the
user sets the retention value to March 15, 2004 11 a.m. PST, the retention value is
stored as March 15, 2004 2 p.m.—the Eastern time zone equivalent of March 15, 2004
11 a.m. The value returned in the computed property is the GMT equivalent of
March 15, 2004 2 p.m.
Permissions
You must have Sysadmin or Superuser privileges to execute this method.
Description
The CHECK_RETENTION_EXPIRED method is used by the RemoveExpiredRetnObjects

administration job to find the content in content‑addressed storage that has an expired
retention period. The method returns a list of the objects. It does not remove the content
from the storage area, nor does it remove from the repository any of the objects that
contain the content.
A content‑addressed storage area can have three possible retention period configurations:
• The storage area may require a retention period.
In this case, the a_retention_attr name property is set and the a_retention_attr_req is
set to T.
• The storage area may not allow a retention period.
In this case, the a_retention_attr name property is not set and the a_retention_attr_req
is set to F.
• The storage area may allow but not require a retention period.
In this case, the a_retention_attr name property is set , but the a_retention_attr_req is
set to F.
By default, the method operates only on objects that are stored in content‑addressed
storage areas that require a retention period. The method never includes objects stored
in content‑addressed storage areas that do not allow retention periods. If you want
it to examine objects stored in content‑addressed storage areas that allow but do not
require a retention period, you must set the INCLUDE_ZERO_RETENTION_OBJECTS
argument to true (refer to INCLUDE_ZERO_RETENTION_OBJECTS argument, page
203, for more information).
QUERY argument
The QUERY argument’s where clause is a DQL where clause qualification. It is used to
select objects for possible inclusion in the results returned by the method. The objects
that fulfill the QUERY argument and are stored in an appropriate content‑addressed
storage area are then examined to determine whether the retention period has expired. If
so, the object is included in the results.
The QUERY argument can reference only literal values or properties defined for the
dm_sysobject object type. If the where clause includes single quotes, you must escape
them with single quotes. For example:
...QUERY,S,'a_storage_type=''castore_1''
and r_creation_date > DATE(01/01/2003)'
INCLUDE_ZERO_RETENTION_OBJECTS argument
By default, the method does not include objects whose content has a 0 retention period
because the assumption is that such content is meant to be kept forever. However, in
a storage area that allows but does not require a retention period, a 0 retention period
can be result from two possible causes:
• The user deliberately set no retention period, and consequently, the server set the
retention period to 0
• The user specified a retention date that had already elapsed. When this occurs,
the server sets the retention period to 0.
Because the meaning of 0 is ambiguous in such storage areas, the method supports the
INCLUDE_ZERO_RETENTION_OBJECTS argument to allow you to include content
with a zero retention in storage areas that allow but do not require a retention period.
If you set INCLUDE_ZERO_RETENTION_OBJECTS to T, when the method examines
objects in storage areas that allow but do not require a retention period and it will
include in the results any object with an expired or zero retention period.
SELECT_LIST argument
The SELECT_LIST argument allows you to include additional SysObject properties in
the result objects. You must enclose the argument’s value in single quotes.
None
Examples
The following example checks SysObjects stored in the content‑addressed storage area
named “castore_2” owned by the user named “John Arthur”. It also adds the title and
subject property values to the result objects.
EXECUTE check_retention_expired
WITH QUERY='a_storage_type=''castore_2'' and
owner_name=''John Author''',
SELECT_LIST='title,subject'
This example directs the method to include objects in a storage area that allows but
doesn’t require a retention period:
EXECUTE check_retention_expired
WITH QUERY='a_storage_type=''castore_3'' and
owner_name=''Mary Writer''',
SELECT_LIST='title,subject',
INCLUDE_ZERO_RETENTION_OBJECTS=true
CHECK_SECURITY
CHECK_SECURITY
Purpose Checks a user’s or group’s access permissions on one or more objects or checks a
user’s or group’s permission level in one or more ACLs.
Syntax
EXECUTE check_security WITH user_name='name'|group_name='name',

level=security_level,object_list='list_of_objectids'
Arguments
Table 37. CHECK_SECURITY arguments

USER_NAME S name Name of the user for
whom you are checking
permissions. If you include
this argument, do not include
GROUP_NAME.
GROUP_NAME S name Name of a group for which
you are checking permissions.
If you include this argument,
do not include USER_NAME.
LEVEL I security_ level Minimum access permission
level for which you are
checking. Valid values are:
1, for None
2, for Browse
3, for Read
4, for Relate
5, for Version
6, for Write
7, for Delete
OBJECT_LIST S list of object IDs The objects being checked.
This can be a list of SysObject
object IDs, a list of ACL object
CHECK_SECURITY

IDs, or both. Use a space to
delimit the individual items.
Return value
CHECK_SECURITY returns a collection of query result objects. The objects have one
property, r_object_id. The property contains the object IDs of those objects submitted
in the OBJECT_LIST argument for which the user or group has at least the permission
level identified in the LEVEL argument.
Permissions
You must have Superuser privileges to use this method.
Description
There are two uses for CHECK_SECURITY:

• You can use it to determine whether a user or group has a particular access
permission or better for a group of SysObjects
• You can use to determine whether a user or group has entries in one or more ACLs
that give the user or group a particular access permission (or better).
To determine whether a user or group has at least the permission identified in the
LEVEL argument for a particular document, include the document’s object ID in the
OBJECT_LIST argument.
To determine whether a user or group has entries in an ACL that give at least the
permission level identified in the LEVEL argument or better to the user or group, include
the object ID of the ACL in the OBJECT_LIST argument.
The method ignores all object IDs that do not represent SysObjects or ACLs or object IDs
that are incorrectly identified (too few characters, too many characters, and so forth).
None
CHECK_SECURITY
Examples
This example checks to determine whether the user LibbyLoo has at least Write
permission on three documents:
EXECUTE check_security WITH user_name='LibbyLoo',
level=5,object_list='09000001734912ac
0900000153813f2b 0900000116572af3'
This example determines whether the group Engineering has accessor entries that give
the group at least Read permission in the ACLs included in the object list:
EXECUTE check_security WITH group_name='Engineering',
level=3,object_list='4500000112562e4c 450000017351213c'
CLEAN_DELETED_OBJECTS
Purpose Removes deleted lightweight and parent objects from the repository.
Syntax
To remove a deleted parent and all its children:

EXECUTE clean_deleted_objects [[FOR] deleted_parent_object_id]
To remove private parents that no longer have lightweight children:
EXECUTE clean_deleted_objects WITH execution_mode='remove_orphaned_parents'
Arguments
Table 38. CLEAN_DELETED_OBJECTS arguments

execution_mode S remove_ The only value allowed is
orphaned_ remove_orphaned_parent.
parents
Return value
Returns a list of removed objects
Permissions
You must have Sysadmin or Superuser privileges to use this method.
Description
CLEAN_DELETED_OBJECTS removes deleted objects from the database. Since a

shareable parent object can have many lightweight children, for performance reasons,
all the lightweight children are not removed when a shareable parent is deleted. The
dmClean job can be configured to remove these objects as part of the usual repository
cleanup, or this method can be used to start removing the objects immediately.
When a lightweight object is reparented from its private parent to a shareable parent, the
private parent is not deleted until the CLEAN_DELETED_OBJECTS method is run with
remove_orphaned_parents set.
CLEAN_LINKS — Deprecated
Purpose On Windows, this method removes unneeded dmi_linkrecord objects and resets
security on file store objects to the original state. On UNIX, this method removes
unneeded dmi_linkrecord objects and the auxiliary directories and symbolic links.
Syntax
EXECUTE clean_links [WITH force_active=true|false]
Arguments
Argument Name Datatype Value Description

FORCE _ACTIVE B T (TRUE) or F TRUE directs the server to
(FALSE) clean the links in all sessions.
FALSE directs the server to
clean links only in inactive
sessions. The default is FALSE.
Return value
CLEAN_LINKS returns a collection with one query result object. The object has one
Boolean property whose value indicates the success (TRUE) or failure (FALSE) of the
operation.
Permissions
Description
Note: The CLEAN_LINKS method is deprecated. DFC Version 6 does not support
linked storage areas. Consequently, the CLEAN_LINKS method, which supports those
storage areas, is deprecated.
Linked storage areas are handled differently on UNIX and Windows platforms.
Consequently, the behavior of CLEAN_LINKS is slightly different on each platform.
On UNIX, when a linked storage area is referenced, the server creates a dmi_linkedrecord
object and auxiliary directories and symbolic links. On Windows, the server creates a
dmi_linkrecord object and resets the security of the linked storage object. Generally, the
server removes unneeded linkrecord objects and, on UNIX, any unneeded auxiliary
directories and symbolic links. On Windows, the server typically resets the linked
storage object’s security as needed. However, there are conditions that do not allow
the server to do this work.
You can use CLEAN_LINKS to perform this work manually. We recommend running
CLEAN_LINKS regularly. (Note that CLEAN_LINKS is run automatically whenever
the server is restarted.)
To determine if you need to run CLEAN_LINKS, run LIST_SESSIONS and compare the
reported session IDs (in session[x]) to the values in the session_id properties of the
dmi_linkrecord objects. If the session_id property in a link record object references an
inactive session (a session not reported in LIST_SESSIONS), that link record object is not
needed. Depending on how many unneeded link record objects you find, you may want
to run CLEAN_LINKS to remove them and perform the other, associated clean up work.
LIST_SESSIONS, page 273
Examples
This example runs CLEAN_LINKS against only inactive sessions because the
FORCE_ACTIVE argument is defaulted to FALSE:
EXECUTE clean_links
The following example removes the unneeded link record objects for all repository
sessions, active and inactive:
EXECUTE clean_links WITH force_active=true
DB_STATS
DB_STATS
Purpose Returns a set of statistics about database operations for the current session.
Syntax
EXECUTE db_stats [WITH clear = true|false]
Arguments
Table 39. DB_STATS arguments

clear Boolean true | false Indicates whether you want
to clear the counters. The
default is FALSE.
Return value
DB_STATS returns a collection with one result object, described in Table 40, page 212.
Table 40. Query result object properties for DB_STATS administration method

updates integer Number of SQL update operations
performed
inserts integer Number of SQL insert operations
performed
deletes integer Number of SQL delete operations
performed
selects integer Number of SQL select operations
performed
DB_STATS

rpc_ops integer Number of RPC calls between Content
Server and the RDBMS
Note: This may not be implemented for
all databases.
ddl_ops integer Number of data definition operations
performed
Data definition operations are operations

such as create table or drop table.
max_cursors integer Maximum number of concurrently open
cursors
Permissions
Description
DB_STATS returns a set of statistics about database operations for the current session.
The statistics are counts of the numbers of:
• Inserts, updates, deletes, and selects executed
• Data definition statements executed
• RPC calls to the database
• Maximum number of cursors opened concurrently during the session
None
Examples
The following example uses EXECUTE to invoke DB_STATS. It returns the statistics for
the current docbase session and resets the counters to zero:
EXECUTE db_stats WITH clear=true
DELETE_REPLICA
DELETE_REPLICA
Purpose Removes a content file from a component of a distributed storage area.
Syntax
EXECUTE delete_replica FOR 'content_object_id'

WITH STORE='storage_name'
Arguments
Table 41. DELETE_REPLICA arguments

store string storage_name Specifies the component
storage area that contains
the file to remove. This is
a required argument. Use
the storage area’s name as
defined in its storage object.
Return value
DELETE_REPLICA returns a collection with one query result object. The object has one
Boolean property that indicates the success (TRUE) or failure (FALSE) of the operation.
Permissions
DELETE_REPLICA
Description
DELETE_REPLICA removes a content file from a storage area that is a component of a

distributed storage area. Using DELETE_REPLICA also modifies the replica record object
associated with the content. The replica record maintains the information that allows the
server to fetch the content from any of the component storage areas. When you remove a
file from a component storage area using DELETE_REPLICA, this record is updated also.
To use DELETE_REPLICA, you must be using one server for both data and content
requests. If the configuration is set up for content servers, you must issue a connection
request that bypasses the content server to use DELETE_REPLICA in the session.
IMPORT_REPLICA, page 262
Examples
This example removes the content file associated with the content object identified by
06000001684537b1 from the distcomp_2 storage area:
EXECUTE delete_replica FOR '06000001684537b1'
WITH STORE='distcomp_2'
DESTROY_CONTENT
DESTROY_CONTENT
Purpose Removes content objects from the repository and their associated content files
from storage areas.
Syntax
EXECUTE destroy_content FOR 'content_obj_id'
Arguments
DESTROY_CONTENT has no arguments.
Return value
DESTROY_CONTENT returns a collection with one query result object. The object
has one Boolean property that indicates the success (TRUE) or failure (FALSE) of the
operation.
Permissions
Description
DESTROY_CONTENT removes orphaned content objects. An orphaned content object is

a content object that has no values in its parent_id property. The method also removes
the content file referenced by the orphaned content object if there are no other content
objects that reference that file.
The DESTROY_CONTENT method is the method invoked by dmclean.
To run DESTROY_CONTENT, you must be using one server for both data and content
request that bypasses the content server to use DESTROY_CONTENT in the session.
DESTROY_CONTENT
Note: Do not use this method to archive content. It removes the file’s content object,
rather than marking it off‑line.
Destroying content in contentaddressed storage

If the storage area defined in the content object is a content‑addressed storage system (a
ca store storage area), Content Server first determines whether the storage area allows
content to be deleted. If not, DESTROY_CONTENT fails with an error. If the storage
system allows deletions, DESTROY_CONTENT checks the retention period specified for
the content represented by the content object. If there are multiple addresses recorded
for the content, Content Server checks the retention period stored with each address. The
retention period for all addresses must be expired before Content Server can destroy
the content.
Note: Some operations, such as those that modify the metadata or object replication,
result in the generation of a new content address for a content file. These additional
addresses are stored in the i_contents property of a subcontent object.
If that period has not expired, DESTROY_CONTENT cannot remove the file from the
storage area. The method fails with an error. If the retention period has expired or there
is none set, the method removes the content.
PURGE_CONTENT, page 326
Examples
This example uses the EXECUTE statement to invoke DESTROY_CONTENT:

EXECUTE destroy_content FOR '06000001684537b1'
DO_METHOD
DO_METHOD
Purpose Executes an external program, a Docbasic script, or a Java method. (Note that
use of Docbasic is deprecated.)
Syntax
EXECUTE do_method WITH METHOD='method_name'

{,arguments=value}
Arguments
Table 42. DO_METHOD arguments

save_results Boolean true | false Indicates if you wish to save
the results into a document.
arguments string command‑line Specifies the command‑line
arguments arguments for the program.
If the method is to be
executed on the application
server, UTF‑8 characters are
accepted for the argument
strings.
If the method is to be
executed on the method
server or Content Server, only
characters from the server OS
code page are accepted for
the argument strings.
Refer to Specifying the

arguments, page 223, for
more information.
DO_METHOD

time_out integer value Specifies the length in seconds
of the default time‑out period
for the program that you are
executing. Refer to Defining a
time out period , page 223 for
more information.
method string method_name Name of the method object
representing the script,
program, or Java method to
execute.
This argument is required.

launch_direct Boolean true | false Indicates whether to execute
the program using the
Windows (UNIX) system API
or the exec API. Set this to
TRUE to use the system API.
By default, it is FALSE, which
uses the system call. Refer
to Launching directly, page
223 for more information.
This argument is
ignored if the method’s
use_method_server property
is TRUE.
launch_async Boolean true | false Indicates whether to execute
the program asynchronously.
TRUE executes the method
asynchronously. The default
is FALSE.
Setting this argument to

TRUE is ignored if the
SAVE_RESULTS argument
is also TRUE. Refer to
Launching asynchronously,
page 224 for more
information.
DO_METHOD

run_as_server Boolean true | false Indicates whether to run the
method under the server’s
account. If the argument
is not set, the server uses
the value of the method’s
run_as_server property.
You must have Sysadmin or

Superuser privileges to set
this to TRUE on the command
line if the method identified in
the METHOD argument has
its run_as_server property set
to FALSE.
This argument must be TRUE

for methods that have their
use_method_server property
set to TRUE.
trace_launch Boolean true | false Indicates whether to generate
tracing information for the
method.
Recording tracing
information and program
output, page 225 describes
where the information is
stored.
Return value
A DO_METHOD function returns a collection that contains one query result object.
Table 43, page 221 lists the properties of this object.
DO_METHOD
Table 43. Properties of the query result object returned by DO_METHOD

result Integer or ID If the program you launched was dmfilescan
or dmclean, this property holds the object ID
of the script run by the utility.
Otherwise, the property contains an integer

value indicating the success or failure of the
program.
For methods executed on an application

server, the values are:
0, meaning a status of HTTP/1.1 2xx

1, meaning a status of HTTP/1.1 5xx
‑1, for any other status
result_doc_id ID Contains the object ID of the document
that contains the output of the program.
(Note that the output is captured even if the
program times out.)
This property is present only when the

SAVE_RESULTS argument is set to TRUE.
launch_failed Boolean Indicates whether the program was
successfully executed. T means that
the program was not launched and the
method_return_val property is meaningless.
F means that the program was launched and
the return value is the exit code of the process
when the method terminated.
method_return_ Integer Contains the return value of the executing
val program.
For methods executed on the application

server, the values are:
0, for a status of HTTP/1.1 2xx

1, for any other status
For all other methods, if the program times

out, this value is 0.
DO_METHOD
If launch_async is T, then method_return_val

is always 0.
os_system_error String Contains an operating system error if one
occurs. This property can be empty.
timed_out Boolean Indicates whether the DO_METHOD was
terminated due to a timeout. T means the
method was terminated while waiting for the
program to complete. F means the method
received a response.
time_out_length Integer The length of the time‑out period.
Permissions

If the method you are executing has the run_as_server property set to FALSE in its
method object, you must have at least Sysadmin privileges to override that setting in the
DO_METHOD command line.
Description
Use DO_METHOD to execute a Java method, a Docbasic script, or other executable

program. (Note that Docbasic is deprecated.) You can direct the method execution to
the Java method server or Content Server. Docbasic programs are executed by DFC,
using an emulation package. Which you choose depends on the language in which
the program is written and how your site is configured. For details about each of the
execution agents and how to direct a method to the agents, refer to the Documentum
Content Server Administration Guide.
To use DO_METHOD, the invoked script or program must be defined in the repository
by a method object. A method object contains properties that tell the server the
program’s command line and arguments and provide parameters for executing the
program. If the program is a Docbasic script, the script is stored as the content of the
method. (For information about creating method objects, refer to the Content Server
Administration Guide.)
DO_METHOD
Specifying the arguments

There are no restrictions on the format of the argument list for methods executed by
Content Server.
If the method is to be executed using the Java method server (use_method_server is
T and method_type is java), you must pass both argument names and values in the
ARGUMENTS value. The format for value is:
argument_name argument_value
Separate multiple arguments with a single space. For example:

EXECUTE do_method WITH METHOD='payroll_report',
ARGUMENTS='docbase accounting
user auditor
ticket DM_TICKET=0000000222a02024.accounting@host01'
If you are directing the DO_METHOD to the Java method server, Content Server encodes
the arguments using application/x‑www‑form‑urlencoded format. For example, suppose
you issued the following DO_METHOD:
EXECUTE do_method WITH METHOD='paymethod',
ARGUMENTS='docbase accounting
user paymaster
ticket DM_TICKET=0000000222a02054.accounting@host01
document "weekly record"
Content Server sends the arguments in the following format:

docbase=accounting&user=paymaster&ticket=DM_TIICKET%
3D0000000222a02054.accounting%4Dhost01&document=weekly+record
Defining a time out period

The TIME_OUT argument defines a time out period for the program or script you are
executing. Assigning a value to this argument overrides any value assigned to the
timeout_default property in the program’s method object.
The value that you specify cannot be greater than the value assigned to the method
object’s timeout_max property or less than the value assigned to the object’s timeout_min
property. If the maximum or minimum time that you specify on the DO_METHOD
command line violates this rule, the server ignores your specification and uses the
timeout_max or timeout_min value specified in the method object.
Launching directly
When you execute DO_METHOD using Content Server as the execution agent, the
server calls the Windows or Unix (depending on the platform on which the method is
running) system API to execute it by default. If you set LAUNCH_DIRECT to TRUE,
the server calls the exec API instead. This API executes the program or script directly,
instead of calling a shell script, which provides the advantage of better error reporting.
DO_METHOD
To execute with LAUNCH_DIRECT set to TRUE, the method’s method_verb property

must contain a fully qualified pathname.
Launching asynchronously
There are two ways to launch a program or script asynchronously:
• Use the ARGUMENTS argument to DO_METHOD to append an ampersand (&)
to the end of the command line arguments. If there are multiple command‑line
arguments, the ampersand must be the last argument in the list.
For example,
EXECUTE do_method
WITH method = 'validate',arguments = '&'
• Set the DO_METHOD’s LAUNCH_ASYNC argument to TRUE.
For example,
EXECUTE do_method
WITH method = 'validate',launch_async = TRUE
If you launch asynchronously and the method is executing on the application server, it is
not possible to capture the method’s output.
Saving results
For DO_METHOD methods that are executing on the application server, EMC
Documentum provides a simple, example interface that captures the program output so
the output can be saved into the repository if SAVE_RESULTS is TRUE. This interface is
described fully in the Content Server Administration Guide.
Running as the server account

By default, the program invoked by the DO_METHOD runs as the logged‑in user. If you
want the program to execute under the Content Server’s account, you can:
• Set the run_as_server property in the associated method object to TRUE and set the
RUN_AS_SERVER argument in the command line to TRUE.
• Set only the RUN_AS_SERVER argument in the command line to TRUE.
By default, both the run_as_server property and the RUN_AS_SERVER argument are
FALSE. To run as the server account, either both must TRUE or you must override
the property setting by setting the RUN_AS_SERVER argument to TRUE. Overriding
the property in the DO_METHOD command line by setting the RUN_AS_SERVER
argument to TRUE requires Sysadmin or Superuser privileges. (Overriding the property
if it is set to TRUE by setting the RUN_AS_SERVER argument to FALSE requires no
special privileges.)
If you execute DO_METHOD using either the emulation package or the Java method
server as the execution agent, you must set both the method’s run_as_server property
to TRUE and the RUN_AS_SERVER argument to TRUE.
DO_METHOD
Notes:
• If LAUNCH_DIRECT is set to TRUE, either on the command line or in the method’s
property, RUN_AS_SERVER must also be set to TRUE. If it is not, the method does
not execute correctly.
• Content Server uses the assume user program to run procedures and print jobs
as the logged‑in user. If you disable the assume user program (by setting the
assume_user_location property in the server config object to a blank), Content Server
runs all procedures and all print jobs under its account.
Ensuring security on the application server

There are two security issues to consider when using an application server to execute
a DO_METHOD that invokes a Java servlet or method:
• Determining the origin of the HTTP_POST request
• Login without passwords (this is only possible on Windows platforms)
Issuing a DO_METHOD to execute on the application server sends an internal
HTTP_POST request to the application server. The invoked servlet ensures that the
generated request comes from a machine that hosts a Content Server by checking the IP
address of the sender against a list of repositories. This list is set up when the application
server is installed and configured. If the sender’s IP address doesn’t match the IP address
of a repository host, the request fails.
The application server runs as the Content Server installation owner. Consequently, the
servlet it invokes to execute DO_METHOD calls also runs as the installation owner.
On Windows platforms, the current operating system user is allowed to log in to the
repository without providing a password. Consequently, a servlet or an invoked Java
method can log into the repository with superuser privileges without providing a
password.
If you write a method that uses that process to log in, you may want to ensure that the
actual user who issues the DO_METHOD to invoke the method has the appropriate
privileges to execute the program as a superuser. To do this, send the current user’s name
and a login ticket to the method in the arguments. The method can use these to log in and
check the privileges of the user before connecting as the current operating system user.
Recording tracing information and program output

Trace information and program output are two different sets of information. Trace
information is information about the DO_METHOD invocation and its success or failure.
The program output is the results returned by the program called by the DO_METHOD.
Setting TRACE_LAUNCH to TRUE logs tracing information, of up to 2047 characters, to
the repository log. Setting SAVE_RESULTS to TRUE saves the execution output of the
invoked program.
DO_METHOD
EXEC_SQL, page 232

HTTP_POST, page 257
Examples
This example executes the update_accounts procedure, specifying a timeout period of

120 seconds (2 minutes):
EXECUTE do_method
WITH method_name='update_accounts',
time_out=120
The following example executes the user‑defined procedure run_rpt_newaccts and

saves the results to a document:
dmAPIGet("apply,s0,NULL,DO_METHOD,
METHOD,S,run_rpt_newaccts,SAVE_RESULTS,B,T")
This example executes a method on the application server:

dmAPIGet("apply,s0,NULL,DO_METHOD,
METHOD,S,check_vacation,SAVE_RESULTS,B,T,
ARGUMENTS,S,docbase HumanRSRC user adminasst
ticket DM_TICKET=0000000221c02052.HumanRSRC@hr025
document "monthly payroll")
DROP_INDEX
DROP_INDEX
Purpose Destroys a user‑defined object type index.
Syntax
EXECUTE drop_index [[FOR] 'dmi_index_id']

[WITH name = 'index_name']
Do not include the FOR clause if you include the NAME argument.
Arguments
Table 44. DROP_INDEX arguments

name string index_name Identifies the index by the
name of its index (dmi_index)
object.
Return value
DROP_INDEX returns a collection that contains one query result object. The object has
one Boolean property whose value indicates the success (TRUE) or failure (FALSE) of
the operation.
Permissions
Description
You can obtain an object type index’s name or object ID from the dmi_index type table.
Each row in this table represents one index in the repository.
DROP_INDEX
FINISH_INDEX_MOVES, page 236

MAKE_INDEX, page 284
MOVE_INDEX, page 314
Examples
These examples illustrate using EXECUTE to drop a user‑defined index on the dm_user
object type. The first example identifies the index by its name, user_index, and the
second example identifies the index by its object ID.
EXECUTE drop_index WITH name='user_index'
EXECUTE drop_index FOR '1f00000011231563a'
ESTIMATE_SEARCH
ESTIMATE_SEARCH
Purpose Returns the number of results matching a particular SEARCH condition.
Syntax
EXECUTE estimate_search [[FOR] 'fulltext_index_obj_id']

WITH [name = 'index_name'] [,type = 'object_type']
[,query = 'value']
Arguments
Table 45. ESTIMATE_SEARCH arguments

name string index_name Identifies the index to be
searched. This is optional.
You can specify the object ID
of the fulltext index object
instead.
type string object_type Identifies the type of objects
to be searched. All subtypes
of the specified type are
included in the search also.
If not included, the method

searches all object types in the
index.
query string value Defines the word or phrase
for which you are searching.
You can use a Boolean Plus
expression for the value or a
particular word or phrase.
If not included, the method’s

return value represents all
objects in the index.
ESTIMATE_SEARCH
Return value
ESTIMATE_SEARCH returns one of the following:

• The exact number of matches that satisfy the SEARCH condition if the user running
the method is a superuser or there are more than 25 matches.
• The number 25 if there are 0‑25 matches and the user running the method is not
a superuser.
• The number ‑1 if an error occurs during execution.
Errors are logged in the session log file.
Permissions
Any user can execute this method. However, the return value is affected by the user’s
privilege level. Refer to the General Notes for an explanation.
To execute this method, the server.ini key, use_estimate_search, must be set to TRUE.
The key defaults to TRUE.
Description
ESTIMATE_SEARCH is a useful tool for fine‑tuning a SEARCH condition in a SELECT

statement. ESTIMATE_SEARCH provides an estimate of the number of results a query
will return. Use it to determine how selective or unselective a particular query is. Do
not use it to determine the exact number of results a particular query will return. It is
intended only as a way to tune queries. Factors such as security affect the actual number
of results returned when the actual query is run.
If the user executing the method is a superuser, the method returns the exact number of
matches regardless of how few or how many matches are returned.
If the user is not a superuser, the method returns the exact number of matches if the
number is greater than 25. If the number of matches is 0‑25, the method always returns
the number 25.
None
ESTIMATE_SEARCH
Examples
EXECUTE estimate_search WITH name='filestore2_indx',

type='dm_document',query='Competitor Evaluation'
EXEC_SQL
EXEC_SQL
Purpose Executes SQL statements.
Syntax
EXECUTE exec_sql WITH query='sql_query'
Arguments
Table 46. EXEC_SQL arguments

query string sql_query Defines the query that you
want to execute.
Return value
EXEC_SQL returns a collection that contains one query result object. The object has
one Boolean property whose value is TRUE if the query succeeded and FALSE if it
was unsuccessful.
Permissions
You must have superuser privileges to use this method.
Description
EXEC_SQL executes any SQL statement with the exception of SQL SELECT statements.
If you use an IDfSession.apply method to execute the method and the query contains
commas, you must enclose the entire query in single quotes.
In the EXECUTE statement, character string literals must always be single‑quoted:
EXEC_SQL
EXECUTE exec_sql
with query='create table mytable (name char(32), address char(64))'
DO_METHOD, page 218
Examples
Refer to the General Notes.
EXPORT_TICKET_KEY
EXPORT_TICKET_KEY
Purpose Returns a login ticket key.
Syntax
EXECUTE export_ticket_key WITH PASSWORD='password'
Arguments
Table 47. EXPORT_TICKET_KEY arguments

password string password User‑defined password used
to encrypt the returned login
ticket key.
Return value
If successful, the method returns the login ticket key used by the repository as an
encrypted and ASCII‑encoded string. The returned key is encrypted using the password
provided as an argument and then encoded as an ASCII string.
If the method fails, the method returns NULL.
Permissions
You must have Superuser privileges to execute this method.
Description
Use EXPORT_TICKET_KEY when you want to copy a login ticket key from one
repository to another, to configure a trust relationship between the two repositories. (For
a description of trusted repositories, refer to Content Server Fundamentals.)
EXPORT_TICKET_KEY
Related methods
IMPORT_TICKET_KEY, page 264

RESET_TICKET_KEY, page 343
IDfSession.exportTicketKey()
Examples
EXECUTE export_ticket_key WITH PASSWORD='myword'
FINISH_INDEX_MOVES
FINISH_INDEX_MOVES
Purpose Completes all unfinished object type index moves.
Syntax
EXECUTE finish_index_moves
Arguments
FINISH_INDEX_MOVES has no arguments.
Return value
FINISH_INDEX_MOVES returns a collection with one query result object. The object has
the operation.
Permissions
Description
FINISH_INDEX_MOVES completes an interrupted move operation for an object type

index.
Moving an object type index is not an atomic operation. Consequently, if a move
operation is interrupted, the repository may be left with a dmi_index object that has no
associated index. To resolve this situation, use FINISH_INDEX_MOVES. This method
scans the dmi_index table and completes all unfinished index moves.
FINISH_INDEX_MOVES
DROP_INDEX, page 227

Examples
Refer to the syntax description.
FIX_LINK_CNT
FIX_LINK_CNT
Purpose Updates the r_link_cnt property for a folder object.
Syntax
EXECUTE fix_link_cnt FOR foler_object_id
Arguments
None
Return Value
FIX_LINK_CNT returns T (TRUE) if successful or F (FALSE) if unsuccessful.
Permissions
Executing this method requires either Superuser privileges or Write permission on the
specified folder.
Description
Use this method if the value of a folder’s r_link_cnt property is incorrect. The method
determines how many documents are linked to the specified folder and then sets that
value in the folder’s r_link_cnt property.
Examples
EXECUTE fix_link_cnt FOR 0b0000023ca4574f1
GENERATE_PARTITION_SCHEME_SQL
Purpose Creates an SQL script to control repository partitioning.
Syntax
To generate a script to partition a database:

EXECUTE generate_partition_scheme_sql WITH [operation='db_partition',]
[type_name='type_name',|table_name='regtable_name',[owner_name='owner_name',]]
[last_partition ='partition_name',last_tablespace='tablespace',]
partition_name='partition_name',range=integer,tablespace='tablespace'
{,partition_name='partition_name',range=integer,tablespace='tablespace'}
[,include_object_type={TRUE|FALSE}]
To generate a script to add partition(s) to a database:

EXECUTE generate_partition_scheme_sql WITH operation='add_partition',
[type_name='type_name',|table_name=’regtable_name',[owner_name='owner_name',]]
partition_name='partition_name',range=integer,tablespace='tablespace'
{,partition_name='partition_name',range=integer,tablespace='tablespace'}
[,include_object_type={TRUE|FALSE}]
To generate a script to exchange a partition:

EXECUTE generate_partition_scheme_sql WITH operation='exchange_
partition',[temp_table_suffix='temp_table_suffix'],
type_name='type_name',
partition_name='partition_name'
,include_object_type={TRUE|FALSE}
EXECUTE generate_partition_scheme_sql WITH operation='exchange_
partition',[temp_table_suffix='temp_table_suffix'],
table_name=’regtable_name',[owner_name='owner_name',]
partition_name='partition_name'
,include_object_type={TRUE|FALSE}
Arguments
Table 48. GENERATE_PARTITION_SCHEME_SQL arguments

operation string db_partition, Defines the operation that
add_partition, you want to execute. The
or exchange_ only values allowed are:
partition db_partition, add_partition,

and exchange_partition.
Db_partition creates a
script to partition the
database, add_partition
creates a script to add a
partition to the database, and
exchange_partition creates a
script to exchange a partition.
type_name string type_name Specifies a type to partition.
Must be a supertype.
table_name string regtable_name Specifies a registered table.
The table must already have
an i_partition column. Do not
use this for repository‑created
tables; use the type_name
argument for those tables.
owner_name string owner_name The table owner name.
last_partition string partition_name The name of the partition
for objects whose i_partition
value is larger than the
highest range defined.
last_tablespace string tablespace The tablespace of the
last partition (for Sybase
installations use the filegroup
name in place of the
tablespace name).
partition_name string partition_name The name of the partition.
range integer integer Uppermost i_partition value
of an object placed in this
partition.
tablespace string tablespace The tablespace for the
partition (for Sybase
installations use the
filegroup name in place
of the tablespace name).

temp_table_suffix string temp_table_ The suffix for the temporary
suffix table. The default is “x”.
include_object_ Boolean TRUE | FALSE Whether to include
type the internal table
dmi_object_type in
partitioning. The table
can only be included if it has
already been partitioned.
Return Value
GENERATE_PARTITION_SCHEME_SQL returns an object id for the text file containing

the SQL script to generate the partitioning.
Permissions
Description
Use this method to generate a database partitioning script. After the script is generated,
it is run against the underlying database, using the database’s SQL facility. For all
versions of this method, except for add_partition, stop the repository before you run the
script against the database, then restart the repository for the changes to take effect
at the content server level. For the add_partition method, you do not need to stop or
restart the repository.
The first form of the command, in which operation=’db_partition’, allows you to specify
a type or a table to partition. If you do not specify a type or table, the generated script
will partition all the partitionable types in the repository if it is run. You would use this
command to partition a repository that was upgraded from an earlier version. The first
range value means that objects with i_partition values from 0 to the first value will be
in the first partition. The second partition will contain objects with i_partition values
greater than first range value up to the second range value. Each subsequent partition
will contain all the objects with i_partition values greater than the previous partition and
up to its value. The last partition contains those objects with i_partition values greater
than any previously specified partition.
The second form of the command, in which operation=’add_partition’, allows you to add
partitions. This form is similar to the first form, but the first added partition begins
with values greater than previously defined partitions. If there happen to be objects in
the last partition whose i_partition values fall into the new partition’s range, they will
be moved into the new partition.
If you create a new repository with partitioning enabled, there is only one partition,
called the last partition. You can then customize your repository by adding partitions. In
this case, the first added partition range goes from 0 to the value you specified.
The final two versions, in which operation=’exchange_partition’, allow you to exchange a
partition with a schema‑identical offline table in the database tablespace. Commonly,
you would use this feature to load a large number of objects into a table and then swap
the table into the partition.
Note: In order to use this method with an Oracle installation, you must run the script as
SYSDBA. For example, if dmadmin is the installation owner:
C:\Documents and Settings\dmadmin>sqlplus "/as sysdba"
@ C:\Documentum\data\testenv\content_storage_01\00000057\80\00\01\19.txt
Additionally, if you are partitioning a non‑partitioned database, you may want to

increase the number of open database cursors, or the script may exit with the error:
ORA0100 Max Opened Cursors Exceeded
To increase the number of cursors, consult your Oracle documentation. It may tell you to
use a command similar to:
ALTER SYSTEM SET OPEN_CURSORS=2000 SID='*' SCOPE=MEMORY;
to alter the number of open cursors.
If you exit the script with an error (from inadvertently exceeding the number of open
cursors, for example), correct the error, and rerun the script, you may see an error
message like:
ORA12091: cannot online redefine table "TECHPUBS"."DMC_WFSD_ELEMENT_S" with
materialized views
caused by leftover temporary items from the previous script failure. One way to correct
this error is to run a command similar to:
execute DBMS_REDEFINITION.ABORT_REDEF_TABLE('<Schema Name>', '<Table Name>'
,'<Table Name>I');
Where <Table Name>I is the intermediate table name used for the redefinition. From
the previous error message, we would use this command:
execute DBMS_REDEFINITION.ABORT_REDEF_TABLE('TECHPUBS', 'DMC_WFSD_ELEMENT_S'
,'DMC_WFSD_ELEMENT_SI');
SQL Server installations

If you are using a SQL Server installation, use filegroup names as values for the tablespace
attributes, since SQL Server filegroups correspond to tablespaces. For example, use:
tablespace='filegroup'
and
last_tablespace='filegroup'
for SQL Server installations.
Partition Exchange
Partition exchange must be carefully planned. Typically, you will create a number of
offline tables to load with data, use whatever native database method is available to load
the tables, create the table indexes, and then swap the tables into the prepared repository
partition. This technique can load large amounts of data into a repository while causing
a minimum of disruption to normal use of the repository. This technique can also be
used to remove large amounts of data from a repository by swapping out a partition
for small offline tables.
The typical steps you would take to do a partition exchange involve the following:
1. Identify the offline tables to create.

See Documentum High‑Volume Server Development Guide for an example of the tables
to create.
2. Load the offline tables.
Load the tables with data using whatever methods are available to you with your
database.
3. Create the offline index tables.
The offline tables must index the same attributes as the online objects do. The
schema must be identical. Create the offline index tables in the same tablespace
as the current online indexes.
4. Exchange the partition for the offline tables.
Run the GENERATE_PARTITION_SCHEME_SQL administration method to
generate the partitioning script, stop the repository, run the script against the
RDBMS, and restart the repository. After following these steps, the data that was
previously in the offline tables is in the online partition, and the previously online
data is now in the offline table.
5. Validate the exchange.
Check the online data to be sure that the exchange was successful.
More details about executing a partition swap are covered in Documentum High‑Volume
Server Development Guide.
Examples
This example generates a script to partition all the partitionable types in a repository.
After the script is run, partitionable objects with an i_partition value of 0 to 10 will be
stored in partition P1 of the database. Partitionable objects with an i_partition value of 11
to 20 will be stored in partition P2 of the database.
EXECUTE generate_partition_scheme_sql WITH
"partition_name"='P1',"range"=10,"tablespace"='dm_techpubs_docbase',
"partition_name"='P2',"range"=20,
"tablespace"='dm_techpubs_docbase'
To get the script, you can issue the following DQL statement (assume that the result of
the earlier method returned the object ID 0855706080007c19):
EXECUTE get_file_url FOR '0855706080007c19' WITH "format"='text'
GET_FILE_URL
GET_FILE_URL
Purpose Returns the URL to a particular content file.
Syntax
EXECUTE get_file_url FOR object_id

WITH format='format_name'[,page=page_number,]
[page_modifier='value']
object_id is the object ID of the document that contains the content file.
Arguments
Table 49. GET_FILE_URL arguments

format string format_name Name of the content format,
as specified in the format
object.
page integer page_number Page number of the content
file.
Setting this to ‑1 directs the

server to return the URLs
for all primary content pages
and renditions that have the
specified format.
The default is 0.
Return value
GET_FILE_URL returns a collection consisting of one object with five properties. One
property indicates the success or failure of the method call. If the call is successful, the
other property values can be concatenated to compose the URL.
The properties are:
GET_FILE_URL
result Boolean property whose value indicates whether the method

was successful. T (TRUE) indicates successful completion and
F (FALSE) indicates failure.
base_url The value in the base_url property is the base URL used by the
Web server to retrieve the content. This value is retrieved from
the base_url property of the storage area that contains the file.
store The value in the store property is the name of the storage area
that contains the file.
path The value in the path property is a path to the file. The path is
relative to the storage area identified in the store property.
ticket Contains an encryption of the path value plus a time stamp.
Permissions
You must have at least Read permission on the object or Sysadmin privileges to use this
method.
Description
Use GET_FILE_URL in an application when you want to access content using a Web
server or a streaming server.
None
Examples
EXECUTE get_file_url FOR 090000215400ac12

WITH format='jpeg_th',page=0
GET_INBOX
GET_INBOX
Purpose Returns items from an Inbox.
Syntax
EXECUTE get_inbox [WITH name='user_name'][,category=value]

[,batch=value]{,order_by='attr_name [asc|desc]'}]
Arguments
Table 50. GET_INBOX arguments

name string user_name User whose Inbox items you
want to retrieve. The default
value is the session user.
category integer value The kind of items to retrieve.
Valid values are:
1, for workflow tasks

2, for router tasks (obsolete)
4, for notifications
8, for completed router tasks
To retrieve multiple kinds

of items, use the sum of
the integers representing
the items. For example, to
retrieve workflow tasks and
notifications, specify the
value as 5.
The default is 3, workflow

tasks and router tasks.
GET_INBOX

batch integer value Number of items returned
by each IDfCollection.next
method issued against
the collection returned by
GET_INBOX.
The default value is 0,

meaning return all rows.
order_by string attr_name Property by which to order
the returned items.
The property must

be a property of the
dmi_queue_item object
type.
Including asc sorts the

returned items in ascending
order. desc sorts the items
in descending order. The
default is ascending order.
The default ordering is by

r_object_id
Return value
GET_INBOX returns a collection containing the Inbox items in query result objects.
The query result objects have 49 properties. The first 41 are the properties of the
dmi_queue_item object representing the Inbox item. The property names in the query
result object match the names of the properties of the queue items. The remaining 8
properties identify the SysObject associated with the Inbox item, if any. Generally, these
properties have values if the Inbox item is a workflow task. Notification items have no
values in these 8 properties. (Refer to the General Notes for a more detailed explanation.)
Table 51, page 248, lists the SysObject‑related properties and their corresponding
SysObject property.
Table 51. SysObjectrelated property names for GET_INBOX query result objects
Query Result Property Name Associated SysObject Property

pkg_object_id r_object_id
GET_INBOX
Query Result Property Name Associated SysObject Property

pkg_object_name object_name
pkg_object_type r_object_type
pkg_content_type a_content_type
pkg_application_type a_application_type
pkg_link_cnt r_link_cnt
pkg_lock_owner r_lock_owner
pkg_is_virtual_doc r_is_virtual_doc
Permissions
Any user can issue this method to return either his or her own Inbox items or the Inbox
items of another user.
Description
With one exception, you can specify the arguments in any order. The exception is
ORDER_BY. This argument must appear last.
Generally, GET_INBOX returns one query result object for each item in user’s Inbox.
However, if a particular task has multiple objects associated with it, the method returns
one query result object for each object associated with the task. The queue item
property values for the multiple objects will be the same. Only the values of the eight
SysObject‑related properties will be different.
The eight SysObject‑related properties contain null values in the following cases:
• The Inbox item is an event notification and therefore has no associated object.
• The Inbox item is a task, but its associated object has been deleted from the repository.
• The Inbox item is a task but the user who issues the method doesn’t have at least
Browse permission on the associated object.
• The Inbox item is a workflow task, such as a Beginning task, that has no package
attached to it.
• The Inbox item represents an object in a remote repository.
GET_INBOX
None
Examples
This example returns all tasks and notifications for the user issuing the method:
EXECUTE get_inbox WITH category=7
GET_LAST_SQL
GET_LAST_SQL
Purpose Retrieves the SQL translation of the last DQL statement issued.
Syntax
EXECUTE get_last_sql
Arguments
None
Return value
GET_LAST_SQL returns a collection with one query result object. The result object has
one property whose value is the last SQL statement. To see the statement, issue a Next on
the collection and then dump the collection.
If the last SQL tracing option is turned off, this method returns the following error
message:
No SQL Statement is available because Last SQL Trace is disabled.
Permissions
Any one can issue this method.
Description
The last SQL tracing feature is turned on by default when a server starts. If the feature
is turned off, you can turn it on using the last_sql_trace option of the SET_OPTIONS
method. (Refer to SET_OPTIONS, page 357, for instructions.)
GET_LAST_SQL
None
Examples
EXECUTE get_last_sql
GET_PATH
GET_PATH
Purpose Returns the directory location of a content file stored in a distributed storage area.
Syntax
EXECUTE get_path [FOR] 'content_obj_id'

[WITH store = 'value']
Arguments
Table 52. GET_PATH arguments

store string storage_ Specifies a storage area that
component_ contains the file whose full
name path you want to determine.
Use the storage area’s name as
defined in its storage object.
Return value
Returns the directory path of the specified content file.
Permissions
Description
In a content server configuration, the GET_PATH function is executed by the content

server.
GET_PATH
If you do not include the STORE argument, the method looks in the local component of
the distributed storage area. If the file isn’t found in the local area, the method attempts
to create a replica of the file in the local area and returns the path of the local replica.
None
Examples
The following examples return the file path for the content file represented by the content
object whose object ID is 060000027435127c in the storage1 storage area:
EXECUTE get_path FOR '060000027435127c'
WITH store='storage1'
GET_SESSION_DD_LOCALE
Purpose Returns the locale in use for the current session.
Syntax
EXECUTE get_session_dd_locale
Arguments
None
Return value
The method returns a collection with one result object. The result object has one property,
named dd_locale. The value of this property is the locale for the session.
Permissions
Description
None
None
Examples
EXECUTE get_session_dd_locale
HTTP_POST
HTTP_POST
Purpose Sends an HTTP_POST request invoking a Java servlet.
Syntax
EXECUTE http_post WITH app_server_name='name'

[,arguments=argument_list][,save_response=value]
[,time_out=value][,launch_asynch=value][,trace_launch=value]
Arguments
Table 53. HTTP_POST arguments

app_server_name string name Name of the Java servlet.
This must match a

servlet identified in the
app_server_name property of
the server config object.
arguments string argument list Defines the command line
arguments passed to the
servlet or Java method.
UTF‑8 characters are

acceptable for the argument
strings.
save_response integer integer Indicates whether to save the
response in a document in the
repository. Value values are:
0, do not save
1, save the results
‑1, save the results if there is
an error
The default is 0, do not save.
HTTP_POST

time_out integer integer The length of time, in seconds,
to wait for a response to the
HTTP_POST request.
The default is 60 seconds.

launch_async Boolean true | false Indicates whether to execute
the HTTP_POST request
asynchronously. TRUE
executes the HTTP_POST
asynchronously. The default
is FALSE.
This argument is ignored if

SAVE_RESPONSE is TRUE.
trace_launch Boolean true | false Indicates whether to generate
tracing information for the
HTTP_POST request. If
TRACE_LAUNCH is TRUE,
the information is stored in
the server log. The default is
FALSE.
Return value
HTTP_POST returns a collection with one query result object that has seven properties.
Table 54, page 258, lists the properties:
Table 54. Query result object properties for HTTP_POST
Property Name Description

result Indicates the status of the HTTP_POST. Possible
values are:
0, indicating the status HTTP/1.1 2xx

1, indicating the status HTTP/1.1 5xx
‑1, indicating any other status
HTTP_POST
Property Name Description

http_response_status The response returned for the HTTP_POST.
Some example values are:
HTTP/1.1 2xx OK
HTTP/1.1 5xx Internal Server Error
For a complete list of responses, refer to the HTTP

protocol specification.
request_failed Indicates whether the method sent an HTTP request
to the application server. T (TRUE) means the
method failed to send a request. F (FALSE) means
the request was successfully sent to the application
server.
response_doc_id Object ID of the document in which the response is
stored. This only has a value if SAVE_RESPONSE
was set to TRUE.
time_taken Length of time, in seconds, between when the request
was sent and when a response was received. This
represents the execution time of the Java method plus
the time used for communication between Content
Server and the application server.
timed_out Indicates whether the method timed out. T (TRUE)
means that the HTTP_POST method timed out while
waiting for a response. F (FALSE) means that a
response was received.
time_out_length Time, in seconds, of the time out period.
Permissions
You must have Superuser privileges to execute this method. (Refer to Preserving security,
page 260, for more information about security when using this method.)
Description
Use HTTP_POST to invoke a servlet or Java method installed in an application server.
HTTP_POST
If you set LAUNCH_ASYNC to TRUE, Content Server closes the connection to the
application server immediately after sending the request. If LAUNCH_ASYNC is
FALSE, the server waits for a response until a response is received or the time out
period is reached.
Setting TRACE_LAUNCH to TRUE logs tracing information about the invocation of the
HTTP_POST method and its success or failure.
The ARGUMENTS argument can contain only UTF‑8 characters. Content Server encodes
the arguments using application/x‑www‑form‑urlencoded format. For example, suppose
you issued the following HTTP_POST method:
EXECUTE http_post WITH app_server_name='payroll',
save_response=true,trace_launch=true,
arguments='docbase accounting user paymaster
ticket DM_TICKET=0000000222a02054.accounting@host01
document "weekly record"'
Content Server sends the arguments in the following format:

docbase=accounting&user=paymaster&ticket=DM_TIICKET%
3D0000000222a02054.accounting%4Dhost01&document=weekly+record
Preserving security
The application server, all servlets that it invokes, and the methods invoked by the
servlets run as the Content Server installation owner, which is an account with Superuser
privileges. Consequently, it is important that they are written and execute using
adequate security precautions.
There are two primary security issues:
• Determining origin of HTTP_POST requests
• Login without passwords (this is only possible on Windows platforms)
The application server or the servlet has no inherent way to know whether the
HTTP_POST request was sent from a Documentum Server. When you write a servlet,
you must include security checking to ensure that the request comes from a Documentum
Server. One recommended way is have the servlet ensure that the generated request
comes from a machine that hosts a Content Server by checking the IP address of the
sender against a list of valid IP addresses. (This is how the do_method servlet checks the
origin. Refer to Installing Content Server for information about how that is set up.)
On Windows platforms, the current operating system user is allowed to log in to the
repository without providing a password. Consequently, a servlet or an invoked Java
method can log into the repository with Superuser privileges without providing a
password.
If you write a servlet or method that uses this manner of login, you may want to
ensure that the actual user who issues the HTTP_POST to invoke the program has the
appropriate privileges to execute the program as a superuser. To do this, send the
current user’s name and a login ticket to the method in the arguments. The method
HTTP_POST
can use these to log in and check the privileges of the user before connecting as the
current operating system user.
Sample servlet and method

Documentum provides a sample servlet for handling HTTP_POST method calls and a
sample method. The servlet is named DmSampleServlet.java and the method is named
DmSampleMethod.java. The sample servlet and method are located in the classes folder
under the WEB‑INF folder. The WEB‑INF folder was set up when you installed the
application server.
Recording output
If you set SAVE_RESPONSE to TRUE, then anything that the invoked servlet writes to
HttpServerletResponse.OutputStream is saved to a document in the repository.
DO_METHOD, page 218
Examples
The following examples send an HTTP_POST request to the Java servlet called
DevAppSrv. The content of the request passes a repository name, user name, a login
ticket, and a document name to the Java servlet.
EXECUTE http_post WITH app_server_name='DevAppSrv',
save_response=1,trace_launch=T,time_out=60,
arguments='docbase DevTest user test_user
ticket DM_TICKET=0000000221c02052.DevTest@dev012
document "A Test"'
IMPORT_REPLICA
IMPORT_REPLICA
Purpose Imports files from one distributed storage area into another distributed storage area.
Syntax
EXECUTE import_replica FOR 'content_object_id'

WITH store='storage_name',file='file_name'
[,other_file='other_file_name']
Arguments
Table 55. IMPORT_REPLICA arguments

store string storage_name Identifies the storage area in
which to place the imported
content file. This must be a
component of a distributed
storage area. Use the storage
area’s name.
file string file_name Identifies the file to replicate.
other_file string other_file_name The OTHER_FILE argument
is optional. It directs the
server to copy the specified
Macintosh resource fork
file in addition to the data
file. Specify the name of the
resource fork file.
Use this only when the

file you are importing was
created on a Macintosh.
IMPORT_REPLICA
Return value
IMPORT_REPLICA returns a collection with one query result object. The object has one
property whose value indicates success (TRUE) or failure (FALSE).
Permissions
Description
IMPORT_REPLICA imports files from one distributed storage area into another
distributed storage area. The files are considered replicas in the target storage area.
To use IMPORT_REPLICA, you must be using one server for both data and content
request that bypasses the content server to use IMPORT_REPLICA in the session.
CAN_FETCH, page 196

DELETE_REPLICA , page 214
GET_PATH, page 253
REPLICATE, page 340
Examples
The following examples import the file mydoc into the storage area named distcomp_2:
EXECUTE import_replica FOR '06000001402371e1'
WITH store='distcomp_2',FILE='mydoc'
IMPORT_TICKET_KEY
IMPORT_TICKET_KEY
Purpose Imports a login ticket key into a repository.
Syntax
EXECUTE import_ticket_key
WITH KEY_STRING='string',
PASSWORD='password'
Arguments
Table 56. IMPORT_TICKET_KEY arguments

key_string string string The ASCII‑encoded
string returned by an
EXPORT_TICKET_KEY
method.
password string password Password used when the key
was exported.
Return value
This method returns a collection with one query result object. The object has one
property, named result, that contains T (TRUE) if the method was successful or F
(FALSE) if unsuccessful.
Permissions
IMPORT_TICKET_KEY
Description
Use IMPORT_TICKET_KEY to import a login ticket key into a repository. The key must
have been exported from a repository using the EXPORT_TICKET_KEY method. When
you import the key, the password argument in IMPORT_TICKET_KEY must be the same
password that you used in the EXPORT_TICKET_KEY method.
You must restart Content Server after importing a login ticket key to make the key take
effect.
Keys are typically exported from one respository and imported into another as part of
the configuration process when setting up trusted respositories, to allow use of global
login tickets or tokens. (For a description of trusted repositories, global login tickets, and
global tokens, refer to Content Server Fundamentals.)
EXPORT_TICKET_KEY, page 234

RESET_TICKET_KEY, page 343
IDfSession.importTicketKey()
Example
EXECUTE import_ticket_key
WITH KEY_STRING='ticket_string',
PASSWORD='myword'
LIST_AUTH_PLUGINS
LIST_AUTH_PLUGINS
Purpose Lists the authentication plugins that the server has loaded.
Syntax
EXECUTE list_auth_plugins
Arguments
None
Return value
The method returns a collection with one query result object. The object has two
repeating string properties, plugin_id and plugin_filepath. The values in plugin_id are
the unique plugin identifiers and the values in plugin_filepath are the full paths of the
plugins. The values at corresponding index positions represent one plugin.
Permissions
You must have Sysadmin or Superuser privileges to execute this method.
Description
This method is useful only at sites that have a Trusted Content Services license because
the ability to use authentication plugins is a feature of Trusted Content Services.
None
LIST_AUTH_PLUGINS
Examples
Refer to the syntax.
LIST_RESOURCES
LIST_RESOURCES
Purpose Lists a variety of information about the server’s operating system environment
and the server.
Syntax
EXECUTE list_resources [WITH reset=true|false]
Arguments
Table 57. LIST_RESOURCES arguments

RESET B T (TRUE) or F TRUE reinitializes the
(FALSE) file handle and heap size
counters. FALSE keeps the
present values of the counters.
Return value
LIST_RESOURCES returns a collection with one query result object. On Windows

platforms, the query result object has twelve properties, described in Table 58, page 268.
Table 58. Collection properties for LIST_RESOURCES

file_handles_in_use integer The number of file handles in use
by the main thread and all session
threads (Windows) or the current
child process (UNIX).
file_handles_max integer The configured limit at the
operating‑system level on the
number of file handles the process
can open.
LIST_RESOURCES

file_handles_new integer A counter that indicates how
many file handles have been
created or destroyed since the last
LIST_RESOURCES with RESET
= T. If the number is negative, it
means that there are fewer handles
open than there were at the last
LIST_RESOURCES call. (Issuing
LIST_RESOURCES with RESET=T
reinitializes file_handles_new to
zero.)
session_heap_size_max integer Maximum size, in bytes, of a thread’s
session heap. When a session is
started, its maximum heap size
corresponds to this value. A value of
‑1 indicates that the size of the session
heap will be unconstrained (the heap
will grow to whatever size the server
machine resources will allow).
current_heap_size_max integer Maximum size of the thread’s session
heap. This reflects the value that was
in session_heap_size_max when the
session was started, and is the size of
the heap available to the session.
session_heap_size_in_use integer How much, in bytes, of the currently
allocated heap (virtual memory) is in
use by the session.
session_heap_size_new integer A count of the bytes that the heap
has grown or shrunk since the last
reinitializes session_heap_size_new
to zero.)
root_heap_size_in_use integer How much, in bytes, of the main
server thread’s heap is in use.
LIST_RESOURCES

root_heap_size_new integer A count of the bytes that the heap
LIST_RESOURCES call.
Issuing LIST_RESOURCES
with RESET=T reinitializes
session_heap_size_new to zero.
max_processes integer The maximum number of processes
that can be created by the account
under which the server is running.
server_init_file string(255) The full path to the server’s server.ini
file.
initial_working_directory string(255) The full path to the directory
containing the server executable.
On UNIX, the result object has eight properties, described in Table 59, page 270.
Table 59. Collection properties for LIST_RESOURCES

file_handles_in_use integer The number of file handles in use
by the main thread and all session
threads (Windows) or the current
child process (UNIX).
file_handles_max integer The configured limit at the
operating‑system level on the
number of file handles the process
can open.
file_handles_new integer A counter that indicates how
many file handles have been
created or destroyed since the last
LIST_RESOURCES with RESET
= T. If the number is negative, it
means that there are fewer handles
open than there were at the last
reinitializes file_handles_new to
zero.)
heap_size_in_use integer The size, in bytes, of the session heap.
LIST_RESOURCES

heap_size_new integer A count of the bytes that the heap
LIST_RESOURCES call.
Issuing LIST_RESOURCES with

RESET=T reinitializes heap_size_new
to zero.
max_processes integer The maximum number of processes
that can be created by the account
under which the server is running.
server_init_file string(255) The full path to the server’s server.ini
file.
initial_working_directory string(255) The full path to the directory
containing the server executable.
Permissions
Description
LIST_RESOURCES lists a variety of information about the server operating system

environment and the server (the information is described in Return value, page 268).
DB_STATS, page 212

LIST_TARGETS, page 278
SHOW_SESSIONS, page 363
Examples
The following examples return the resources information and reset the heap size
counters:
LIST_RESOURCES
EXECUTE list_resources WITH reset=true
LIST_SESSIONS
LIST_SESSIONS
Purpose Returns information about all the currently active repository sessions.
Syntax
EXECUTE list_sessions[WITH brief_info=true|false]
Arguments
Table 60. LIST_SESSIONS arguments

BRIEF_INFO B T (TRUE) or F Indicates whether you want
(FALSE) a subset of the properties in
the result object. The default
is FALSE.
Return value
LIST_SESSIONS returns a collection. Each result object in the collection describes one
currently active session or one historical session.
If BRIEF_INFO is FALSE
Table 61, page 273 lists the information returned if BRIEF_INFO is FALSE.
Table 61. Complete information returned by LIST_SESSIONS (BRIEF_INFO=F)
Property Description
root_start The time when the main server thread
(root server process) was started.
LIST_SESSIONS
root_pid On Windows, the process ID of the
Content Server process.
On UNIX, the process ID of the root

Content Server process.
shared_mem_id The ID of the shared memory segment
used by the servers.
This property is returned only on UNIX

platforms.
semaphore_id The ID of the semaphore used by the
servers.
This property is returned only on UNIX

platforms.
session The object ID of the session begun by
user_name.
db_session_id The ID of the database session.
typelockdb_session_id The database session ID for type locking
tempdb_session_ids List of temporary database sessions
pid The ID of the session thread (process).
user_name The user name of the user who started the
session.
user_authentication The user authentication state for the
session. Possible values are password,
ticket, trusted client, change password, or
in progress.
If the value is change password, the

user logged in for that session can only
perform the change password operation.
No other operations are allowed.
client_host The host name of the machine on which
the session was started.
client_lib_ver The version number of the DFC in use for
the session.
LIST_SESSIONS
client_locale A verbose description of the client’s
environment, including the operating
system version, the character set in use,
the language in use, and the date format.
start The starting time of the session.
last_used The last time the client session contacted
the server.
session_status The session status. Active means that the
session is connected and has not timed
out. Inactive means that the session has
timed out.
shutdown_flag Records the setting of the immediacy_level
argument in the kill method.
last_rpc The last RPC the server ran for the session
current_rpc The current RPC being run by the server
for the session
Note that after the RPC is completed the

server will not clear this field. Therefore,
if last_rpc and current_rpc have the same
value, either the server has completed an
RPC for the session and has not executed
another RPC, or the server is running the
same RPC again.
last_completed_rpc The last time the server completed an RPC
for the session
If BRIEF_INFO is TRUE
Table 62, page 275, lists the information returned if BRIEF_INFO is TRUE.
Table 62. Brief information returned by LIST_SESSIONS (BRIEF_INFO=T)
session The object ID of the session begun by
user_name.
db_session_id The ID of the database session.
user_name The user name of the user who started the
session.
LIST_SESSIONS
client_host The host name of the machine on which
the session was started.
start The starting time of the session.
last_used The last time the client session contacted
the server.
session_status The session status. Active means that the
session is connected and has not timed
out. Inactive means that the session has
timed out.
Permissions
Description
LIST_SESSIONS returns a collection of query result objects whose properties contain

information about all the currently active sessions and a user‑specified number of
historical sessions. The historical sessions are past sessions that are not currently active.
The maximum number of historical sessions returned by LIST_SESSIONS is determined
by the parameter history_sessions in the server’s startup file (the server.ini file). There
is also a startup parameter, called history_cutoff, to define a cutoff time for the history
sessions. For example, if history_cutoff is set to 15 minutes, then LIST_SESSIONS will
not return any historical sessions older than 15 minutes.
For a description of the server.ini file and the parameters you can set in it, refer to the
Content Server Administration Guide.
If you have a large number of active sessions, use SHOW_SESSIONS, page 363, instead
of LIST_SESSIONS.
SHOW_SESSIONS, page 363
LIST_SESSIONS
Examples
This example executes LIST_SESSIONS with the BRIEF_INFO argument defaulted to

FALSE:
EXECUTE list_sessions
This example executes LIST_SESSIONS with the BRIEF_INFO argument set to TRUE:
EXECUTE list_sessions WITH brief_info='true'
LIST_TARGETS
LIST_TARGETS
Purpose Lists the connection brokers to which the server is currently projecting.
Syntax
EXECUTE list_targets
Arguments
LIST_TARGETS has no arguments.
Return value
LIST_TARGETS returns a collection with one query result object. The Table 2‑9. The
values across the properties at one index position represent the information about one
connection broker to which the server is projecting.
Table 63. Query result object properties for LIST_TARGETS

projection_targets string(80) A repeating property that contains the
names of the hosts on which the target
connection brokers are running.
projection_proxval integer A repeating property that contains the
proximity value projected to the connection
broker identified in the corresponding
index position in projection_targets.
projection_notes string(80) A repeating property that contains any
user‑defined note for the connection
broker defined at the corresponding
index position in projection_targets and
projection_proxval.
LIST_TARGETS

docbroker_status string(64) A repeating property that records whether
the connection broker identified in
projection_targets at the corresponding
index position is available. Valid values are:
Available and Unavailable.
comments string(64) A repeating property that records whether
the projection target entry was taken from
the server config object or the server.ini file.
Permissions
Description
A server’s connection broker targets are those connection brokers to which the server
is sending checkpoint messages. Target connection brokers are defined in the server’s
server config object and may also be defined in the server.ini file. This method returns a
list of the targets defined in the server config object.
None
Examples
The following examples list the current connection broker targets for the server:
EXECUTE list_targets
LOG_OFF
LOG_OFF
Purpose Turns off the RPC logging.
Syntax
EXECUTE log_off
Arguments
LOG_OFF has no arguments.
Return value
LOG_OFF returns a collection with one query result object. The object has one Boolean
property whose value indicates the success (TRUE) or failure (FALSE) of the operation.
Permissions
Description
None
LOG_ON, page 282
LOG_OFF
Examples
The following example turns off RPC logging:

EXECUTE log_off
LOG_ON
LOG_ON
Purpose Turns on logging for RPC calls.
Syntax
EXECUTE log_on [WITH detail=true|false]
Arguments
Table 64. LOG_OFF arguments

DETAIL B T (TRUE) or F Indicates whether you
(FALSE) want information about the
arguments passed with the
RPC call and the results. The
default is FALSE.
Return value
LOG_ON returns a collection with one query result object. The object has one Boolean
Permissions
Description
The LOG_ON function turns on logging for RPC calls.

If you execute the LOG_ON function without including the DETAIL argument, the
server logs information about the start and stop names and time information for the
LOG_ON
operation. If you set DETAIL to TRUE, the server also includes information about the
arguments passed with each call and the results of the call.
LOG_OFF, page 280
Examples
These examples turn on detailed RPC logging:

EXECUTE log_on WITH detail=true
MAKE_INDEX
MAKE_INDEX
Purpose Creates an index for a persistent object type.
Syntax
EXECUTE make_index
WITH type_name='object_type',attribute='property_name'
{,attribute='property_name'}
[,unique=true|false][,index_space='name'][,index_name='name']
[,use_id_col=true|false]
[,global_index=true|false]
Arguments
Table 65. MAKE_INDEX arguments

TYPE_NAME S object_type Identifies the object type for
which to create an index.
This is a required argument.

ATTRIBUTE S property_name Identifies the property or
properties on which to build
the index. You can specify
multiple properties, but you
cannot mix single‑valued and
repeating properties in the
same statement.
UNIQUE B TRUE or FALSE Indicates whether to create a
unique index. The default is
FALSE.
INDEX_SPACE S Name of Specifies the tablespace or
tablespace or segment in which to store
segment the index. If unspecified,
the default is the tablespace
or segment in which the
repository resides.
MAKE_INDEX

INDEX_NAME S Name of index Specifies the name of the
table index table. If unspecified,
the system generates this
name.
USE_ID_COL B TRUE or FALSE Indicates whether to include
the r_object_id column value
in the index. The default is
FALSE.
GLOBAL_INDEX B TRUE or FALSE Indicates whether the index
being created is a global
index. This parameter can
only be used for partitioned
types. The default is FALSE.
Return value
MAKE_INDEX returns a collection with one query result object. The object has one
property, named result, that contains the object ID of the dmi_index_object for the new
index if successful.
If the method failed because the syntax was incorrect or the property specified did not
exist, the result property contains F (FALSE).
If the specified index already exists, the result property contains ’0000000000000000’.
Permissions
Description
MAKE_INDEX creates an index for a persistent object type. You can create an index for
any persistent object type.
You can specify one or more properties. However, if you specify multiple properties,
you must specify all single‑valued properties or all repeating properties. You cannot mix
single and repeating valued properties in the same argument list. (This is because the
underlying RDBMS stores an object’s single and repeating properties in separate tables.)
MAKE_INDEX
If you specify multiple properties, the sort order within the index corresponds to the
order in which the properties are specified in the statement. To include the r_object_id
column in the index, include the USE_ID_COL argument.
The properties you specify must be defined for the type you specify. They cannot be
inherited properties. For example, if you want to create an index on the subject and
title properties, you would specify dm_sysobject in TYPE_NAME, as these properties
are defined for dm_sysobject. (The Object Reference Manual lists the properties defined
for each object type.)
A unique index is an index in which the values in the columns to be indexed are unique
within the index. If you include the UNIQUE argument, the RDBMS server enforces
the uniqueness.
GLOBAL_INDEX is a boolean parameter that indicates whether the index being created
is a global index. The default value is FALSE. This parameter can be used only when
the type is a partitioned type, and is only useful if UNIQUE=TRUE is also specified. If
an index of a partitioned table is a unique local index, it must include the i_partition
column as part of the index. Otherwise, the database server will return an error. This
is a requirement of the database for unique local indexes in a partitioned table. Since
i_partition is an internal attribute, both single value tables and repeating value tables
have this column. The internal attribute i_partition will not be included for unique
indexes created for a partitioned type if GLOBAL_INDEX is TRUE.
Note: If you plan to use partition exchange, do not create global indexes on the types
to use for the exchange. See EMC Documentum High‑Volume Server Development Guide
for more details on partition exchange.

Examples
This example creates an index for the dm_sysobject object type, indexing on the subject
and title properties:
EXECUTE make_index WITH type_name='dm_sysobject',
attribute='subject', attribute='title'
The next example creates an index for the dm_sysobject type on the property
r_creator_name:
MAKE_INDEX

attribute='r_creator_name'
The next example creates an index for the dm_sysobject type on the properties
r_creator_name and r_creation_date:
attribute='r_creator_name',
attribute='r_creation_date'
MARK_AS_ARCHIVED
MARK_AS_ARCHIVED
Purpose Sets the i_is_archived property of an audit trail entry to TRUE.
Syntax
EXECUTE mark_as_archived FOR audit_obj_id
audit_obj_id is the object ID of the audit trail entry. This is a dm_audittrail,

dm_audittrail_acl, or dm_audittrail_group object.
Arguments
This method has no arguments.
Return value
The method returns TRUE if successful or FALSE if unsuccessful.
Permissions
Description
Use this method to set an audit trail entry’s i_is_archived property to TRUE after you
archive the entry.
PURGE_AUDIT, page 318
MARK_AS_ARCHIVED
Examples
EXECUTE mark_as_archived FOR 5f000012ae6217ce
MARK_FOR_RETRY
MARK_FOR_RETRY
Purpose Finds queue items representing events queued to the Index Agent that are in the
acquired or failed state and resets them to the pending state
Syntax
EXECUTE mark_for_retry
WITH NAME = 'index_name'
Arguments
Table 66. MARK_FOR_RETRY arguments

NAME S index_name Identifies the index that
contains the objects to mark
for a retry. Use the name
associated with the index’s
fulltext index object.
Return value
MARK_FOR_RETRY returns a collection with one query result object. The object has
the operation.
Permissions
MARK_FOR_RETRY
Description
Use MARK_FOR_RETRY in the recovery procedure if you encounter problems with the
index agent. The method scans the repository to find queue items representing events
queued to the index agent that are in the acquired or failed state and resets them to
the pending state.
The index agent registers itself for certain events on all SysObjects. The events serve
as notice to the index agent that the objects need to be indexed or updated in the
index. If there is a problem with the index agent, for example, if it crashes, some of
the queue items representing those events may be left in the acquired or failed state.
MARK_FOR_RETRY is used to reset those events to pending so that the index agent will
pick up those events and properly process the objects after the problem is resolved.
None
Examples
These examples find all the content objects in the index that have an update_count value
of ‑5 and marks them for a retry:
EXECUTE mark_for_retry
WITH NAME = 'storage1_index'
MIGRATE_CONTENT
MIGRATE_CONTENT
Purpose Moves content files from one storage area to another.
Syntax
To migrate a single object:

EXECUTE migrate_content [FOR]object_id
WITH target_store='target_storage_name'
[,renditions=value][,remove_original=T|F][,log_file='log_file_path']
To migrate all objects in a particular storage area:

EXECUTE migrate_content WITH source_store='source_storage_name',
target_store='target_storage_name',log_file='log_file_path'
[,max_migrate_count=value][,batch_size=value]
[,remove_original=T|F][,parallel_degree=value]
To migrate a set of objects identified by a DQL query:

EXECUTE migrate_content WITH target_store='target_storage_
name',query='DQL_predicate'[,sysobject_query=T|F [,type_to_query=
'type_name'],log_file='log_file_path'
[,renditions=value][,max_migrate_count=integer][,batch_size=value]
[,remove_original=T|F][,parallel_degree=value]
Arguments
Table 67. MIGRATE_CONTENT arguments

object_id ID content_object When migrating a single
ID or SysObject content file, you can identify
ID the file using its content
object ID or the object ID of
the SysObject (or SysObject
subtype) that contains the
content file.
Specifying a content object ID

requires Superuser privileges.
Specifying a SysObject object
MIGRATE_CONTENT

ID requires Write permission
on the object.
SOURCE_STORE S source_storage_ Name of the storage area
name whose content you wish to
migrate. The storage area
may be a file store, a ca store,
a blobstore, or a distributed
store. Use the name of the
storage area’s object.
TARGET_STORE S target_storage_ Name of the storage area to
name which you are migrating the
content. The storage area
may be a file store, a ca store,
or a distributed store. Use
the name of the storage area’s
object.
(Blobstores cannot be
specified as a target storage
area.)
RENDITIONS S all, primary, or Indicates which content files
secondary associated with the SysObject
or SysObjects you wish to
move. This argument is
used only when object_id
references a SysObject or
when SYSOBJECT_QUERY is
set to T. Valid values are:
all, meaning move the first

primary content file (page 0)
and its renditions
primary, meaning move only

the first primary content file
(page 0)
secondary, meaning move

only the renditions of the first
primary file (page 0)
The default is primary.
MIGRATE_CONTENT

REMOVE_ B T (TRUE) or F Whether to remove the
ORIGINAL (FALSE) content file from the source
storage area. T directs
Content Server to remove
the original content file if
possible. F directs Content
Server not to remove the
content.
If set to F, you must include

the LOG_FILE argument also.
The default is T.
LOG_FILE S log_file_path Identifies where to log
messages generated by the
method.
You must include this

argument if you are moving
all content from one storage
area to another or if you are
using a DQL predicate to
select content for migration.
MAX_MIGRATE_ I value Defines the maximum
COUNT number of content files to
migrate.
BATCH_SIZE I value Defines how many content
files to include in a single
transaction during the
migration operation (or how
many files per worker session
if PARALLEL_DEGREE is
greater than 1).
The default is 500.
MIGRATE_CONTENT

PARALLEL_ I value Defines how many content
DEGREE migration sessions are created
to do the migration.
The default value is 0,

indicating that a single
session is created and
migration will not be done in
parallel.
The maximum value

default is 10, but can be
modified by setting the
max_cm_parallel_degree
parameter in the server.ini
file. The valid range for
this parameter is 1 to 128.
PARALLEL_DEGREE is
set to a value greater than
max_cm_parallel_degree,
the server will use the
max_cm_parallel_degree
value instead.
QUERY S dql_predicate Specifies a DQL predicate to
be used to select content files
for migration.
This must be a valid WHERE

clause qualification.
The predicate is applied

to either content objects
or SysObjects, depending
on the setting of the
SYSOBJECT_QUERY
argument.
For more information, refer

to the Usage Notes.
MIGRATE_CONTENT

SYSOBJECT_ B T (TRUE) or F T directs the method to
QUERY (FALSE) apply the DQL predicate
specified in the QUERY
argument to SysObjects or
the subtype identified in
TYPE_TO_QUERY. F directs
the method to apply the
predicate to content objects.
The default is F.
TYPE_TO_QUERY S type_name Name of a SysObject subtype.
You can include this only

if SYSOBJECT_QUERY is
set to T. If specified, the
DQL predicate is applied
to the subtype, rather than
dm_sysobject type. For
information about the uses
of this argument, refer to
Including a query, page 298.
Return value
The method returns a collection with one query result object. The object has one integer
property, named result, whose value is the number of contents successfully migrated.
Permissions
Superuser permissions are required to:

• Specify a content object ID when moving a single content file.
• Move all content from one storage area to another.
• Move content using a DQL predicate that operates on content objects
(SYSOBJECT_QUERY=F)
Write permission on the object is required to:
• Specify a SysObject ID when moving the content of a single object.
• Move content using a DQL predicate that operates on a SysObject
(SYSOBJECT_QUERY=T)
MIGRATE_CONTENT
Description
General notes
MIGRATE_CONTENT is the preferred way to move content files from a file store, ca
store, blobstore, or distributed store storage area to a file store, ca store, or distributed
store storage area. You cannot move content to a blob store storage area. Additionally,
you cannot use this method to move files to or from turbo or external storage. If content
is stored in a retention‑enabled ca store storage area, you can only move the content
to another retention‑enabled ca store storage area. If you move a file to a distributed
storage area, the file is placed in the distributed component local to the Content Server
to which you are connected when executing the method.
The method moves content files associated with immutable objects as well as changeable
objects. It does not update a SysObject’s r_modify_date property when the object’s
content is moved. You must use this method if you want to move content files from an
unencrypted storage area to an encrypted storage area. The method allows you to move
one file, all files in a particular storage area, or a set of files selected by a DQL WHERE
clause qualification.
The method operates on dmr_content objects, resetting their storage_id property to the
new storage area and resetting the data ticket property. It also updates the i_vstamp
property. The i_vstamp property is also incremented for any SysObject that contains the
content file as the first primary content (page 0). (Consequently, if the affected content
objects are associated with replicated SysObjects, the next replication job for those objects
will refresh the objects.) Similarly, if the content objects are associated with persistently
cached objects, the next time the cached objects are accessed by the client, they will
be refreshed.
Here are some general guidelines for using MIGRATE_CONTENT:
• If you want to move content to or from a distributed storage area, you must specify
the dm_distributedstore object as the target or source storage area—do not specify
the actual distributed component.
• Make sure none of the objects whose content you intend to migrate are checked out.
If the method attempts to migrate content associated with a checked out object,
the method fails with an error.
• If the content to be migrated is stored in a content‑addressed storage area with a
retention date, make sure the retention date has expired. If not, the method fails
with an error.
• If the content’s current storage area and the target storage area are the same
content‑addressed storage area and the storage area has a retention period, the
method updates the content’s metadata and retention period and creates a new
address for the content. However, the content is not physically moved.
MIGRATE_CONTENT
• Back up the repository and the file store storage areas before using the method.
• Make sure that the target storage area has enough disk space to hold the migrated
content.
• If you choose not to remove the original content, that content becomes an orphaned
content file and can be removed using dmfilescan.
Migrating to contentaddressed storage

If you move a file that has a retention policy to a content‑addressed storage area, the
retention set on the object is calculated from the retention policy even if the default
retention for the content‑addressed storage area is further in the future. If there are
multiple retention policies on the object, the method sets the retention on the file based
on the policy with the retention date furthest in the future.
If you are moving content files to a content‑addressed storage area that requires
a retention date, you must set the retention date for the content before migrating
the content. Use either a setContentAttrs method or the SET_CONTENT_ATTRS
administration method to set the retention date.
Note: A content‑addressed storage area requires a retention date if:
• The storage area’s a_retention_attr_name property is set and the
a_default_retention_date is not null, or
• The a_retention attr_name property is set and the a_retention_attr_required property
is set to T
Including a query
You can include a DQL predicate in the method arguments. Depending on the value of
the SYSOBJECT_QUERY argument, the predicate is run against instances of a specified
object type or against content objects.
SYSOBJECT_QUERY is F (FALSE) by default, meaning that the predicate is applied to
content objects. You must have Superuser permissions to run the predicate against
content objects. When you run the query against content objects, it is recommended
that you use a predicate that references a unique value in the content object. For
example, reference the storage area ID—there is only one storage area in the repository
with any given storeage ID. You cannot include the TYPE_TO_QUERY argument if
SYSOBJECT_QUERY is set to F.
If SYSOBJECT_QUERY is T and the TYPE_TO_QUERY argument is not included,
the predicate executes against instances of the dm_sysobject type. However, if
SYSOBJECT_QUERY is T and the TYPE_TO_QUERY argument is included, the
predicate executes against instances of the object type specified in the TYPE_TO_QUERY
argument. When the query is executed, the method affects the content of only those
objects that match the query and for which you have at least Write permission.
MIGRATE_CONTENT
When the query is run against instances of an object type, the properties specified in
the DQL predicate must be defined for the object type. Consequently, if you want to
specify custom properties of a SysObject subtype in the predicate, you must include the
TYPE_TO_QUERY argument and identify the subtype in that argument.
For example, suppose you want to migrate all content of a subtype called
“loan_documents”, and that subtype has a property named customer_state. The
following MIGRATE_CONTENT statement will execute against all loan_document
objects and moves the content for those belonging to customers in CA (California) state:
EXECUTE migrate_content
WITH target_store='storage_005',
query='customer_state='CA'',
sysobject_query=T,
type_to_query='loan_documents'
Affected content when referencing SysObjects or its subtypes

When you execute the method against SysObjects or subtypes of SysObject, the method
acts only on the first primary content page (page 0) of each object, the renditions of the
primary pages, or both. If a SysObject has multiple primary content pages, the primary
pages other than page 0 and their renditions are not affected by the method. (If you
want to move all the content, use a method syntax that references the content objects,
rather than the SysObject.)
You can specify which of these files you want the method to act on by setting the
RENDITIONS argument. The default for RENDITIONS is primary, which means that
the method will only operate on the first primary content files of the SysObjects. If
you set the argument to all, the method moves both the primary content page and its
renditions. If you set the argument to secondary, the method moves only the renditions
but not the primary content.
Controlling the size of the operation

If you are moving a large number of files, you can control the operation using the
MAX_MIGRATE_COUNT and BATCH_SIZE arguments. MAX_MIGRATE_COUNT
controls how many content files are moved with each execution of the method. Use
this argument if you have a large number of files to migrate and want to perform the
migration in smaller steps rather than all in one operation. BATCH_SIZE controls how
many content files are moved in a single transaction within the migration operation (or
how many files per worker session if PARALLEL_DEGREE is greater than 1). Setting
BATCH_SIZE can help protect the operation from overrunning system and database
resource limits during the operation.
If you set MAX_MIGRATE_COUNT, make sure that each execution of the method does
not attempt to move content files that have already been migrated in previous executions
of the method.
MIGRATE_CONTENT
Parallel content migration

In previous releases, the MIGRATE_CONTENT method performed content migration
sequentially, in a single session. Migrating a large number of objects in a production
environment could take a long time. To achieve better performance, an administrator
would execute the method in multiple sessions concurrently (in parallel), with each
session migrating a unique set of objects. This workaround can be challenging to
implement because of the difficulty of identifying individual sets of objects to migrate.
Additionally, this approach may lead to database deadlocks because of database update
collisions caused by multiple sessions attempting to migrate the same object.
The PARALLEL_DEGREE parameter controls how many content migration sessions
are created to do the migration. Using the built‑in parallel migration facility avoids
the difficulties caused by manually implementing concurrent sessions. Use of the
PARALLEL_DEGREE parameter with a value greater than zero requires a Content
Storage Services license.
For any value of the PARALLEL_DEGREE parameter, a master session is created. If the
value of the parameter is 0, the master session does all the migration; the migration is
not done in parallel. For positive values of the parameter, the master session creates
at least that number of worker sessions. The master session validates the method
arguments, finds all the qualified content objects, and assigns individual content objects
for migration to the individual worker sessions. The master session waits until all the
worker sessions have terminated. Then it aggregates the results and statistics, cleans up
worker sessions if necessary, destroys the task queue, and returns.
There are two special cases that will cause problems if migrated by different worker
sessions:
1. Any parent of a migrating content object has more content objects to migrate.
2. The content object has more than one parent and the qualification predicate is
specified against dm_sysobject.
In case 1, the different worker sessions will attempt to migrate the different content
objects. One session will succeed, but the others will fail due to an i_vstamp mismatch.
In case 2, a content object shared by two or more sysobjects may get assigned to multiple
worker sessions. As a result, it is possible for the sessions to migrate the same content
object simultaneously, and thus cause a deadlock or some indefinite behaviors.
To avoid those difficulties, the master session will create a special worker session to
migrate any content that is in a special case. The special session will migrate all of the
special case content objects. If there is a special worker session, there will be total of
PARALLEL_DEGREE + 1 worker sessions. For example, if PARALLEL_DEGREE is 3,
there will be total of 4 worker sessions. These worker sessions are numbered as 0, 1, 2,
and 3. Worker session 0 always acts as the special worker session.
MIGRATE_CONTENT
The special session will always try to acquire tasks from the special task queue. If the
queue is empty, it will try to acquire a task from the regular task queue. In this way, the
special session will share the workload with the other sessions. However, if most of the
migration objects are in one of the special cases, the special session will perform most
of the migration sequentially. If the content to be migrated falls mostly into the special
cases, the migration will be mostly sequential.
The BATCH_SIZE parameter applies to each worker session individually. For example,
if the BATCH_SIZE is 400, each worker session will migrate 400 content objects in a
single transaction.
Removing the original content

When you move content, you can choose whether to remove the content from the current
(source) storage area or not.
If you choose not to remove the content from the current storage area and no other
content objects reference that file, Content Server writes a message to the log file to
identify the content file as an orphaned file that must be removed manually. (The file is
now an orphan because it is no longer referenced by any content objects.)
If you choose to remove the content from the current storage area and the storage area
is a file store storage area, Content Server first checks to ensure that no other content
objects reference that content. If another content object is found that references the
content, the content is not removed. (Multiple content objects may reference one content
file if content duplication checking and prevention is enabled for the file store storage
area. For information about that feature, refer to the Content Server Administration Guide.)
Log file use

You must identify a log file location if you are migrating an entire storage area or
including a DQL predicate or setting REMOVE_ORIGINAL to false in the method
arguments. Specifying a log file location is only optional if you are migrating just a
single object. For all other cases, you must specify a log file location. If the file you
specify already exists, the method appends to that file.
Note: If you are migrating a single content file, you can retrieve messages using a
IDfSession.getMessage method.
The method logs the following messages:
• A success message for each content object successfully migrated without errors.
• A failure message for each content object that was not successfully migrated. The
message includes the reason for the failure.
• Messages for all database errors. (These are written to the server log and the session
log file.)
• A success or failure message for each batch in the operation.
MIGRATE_CONTENT
• Performance metrics about the amount of time spent in the RDBMS and in the
storage area. The information is logged for each object successfully migrated, and
accummulated totals for ever 100 objects, and a summary total for all objects.
Here are samples of the performance messages. The first sample shows the column
headers for entries for individual objects and the information about one object:
Fri Jan 12 10:03:52 2007 953000
[DM_CONTENT_T_MIGRATE_CONTENT_PERF_REC]info: "Total Time (secs)
Total Storage Time (secs) Total Database Time (secs) Storage Time
for current file (secs) Database Time for current file (secs) Total
Objects Current file size Xput (bytes/sec) for current file Max
storage time (secs) Max database time (secs) Max file size Migration
Xput (docs/sec) Storage Xput (bytes/sec) Total KBytes"
Fri Jan 12 10:03:52 2007 953000

[DM_CONTENT_T_MIGRATE_CONTENT_PERF_REC]info: "6.765 6.703 0.062
6.703 0.062 1 8182 1209.46045824095 6.703 0.062
8182 0.147819660014782 1220.64747128152 7"
This sample shows the summarizing entry for 100 objects:

Fri Jan 12 10:05:19 2007 674000
[DM_CONTENT_T_MIGRATE_CONTENT_PERF_FREC]info: "100 Objects Migrated.
256.513 1.289 3974"
Finally, here is a sample of the final summarizing entry:

Fri Jan 12 10:07:02 2007 270000
[DM_CONTENT_T_MIGRATE_CONTENT_PERF_FINAL]info:
"250 Migrated. Storage Time(secs): 547.891, Total Database Time: 3.141,
Total Content Size (KBytes): 9415
None
Examples
This example migrates a single content file, represented by the content object
0600000272ac100d:
EXECUTE migrate_content FOR 0600000272ac100d
WITH target_store='filestore_02'
The next example migrates all the content from filestore_01 to engr_filestore:
WITH source_store='filestore_01',
MIGRATE_CONTENT
target_store='engr_filestore',batch_size=100,
log_file='C:\temp\migration.log'
The final example uses a DQL predicate to select the content to migrate. The query uses
content size to select the content.
WITH target_store='engr_filestore',
query='content_size>1000',max_migrate_count=1000,
batch_size=100,log_file='C:\temp\migration.log'
MIGRATE_TO_LITE
MIGRATE_TO_LITE
Purpose Migrates standard objects to lightweight objects.
Syntax
To generate, and optionally run, a script to split standard objects into a shareable parent
object and a lightweight object:
EXECUTE migrate_to_lite WITH source_type='source_type'
,shared_parent_type='shared_parent_type'
,execution_mode='execution_mode_split'[,recovery_mode=TRUE|FALSE]
,parent_attributes='parent_attributes'
To generate, and optionally run, a script to migrate standard objects to lightweight

objects:
EXECUTE migrate_to_lite WITH
shared_parent_type='shared_parent_type'
[,lightweight_type='lightweight_type']
,execution_mode='execution_mode'[,recovery_mode=TRUE|FALSE]
{,parent_sql_predicate='parent_sql_predicate'}
{,parent_id='ID'}
[,default_parent_id='ID']
Arguments
Table 68. MIGRATE_TO_LITE arguments

source_type string source_type Specifies the name of the
source type which needs
to be split. This type
must be a dm_sysobject
subtype, not the dm_sysobject
itself. After the conversion,
this type will become the
lightweight type whose
shared parent type is specified
in the following parameter,
shared_parent_type.
MIGRATE_TO_LITE

shared_parent_ string shared_parent_ Defines the shareable type to
type type use. If the specified type is
not a shareable type, then it
will be converted to one. The
specified type needs to be a
subtype of dm_sysobject and
cannot be dm_sysobject. If
the specified type is already
a shareable type, then the
lightweight_type parameter
must be specified.
execution_mode string execution_mode_ Specifies the operation to
split perform. The allowable
values for the first form of the
method are:
• Split and Finalize
• Split without Finalize
• Finalize
These values are described in
detail in Execution Mode Split
Values, page 308
execution_mode Specifies the operation to
perform. The allowable
values for the second form of
the method are:
• Generate Script Only
• Run and Finalize
• Run without Finalize
• Cancel
• Finalize
These values are described
in detail in Execution Mode
Values, page 308
MIGRATE_TO_LITE

recovery_mode boolean TRUE|FALSE Use this flag when the
EXECUTION_MODE is
either Run and Finalize or
Run without Finalize. The
default is FALSE. If the flag
is set to TRUE, then the
internally‑created interim
types (and tables) will be
dropped before the process
begins.
parent_attributes string parent_attributes Specifies attributes in the
source type which will be split
into the parent type specified
in shared_parent_type. The
parameter contains a list of
comma‑separated attribute
names from the source
type. The remainder of the
attributes in the source_type
will remain there
lightweight_type string lightweight_type If the specified type is a
standard type, it will be
converted to a lightweight
type. The type needs
to be a direct subtype
of the one specified in
shared_parent_type.
If the specified type is already

a lightweight type, then you
must also set recovery_mode
to TRUE, and specify which
lightweight objects go
with which parents. Use
the parent_sql_predicate,
parent_id, and
default_parent_id arguments
to specify lightweight objects
and parents.
MIGRATE_TO_LITE

parent_sql_ string parent_sql_ This repeating string
predicate predicate parameter specifies an
SQL (not DQL), predicate
qualifying a set of lightweight
SysObjects whose parent
will be set to the following
parameter, parent_id. This
parameter is allowed only
when the execution_mode
is either Run and Finalize or
Finalize.
parent_id ID ID This repeating ID parameter
corresponds to the above
parent_sql_predicate
parameter. The lightweight
SysObjects that match the SQL
predicate will be assigned to
this parent. The specified ID
needs to be a legal ID. This
parameter is allowed only
when the execution_mode
is either Run and Finalize or
Finalize.
default_parent_id ID ID This ID parameter is used for
the remaining lightweight
SysObjects created by this
method that are not qualified
with any predicate specified
in a parent_sql_predicate
parameter. If this parameter
is not specified, then the
i_sharing_parent property of
all the remaining lightweight
SysObjects will be set to
the ID of the lightweight
object itself. That is, they
will be considered as
materialized. This parameter
is allowed only when the
execution_mode is either Run
and Finalize or Finalize.
MIGRATE_TO_LITE
Return Value
MIGRATE_TO_LITE returns an object id for the text file containing the SQL script to do
the migration. The script will be generated regardless of the execution_mode specified.
Execution Mode Split Values
For the first form of the method, execution_mode can take on the following values:
• Split and Finalize—Generates the script and immediately runs it.
• Split without Finalize—Generates the script, but the original types are not changed.
You can then validate the changes before making the changes permanent.
• Finalize—Makes the changes. For this mode, only the source_type,
shared_parent_type, and execution_mode parameters are required.
Execution Mode Values
For the second form of the method, execution_mode can take on the following values:
• Generate Script Only—Generates the script, but does not execute it.
• Run and Finalize—Generates the script and immediately runs it.
• Run without Finalize—Generates the script and immediately runs it, but the
original types are not changed. All the changes will be applied to corresponding
internally‑created types (and tables) with the name dm_lw_id_of_my_parent_type and
dm_lw_id_of_my_child_type created with the changes. You can then validate the
changes before making the changes permanent.
• Cancel—Allows you to remove the interim types and tables created by the Run
without Finalize mode. Typically you would do this if you decided not to finalize the
changes. After removing the interim types and tables, the method ends.
• Finalize—Makes the changes permanent by replacing the original types with the
internal types and dropped the internal types afterwards. If this option is provided
when there is nothing to swap, a warning will be reported back to client and
recorded in server log.
Permissions
You must have Superuser privileges, or be the owner of the involved types, to use this
method. But also see the note for Oracle installation users following the description
section.
MIGRATE_TO_LITE
Description
Use this method to migrate standard types and objects to shareable and lightweight
types and objects. This method can also be used to reparent lightweight objects.
The first form of the command is used to convert a standard type to a lightweight
and a shareable type. In this form of the command, the shareable type is formed by
splitting off attributes from the original standard type. The remaining attributes are used
to create the lightweight type. Specify the name of the standard type to split in the
source_type parameter, the new shareable type in the shared_parent_type parameter,
and list the attributes to split off of the original type in the parent_attributes parameter.
When you use this method to split standard objects, each lightweight object has its own
private parent. In other words, each lightweight object is materialized. You can then
reparent the lightweight objects by using the second form of the command, specifying
parent_sql_predicates and parent_ids to point the lightweight objects to shareable
parents.
The second form of the command does not move attributes from one type to another.
You will use it when all the non‑inherited standard type attributes will remain with the
lightweight type. You can also use this form to reparent lightweight objects.
If you use the second form of the command and do not specify a lightweight type, and
you specify a standard type in the shared_parent_type argument, the standard type is
changed into a shareable type.
The second form can convert standard objects to lightweight objects and parent them
with specified shareable parents. To do this, you specify a shared_parent_type and a
lightweight_type. Conceptually, you can imagine that all the standard objects specified
by the lightweight_type argument are converted to materialized lightweight objects
pointing to private parents of the shared_parent_type. Next, all the objects of the
lightweight type that match the parent_sql_predicate argument are made to point to
the shareable parent with the associated parent_id. The method continues associating
each group of lightweight objects that matches each subsequent parent_sql_predicate
and parenting that group with the associated shareable parent. If any unconverted
materialized lightweight objects remain after converting each parent_sql_predicate
group, the remaining objects are parented with the default_parent_id shareable parent,
if specified. Typically, you would create some shareable parents ahead of time, and
then use this method to associate that list of objects with the groups defined by the
parent_sql_predicate.
To use this method to reparent lightweight objects, specify the shared_parent_type and
the lightweight_type, the parent_sql_predicate to select which objects to reparent and the
parent_id to reparent to. You must also specify recovery_mode as TRUE, or the method
won’t work with already converted objects of lightweight_type.
Note: In order to use this method with an Oracle installation, the user account that
Content Server uses to access the database must have enhanced privileges. The following
MIGRATE_TO_LITE
example assumes that you have logged into SQLPLUS as the SYS user, in SYSDBA mode
to grant these privileges to the repository_1 user:
grant DBA to repository_1;
Examples
This example generates a script to convert usertype_1 to a shareable type. You do not
execute this script against your database. It is created so you can examine the commands
that will be issued when you later execute this method using another form of the method,
either Run and Finalize or Run without Finalize:
EXECUTE migrate_to_lite WITH "shared_parent_type"='usertype_1'
,"execution_mode"='Generate Script Only'
To get the script, you can issue the following DQL statement (assume that the result of
the earlier method returned the object ID 0855706080007c19):
EXECUTE get_file_url FOR '0855706080007c19' WITH "format"='text'
This example converts usertype_2 to a shareable type in one operation:

,"execution_mode"='Run and Finalize'
This example converts usertype_3 to a shareable type in two steps. After step one, you
can examine the script and the temporary types and tables to verify the repository
changes. For step one, use the Run without Finalize execution_mode to run the script
and create the temporary tables:
,"execution_mode"='Run without Finalize'
Then, for step two, use the Finalize execution_mode to swap in the temporary tables
and commit the change:
,"execution_mode"='Finalize'
This example converts an existing standard type, emc_payment_check, and all its objects,
into a lightweight type and a shareable type, emc_payment_bank. Each lightweight
object will have its own private parent object. The parent type will take the attributes
bank_code and routing, but the other attributes will be part of the lightweight type.
In this example, there are already objects created of type emc_payment_check. You can
create the type using the following command:
CREATE TYPE "emc_payment_check" (
account integer,
check_number integer,
transaction_date date,
amount float,
MIGRATE_TO_LITE
bank_code integer,
routing integer
) WITH SUPERTYPE "dm_document" PUBLISH
You can also use the batch example program listed in EMC Documentum High‑Volume
Server Development Guide to create a number of objects for this example.
Use the following command to split the emc_payment_check objects into lightweight
objects of type emc_payment_check, and private parents of type emc_payment_bank.
The bank_code and routing attribute values will be associated with the private parent,
and the other attributes will be associated with the lightweight objects:
EXECUTE migrate_to_lite WITH "source_type"='emc_payment_check'
,"shared_parent_type"='emc_payment_bank'
,"execution_mode"='Split and Finalize'
,"parent_attributes"='bank_code,routing'
The following example takes the materialized lightweight objects converted by the last
example and reparents them. Objects with check_numbers less than five are reparented
to a separately created emc_payment_bank shareable parent, and the remaining
materialized objects are reparented to another separately created shareable parent:
EXECUTE "migrate_to_lite" WITH
"shared_parent_type"='emc_payment_bank',"lightweight_type"='emc_payment_check'
,"execution_mode"='Run and Finalize',"parent_sql_predicate"='check_number<5'
,"parent_id"='0925392d80001d5d'
,"default_parent_id"='0925392d80001d5e'
MODIFY_TRACE
MODIFY_TRACE
Purpose Turns tracing on and off for full‑text index query operations.
Syntax
EXECUTE modify_trace
WITH subsystem='fulltext',value='tracing_level'
Arguments
Table 69. MODIFY_TRACE arguments

SUBSYSTEM S fulltext The keyword fulltext
indicates that you want
to turn on tracing for the
full‑text querying operations.
VALUE S tracing_level The tracing_level must be one
of:
none, to turn off tracing
all, to log both Content

Server and full‑text querying
messages
Return value
MODIFY_TRACE returns a collection with one query result object. The object has one
Permissions
MODIFY_TRACE
Description
MODIFY_TRACE turns tracing on and off for full‑text index operations. When tracing
is on, tracing information for all full‑text queries is logged. The trace information is
placed in the server’s log file.
The tracing information includes informational, verbose, and debug messages. All trace
messages include time stamps and process and thread ID information.
If the method returns FALSE, the level of tracing remains unchanged. For example, if
tracing is currently set at all and you execute MODIFY_TRACE to reset the level to none,
but the method returned FALSE, the trace level remains at the all level.
LOG_OFF, page 280

LOG_ON, page 282
SET_OPTIONS, page 357
Examples
The following example turns on full tracing:

EXECUTE modify_trace
WITH subsystem = 'fulltext',value = 'all'
MOVE_INDEX
MOVE_INDEX
Purpose Moves an existing object type index from one tablespace or segment to another.
(This method is not supported for servers running against DB2.)
Syntax
EXECUTE move_index FOR 'dmi_index_obj_id'

WITH name = 'new_home'
[,global_index=true|false]
Arguments
Table 70. MOVE_INDEX arguments

NAME S new_home Identifies the new tablespace
or segment for the index. Use
the name of the tablespace or
segment.
GLOBAL_INDEX B TRUE or FALSE Indicates whether the index

being created is a global
index. This parameter can
only be used for partitioned
types. The default is FALSE.
Return value
MOVE_INDEX returns a collection with one query result object. The object contains one
Permissions
MOVE_INDEX
Description
MOVE_INDEX moves an existing object type index from one tablespace or segment to
another. You can obtain the index’s object ID from the index’s index object. Refer to the
System Object Reference Manual for a list of the properties defined for the index type.
GLOBAL_INDEX is a boolean parameter that indicates whether the index being moved
is a global index. The default value is FALSE. This parameter can be used only when the
type is a partitioned type, and is only useful if the index is a unique index.
MOVE_INDEX only operates on object type indexes that are represented in the
repository by dmi_index objects.
Note: Those indexes that do not have a dmi_index object (DMI_OBJECT_TPE_UNIQUE
and DM_FED_LOG_INDEX for example) may be moved manually. However, be sure to
shut down Content Server before moving them.

Examples
This example moves the index represented by 1f0000012643124c to the index2 tablespace:
EXECUTE move_index FOR '1f0000012643124c'
WITH name = 'index2'
PING
PING
Purpose Determines if the client still has an active server connection.
Syntax
dmAPIGet("apply,c,NULL,PING[,RETRY_ON_TIMEOUT,B,T|F]")
You cannot use the EXECUTE statement to invoke PING.
Arguments
Table 71. PING arguments

RETRY_ON_ B T (TRUE) or F T (TRUE) forces a connection
TIMEOUT (FALSE) attempt between the client
and the server. The default is
F.
Return value
PING returns a collection with one query result object. The object has one property,
called result, that is TRUE if the connection is alive. If the connection has timed out, a
null collection is returned.
Permissions
Description
None
PING
None
Examples
dmAPIGet("apply,c,NULL,PING,RETRY_ON_TIMEOUT,B,T")
PURGE_AUDIT
PURGE_AUDIT
Purpose Removes an audit trail entry from the repository.
Syntax
EXECUTE purge_audit WITH delete_mode='mode'

[,date_start='start_date',date_end='end_date']
[,id_start='start_id',id_end='end_id']
[,object_id='object_id'][,dql_predicate='predicate']
[,purge_non_archived=T|F][,purge_signed=T|F][,commit_size=value]
Arguments
Table 72. PURGE_AUDIT arguments

DELETE_MODE S mode Defines how the entries to
be deleted are chosen. Valid
values are:
• DATE_RANGE
Deletes all audit trail
entries generated within
a specified date range. If
you include this, include
the DATE_START and
DATE_END arguments.
• ID_RANGE
entries whose object IDs
fall within a specified
range. If you include this,
include the ID_START and
ID_END arguments.
• ALL_VERSIONS
Deletes all audit
trail entries whose
audited_obj_id value
corresponds to a specified
PURGE_AUDIT

object ID. ALL_VERSIONS
is valid only for audit
trail entries whose
audited_obj_id identifies
a SysObject or SysObject
subtype. If you include
ALL_VERSIONS, include
the OBJECT_ID argument.
• SINGLE_VERSION
Deletes all audit
trail entries whose
audited_obj_id value
object ID. If you include
SINGLE_VERSION,
include the OBJECT_ID
argument.
• AUDIT_RECORD
Deletes the audit trail
entry whose object ID
object ID. If you include
AUDIT_RECORD, include
the OBJECT_ID argument.
• PREDICATE
entries that satisfy a DQL
predicate. If you include
PREDICATE, include
the DQL_PREDICATE
argument.
PURGE_AUDIT

DATE_START S start_date The starting date of the
entries to be deleted. The
date is compared to the value
in the time_stamp property
in the audit trail entry.
(time_stamp records the local
time at which the entry was
generated.)
The date format can be

any acceptable format that
does not require a pattern
specification. (Refer to Date
literals, page 15, for a list of
valid formats.
If you include DATE_START,

you must include END_DATE
also.
Include a start and end date

only when DELETE_MODE
is DATE_RANGE.
DATE_END S end_date The ending date of the entries
to be deleted. The date is
compared to the value in the
time_stamp property in the
audit trail entry. (time_stamp
records the local time at which
the entry was generated.)
The date format can be

any acceptable format that
does not require a pattern
specification. (Refer to Date
literals, page 15, for a list of
valid formats.
If you include END_DATE,

you must also START_DATE.
The end date must be greater
than the start date.
PURGE_AUDIT
Include a start and end date

only when DELETE_MODE
is DATE_RANGE.
ID_START S start_id The object ID of an audit trail
entry.
Include ID_START if
the DELETE_MODE is
ID_RANGE. You must also
include ID_END.
ID_END S end_id The object ID of an audit trail
entry.
Include ID_END if
the DELETE_MODE is
ID_RANGE. You must also
include ID_START. The
ID_END object ID must be
larger than the object ID
identified in ID_START
OBJECT_ID S object_id Include this argument
if DELETE_MODE
is ALL_VERSIONS,
SINGLE_VERSION,
SINGLE_ID, or
AUDIT_RECORD.
For all modes except

AUDIT_RECORD, object_id is
the object ID recorded in the
audited_obj_id property of
the audit trail entries.
For AUDIT_RECORD mode,

object_id is the object ID of an
audit trail entry.
PURGE_AUDIT

PURGE_NON_ B T (TRUE) or F Determines whether
ARCHIVED (FALSE) unarchived audit trial entries
are deleted. Setting this
argument to T (TRUE) directs
Content Server to delete
audit trail entries whose
i_is_archived property is set
to F (FALSE).
The default for this argument

is F (FALSE), meaning
that only entries whose
i_is_archived property is set
to T (TRUE) are removed.
You cannot set this to T if the

DQL_PREDICATE argument
is included.
PURGE_SIGNED B T (TRUE) or F Determines whether
(FALSE) audit trail entries for
dm_adddigsignature and
dm_addesignature events are
considered for deletion.
Setting this argument to T

(TRUE) means entries for
dm_addesignature events are
considered for deletion.
The default is F
(FALSE), meaning the
dm_addesignature entries are
not considered for deletion.
You cannot set this to T if the

DQL_PREDICATE argument
is included.
PURGE_AUDIT

DQL_PREDICATE S predicate Defines a DQL predicate
to choose the audit trail
entries to be deleted. A valid
predicate is that portion of
a DQL SELECT statement
that occurs after the FROM
keyword.
If you include this argument,

you may not include
PURGE_NON_ARCHIVED
or PURGE_SIGNED.
COMMIT_SIZE I value Defines how many audit
trail entries to delete in each
transaction within the overall
operation. The default is
1000.
Setting this to 0 means that

all entries are deleted in one
transaction.
Return value
The PURGE_AUDIT method returns a collection with one query result object. The query
result object has two properties, result and deleted_objects. The result property is set to T
if the method completed successfully and F if the method did not complete successfully.
deleted_objects records the number of audit trail entries that were deleted.
Permissions
You must have Purge Audit privileges to execute this method.
Description
Executing the PURGE_AUDIT method always generates at least one audit trail entry
with the event name dm_purgeaudit. The operation generates one audit trail entry for
each transaction within the operation. For example, if you set COMMIT_SIZE to 100 and
PURGE_AUDIT
the operation deletes 700 audit trail entries, the operation generates 7 audit trail entries,
one for each transaction.
The entry for each transaction has the event name dm_purgeaudit. The optional
properties record the following information for the transaction:
• string_1 stores the time_stamp value of the first audit trail entry deleted in the
transaction
• string_2 stores the time_stamp value of the last audit trail entry deleted in the
transaction
• string_3 stores the actual number of audit trail entries deleted by the transaction
• string_5 stores the entire list of arguments from the method’s command line
• id_1 stores the object ID of the first audit trail object deleted in the transaction
• id_2 stores the object ID of the last audit trail object deleted in the transaction
None
Examples
This example deletes all archived audit trail entries generated from January 1, 2003
to January 1, 2004:
EXECUTE purge_audit WITH DELETE_MODE='DATE_RANGE',
date_start='01/01/2003 00:00:00 AM',
date_end='01/01/2004 00:00:00 AM'
This example deletes all audit trail entries generated from January 1, 2003 to January 1,
2004, including unarchived entries. The number of entries deleted in each transaction is
set to 500:
EXECUTE purge_audit WITH delete_mode='DATE_RANGE',
date_start='01/01/2003 00:00:00 AM',
date_end='01/01/2004 00:00:00 AM'
purge_non_archived=T,commit_size=500
This example deletes all archived audit trail entries that identify the document
09000003ac5794ef as the audited object:
EXECUTE purge_audit WITH delete_mode='ALL_VERSIONS',
object_id='09000003ac5794ef'
This example deletes the single audit trail entry whose object ID is 5f0000021372ac6f:
EXECUTE purge_audit WITH delete_mode='AUDIT_RECORD',
object_id='5f0000021372ac6f'
PURGE_AUDIT
This example deletes all audit trail entries whose object IDs range from 5f1e9a8b003a901
to 5f1e9a8b003a925, including unarchived entries:
EXECUTE purge_audit WITH delete_mode='ID_RANGE',
id_start='5f1e9a8b003a901',id_end='5f1e9a8b003a925',
purge_non_archived=T
This example deletes all audit trail entries that satisfy the specified DQL predicate:
EXECUTE purge_audit WITH delete_mode='PREDICATE',
dql_predicate=
'dm_audittrail where event_name like ''dcm%''and
r_gen_source=0'
If you need to include single‑quotes in the predicate string, (for example, ’dcm%’), escape
the single‑quotes with single‑quotes. This is illustrated in the example above.
PURGE_CONTENT
PURGE_CONTENT
Purpose Sets a content file off line and deletes the file from its storage area.
Syntax
EXECUTE purge_content FOR 'content_object_id'
Arguments
PURGE_CONTENT has no arguments.
Return value
PURGE_CONTENT returns a collection with one query result object. The object has
the operation.
Permissions
You must have Sysadmin or Superuser user privileges to use this method.
Description
PURGE_CONTENT marks a content file as off‑line. Additionally, if the file is referenced

by only one content object, it deletes the file from the storage area. If the file is referenced
by other content objects, the file is not deleted. (A file may be referenced by multiple
content objects if the storage area is a file store storage area configured to use content
duplication checking and prevention. For information about that feature, refer to the
Content Server Administration Guide.)
Do not use this method unless you have previously moved the file to an archival or
back up storage area. PURGE_CONTENT does not back up the file. The method only
PURGE_CONTENT
deletes the file from the storage area and sets the is_offline property of the file’s content
object to TRUE.
To use PURGE_CONTENT, you must be using one server for both data and content
request that bypasses the content server to use PURGE_CONTENT in the session.
Examples
This example deletes the content file associated with the content object represented by
060000018745231c and set the is_offline property in the associated content object to TRUE:
EXECUTE purge_content FOR '060000018745231c'
PUSH_CONTENT_ATTRS
PUSH_CONTENT_ATTRS
Purpose Updates content metatdata in a content addressable systems.
Syntax
EXECUTE push_content_attrs FOR object_id

WITH format=format_name [,page=number]
[,page_modifier=value]
object_id is the ID of a document or other SysObject.
Arguments
Table 73. PUSH_CONTENT_ATTRS arguments

FORMAT S name The file format of the content
file. Use the name of the
format object that defines the
format.
PAGE I number The page number of the
content file in the document.
If the content file is a
rendition, this is the page
number of the primary
content with which the
rendition is associated.
The default value is 0.

PAGE_MODIFIER S value This identifies a rendition. It
is the page modifier defined
for the rendition when the
rendition was added to the
document. The value is
stored in the page_modifier
property in the content object.
PUSH_CONTENT_ATTRS
Return value
PUSH_CONTENT_ATTRS returns a collection with one query result object. The object
has one Boolean property that contains TRUE if the method was successful and FALSE if
unsuccessful.
Permissions
To execute this method you must be a superuser and you must have at least Write
permission on the object identified in object_id.
Description
PUSH_CONTENT_ATTRS updates the metadata fields in a content‑addressed storage

system for a particular content file. First, the method reads the values in the following
content‑related properties in the file’s associated content object:
• content_attr_name
• content_attr_value
• content_attr_data_type
• content_attr_num_value
• content_attr_date_value
content_attr_name identifies the metadata fields to be set in the storage system. The
content_attr_data_type property identifies the data type of the value users must provide
for each metadata field in the corresponding index position in content_attr_name. The
actual value is defined in one of the remaining properties, depending on the field’s
datatype. For example, if the field name is “title” and its datatype is character string, the
content_attr_value property contains the actual title value. (The remaining properties,
content_attr_num_value and content_attr_date_value are set to the default NULLINT
and NULLDATE values.)
After the method reads the content object properties, it invokes the content‑addressed
plugin library to update the storage system metadata fields.
Note: To be updated, a field must be defined in both the content object’s
content_attr_name property and in the storage object’s a_content_attr_name property. If
a field is named in the content object’s content_attr_name property but not defined in the
storage object’s a_content_attr_name object, it is not set in the storage area. Similarly, if a
field is named in the storage object’s a_content_attr_name but not in the content object’s
content_attr_name property, it is not set in the storage area.
PUSH_CONTENT_ATTRS
If PUSH_CONTENT_ATTRS completes successfully, it generates a new content address

for the content. The new address is appended to the i_contents property of the
subcontent object that records content addresses for the content file.
For complete information about how to save a document to content‑addressed storage,
refer to Content Server Fundamentals.
SET_CONTENT_ATTRS, page 352
Examples
EXECUTE push_content_attrs FOR 090000026158a4fc

WITH format=txt,page=1
RECOVER_AUTO_TASKS
RECOVER_AUTO_TASKS
Purpose Recovers work items that have been claimed, but not yet processed, by a workflow
agent associated with a failed Content Server.
Syntax
EXECUTE recover_auto_tasks
WITH server_config_name=name
Arguments
Table 74. RECOVER_AUTO_TASKS arguments

SERVER_CONFIG_ I name of the Use the name of the server
NAME server config config object representing the
object Content Server that crashed
or failed.
Return value
The method returns T (TRUE) if it completes successfully and F (FALSE) if not.
Permissions
This method must be executed by a user with Sysadmin or Superuser privileges.
Description
If a Content Server fails, its workflow agent is stopped also. When the server is restarted,
the workflow agent will recognize and process any work items it had claimed but not
processed before the failure. However, if you cannot restart the Content Server, you
RECOVER_AUTO_TASKS
must recover those work items already claimed by its associated workflow agent so
that another workflow agent can process them. RECOVER_AUTO_TASKS performs
that recovery.
Running RECOVER_AUTO_TASKS executes a query to update all work items claimed
but unprocessed by the failed server’s workflow agent. The query resets the a_wq_name
property in the work items to empty. This allows other workflow agents running against
the repository to claim those work items for processing.
Before executing this method, make sure that the specified Content Server is not running.
None
Examples
EXECUTE recover_auto_tasks
WITH server_config_name='DevRepository_1'
REGISTER_ASSET
REGISTER_ASSET
Purpose Queues a request to the Media Server to generate a thumbnail, proxies, and
metadata for a rich media content file.
Syntax
EXECUTE register_asset FOR object_id

WITH [page=page_number][,priority=priority_level]
Arguments
Table 75. REGISTER_ASSET arguments

PAGE I page_number Page number of the content
file. If unspecified, the default
is 0.
PRIORITY I priority_level Identifies the priority of
the request. A value of
zero indicates no priority.
Priority rises as the value
rises. The Media Server
processes higher priority
requests before lower priority
requests.
If unspecified, the default is 5.
Return value
REGISTER_ASSET returns a collection with one query result object. The object has
properties, result and result_id. The result property is a Boolean property whose value
indicates success (TRUE) or failure (FALSE) of the operation. The result_id property
records the object ID of the newly created queue item object.
REGISTER_ASSET
Permissions
You must have at least Version permission on the object or Sysadmin privileges to use
this method.
Description
REGISTER_ASSET is called by Content Server whenever an object with rich media

content is saved or checked in to the repository. The method generates an event,
dm_register_event, that is queued to the Media Server. When the Media Server processes
the event, the server creates a thumbnail, proxies, and metadata for the content.
The dmi_queue_item that represents the event is queued to the dm_mediaserver user,
who represents the Media Server. (dm_mediaserver is created when Documentum
Media Transformation Services is installed.) REGISTER_ASSET sets the following
properties in the queue item:
Table 76. Queue item property values set by REGISTER_ASSET
Property Set to
event dm_register_event
item_id object ID of the SysObject that triggered the request
instruction_page page number of the content in the SysObject
date_sent date the request was made
name dm_mediaserver
sent_by session user
priority priority level identified in the REGISTER_ASSET call
SET_CONTENT_ATTRS, page 352

TRANSCODE_CONTENT, page 365
Example
EXECUTE register_asset FOR 090002410063ec21

WITH page=0,priority=8
REINDEX_PARTITIONABLE_TYPE
Purpose Reindex a partitionable type to increase performance.
Syntax
EXECUTE reindex_partitionable_type [WITH type_name='type_name']
Arguments
Table 77. REGISTER_ASSET arguments

type_name S type_name Type to reindex.
Return value
The method returns T (TRUE) if it completes successfully and F (FALSE) if not
Permissions
This method must be executed by a user with Sysadmin or Superuser privileges.
Description
REINDEX_PARTITIONABLE_TYPE is used for databases upgraded from release 6.0

or 6.0 SP1 to 6.5. In 6.0, indexes for types that have the i_partition attribute included
a column for that property in indexes that included r_object_id. This can cause a
performance problem for non‑partitioned repositories. In 6.5 databases, these indexes
do not include the i_partition value unless the repository is partitioned. Only use this
method for repositories upgraded to 6.5 that are showing performance issues.
You can reindex all the partitionable types, or any specific partitionable type.
None.
Example
EXECUTE reindex_partitionable_type WITH "type_name"='my_type'
REORGANIZE_TABLE
REORGANIZE_TABLE
Purpose Reorganizes a database table for query performance.
Syntax
EXECUTE reorganize_table WITH table_name='name',

[,index='index_name']
Arguments
Table 78. REORGANZE_TABLE arguments

TABLE_NAME S name Name of the RDBMS table to
be reorganized.
INDEX S index_name Name of an index on the table
identified in TABLE_NAME.
This argument is required for

an Oracle database table. It
is optional for a SQL Server
or DB2 database table. It is
not used for Sybase database
table.
With the exception of Sybase,

which doesn’t use this
argument, the argument
is used differently on each
database. Refer to the General
Notes for details.
REORGANIZE_TABLE
Return value
REORGANIZE_TABLE returns a collection with one query result object. The object has
one property, named result, that contains T if the method was successful or F if the
method was unsuccessful.
Permissions
You must be a superuser to execute this method.
Caution: Do not use this method unless directed to do so by Technical Support.
Description
This method is used by the UpdateStatistics administration tool, in conjunction with

UDPATE_STATISTICS, when the tool is run on a DB2 database. However, the method
can be used on any supported database.
The INDEX argument

On Oracle, you must include the INDEX argument. The method rebuilds the specified
index. The index must be an index on the table identified in TABLE_NAME.
For SQL Server, the argument is optional. If you include it, you must specify an index on
the table identified in TABLE_NAME. The method rebuilds that index. If you do not
include the argument, the method rebuilds all indexes on the specified database table.
For DB2, the argument is optional. If you include it, you must specify an index on the
table identified in TABLE_NAME. The method rebuilds the database table based on the
ordering defined in the index.
Caution: Using the INDEX argument on a DB2 database table is a powerful

feature. The choice of index to use as a basis for re‑ordering the table can greatly
affect query performance against that table— for better or worse, depending on
the index choice. It is recommended that if you use this argument, specify the
index on the r_object_id property.
Note: Indexes created by Content Server are named using the following format:
D_index_obj_id, where index_obj_id is the object ID of the dmi_index object for the index.
The INDEX argument is not used when the method is run against a Sybase table.
REORGANIZE_TABLE
UPDATE_STATISTICS, page 369
Examples
This example reorganizes the dm_sysobject_s table. (Note that these two examples do
not work on Oracle because the required INDEX argument is not included.)
EXECUTE reorganize_table
WITH table_name='dm_sysobject_s'
This example rebuilds an index associated with the dm_sysobject_s table.

EXECUTE reorganize_table
WITH table_name='dm_sysobject_s,
index='D_1f0C9fda80000108'
REPLICATE
REPLICATE
Purpose Copies content files in distributed storage areas.
Syntax
EXECUTE replicate
WITH query='value',store='value'
[,type='value']
Arguments
Table 79. REPLICATE arguments

QUERY S dql_predicate This argument is required.
expression The predicate expression
is used to build a DQL
query that selects the objects
whose content you want to
copy. The expression can be
any expression that would
be a valid WHERE clause
qualification (refer to The
WHERE clause, page 161).
STORE S name This argument is required.
It identifies where to put
the new content copy or
copies. The name must be
the name of a component of a
distributed storage area.
TYPE S type_name This argument is optional.
It identifies the type of
objects whose content you are
replicating. type_name must
be a direct or indirect subtype
of dm_sysobject.
REPLICATE
The default is dm_sysobject.
Return value
REPLICATE returns a collection with one query result object. The object has one Boolean
Permissions
You must have Sysadmin or Superuser privileges to use REPLICATE.
Description
REPLICATE copies content files from one component of a distributed storage area to
another. Typically, replication of content files is performed by the ContentReplication or
surrogate get. Use REPLICATE as a manual backup for these tools. (Refer to the Content
Server Administration Guide for information about the ContentReplication and to the
Distributed Configuration Guide for information about surrogate get.)
REPLICATE checks the contents stored in the storage area at a specified site and copies
back to the local storage area any contents that meet the conditions defined in the
function. (Refer to the Distributed Configuration Guide for more information.)
To use REPLICATE, you must be using one server for both data and content requests. If
the configuration is set up for content servers, you must issue a connection request that
bypasses the content server to use REPLICATE in the session.
DELETE_REPLICA , page 214

IMPORT_REPLICA, page 262
REPLICATE
Examples
This example replicates all content for documents of the subtype proposals owned by
jennyk:
EXECUTE replicate WITH query='owner_name=jennyk',
store='distcomp_1',type='proposals'
The next example replicates the content of all objects whose content is authored by Jane:
EXECUTE replicate WITH query='any authors in (''Jane'')',
store='diststorage3'
RESET_TICKET_KEY
RESET_TICKET_KEY
Purpose Generates a login ticket key and stores it in the repository.
Syntax
EXECUTE reset_ticket_key
Arguments
None
Return value
The method returns a collection with one query result object. The object has one
property, result, that contains T (TRUE) if the method was successful or F (FALSE) if the
Permissions
Description
Use this method when you need to replace a login ticket key in a repository with a new
key. Any login tickets generated by the repository before the LTK was reset cannot
be used within the repository.
You must restart Content Server after resetting the login ticket key.
RESET_TICKET_KEY
EXPORT_TICKET_KEY, page 234

IMPORT_TICKET_KEY, page 264
IDfSession.resetTicketKey()
Examples
EXECUTE reset_ticket_key
RESTORE_CONTENT
RESTORE_CONTENT
Purpose Restores an off‑line content file to its original storage area.
Syntax
EXECUTE restore_content FOR 'content_object_id'

WITH file = 'path_name' [,other file = 'other_path_name']
content_obj_id is the object ID of the content object associated with the specified file.
Arguments
Table 80. RESTORE_CONTENT arguments

FILE S file_path Specifies the current location
of the content file. Use a full
path specification.
OTHER_FILE S other_path_name Specifies the current location
of the resource fork for the
content file. Use a full path
specification. Include this
argument only if the file is a
Macintosh file.
Return value
RESTORE_CONTENT returns a collection with one query result object. The object has
the operation.
Permissions
You must have Sysadmin or Superuser user privileges to use this method.
RESTORE_CONTENT
General notes
RESTORE_CONTENT restores an off‑line content file to its original storage area.

This method only operates on one file at a time. To restore multiple files, use an
IDfSession.restore method.
The method places the file in the storage area indicated by the storage_id property of the
file’s content object and sets the content object’s is_offline property to FALSE.
To use RESTORE_CONTENT, you must be using one server for both data and content
request that bypasses the content server to use RESTORE_CONTENT in the session.
Examples
The following examples restore the file named Myproposal using an EXECUTE
statement:
EXECUTE restore_content
WITH file='c:\archive1\Myproposal'
or, on UNIX:
EXECUTE restore_content
WITH file='u02/archive1/Myproposal'
ROLES_FOR_USER
ROLES_FOR_USER
Purpose Retrieves the roles assigned to the user in a particular client domain.
Syntax
EXECUTE roles_for_user [[FOR] 'dm_user_id']

WITH [USER_NAME=value][,DOMAIN=domain_name]
Arguments
Table 81. ROLES_FOR_USER arguments

USER_NAME S user_name User whose roles you are
retrieving. Identify the user
by the user’s user name.
DOMAIN S domain_name Domain of a client
application.
If a domain is included, the

method returns the user’s
roles within the specified
domain.
If a domain is not included,

the method returns all roles
for the user, regardless of
domain.
Return value
This returns a collection of one query result object that has three properties: user_name,
domain, and roles. user_name contains the name of the user being queried. domain
ROLES_FOR_USER
lists the domains searched for user roles. roles is a repeating property that contains the
roles for the user.
Permissions
Any one can use this method.
General notes
This method is used by client applications to determine the roles assigned to users who
use the applications. For example, when a user starts a session with Desktop Client,
DTC executes this method to query the domain group associated with Desktop Client,
to determine what roles the user has in Desktop Client.
(For more information about groups, roles, and domains, refer to Content Server
Fundamentals.)
None
Examples
EXECUTE roles_for_user
WITH user_name=MaryJean,domain="HR_app"
SET_APIDEADLOCK
SET_APIDEADLOCK
Purpose Sets a deadlock trigger on a particular operation.
Syntax
EXECUTE set_apideadlock
WITH API=api_name,VALUE=T|F{,API=operation_name,VALUE=T|F}
Arguments
Table 82. SET_APIDEADLOCK arguments

API S api_name Name of the operation on
which to set the deadlock
trigger.Table 83, page 350 lists
the operations on which you
can set a trigger.
VALUE BOOLEAN T (TRUE) or F TRUE sets the trigger. FALSE
(FALSE) removes the trigger.
Return value
SET_APIDEADLOCK returns a collection with one query result object. The object has
the operation.
Permissions
Anyone can use this administration method.
SET_APIDEADLOCK
General notes
Use SET_APIDEADLOCK to test deadlock retry code in client applications that execute
in explicit transactions. Operations that occur in explicit transactions are not protected by
Content Server’s internal deadlock retry functionality. Consequently, applications that
execute in an explicit transaction may include their own deadlock retry functionality.
To test the deadlock retry functionality, use SET_APIDEADLOCK to place a trigger on
one or more methods or operations executed in the application. When the application
is tested, Content Server simulates a deadlock when one of the methods or operations
executes, allowing you to test the deadlock retry code in the application. The simulated
deadlock sets the _isdeadlocked computed property and issues a rollback to the database.
The deadlock trigger is removed automatically from the method or operation which
triggered the simulated deadlock.
Table 83, page 350, lists the operations and methods on which you can place a deadlock
trigger.
Table 83. Valid operation names for SET_APIDEADLOCK
Operation Representing
acquire Acquisition of a work item
bp_transition Completion of the bp_transition method
branch Branching of a version tree
checkin A checkin operation
complete Completion of a work item
demote Demotion of an object
dequeue Dequeuing an object
destroy Destruction of an object

exec Any RPC EXEC call (on behalf of a Query,
Readquery, Execquery, or Cachequery
operation)
next A next method
promote Promotion of an object
queue A queue method
resume Resumption of an object
revert A revert method
SET_APIDEADLOCK
Operation Representing
save Save on any object
Use this operation to put a deadlock trigger on

a Saveasnew method for a SysObject.
save_content A content save operation during a save,
checkin, saveasnew, or branch operation
save_parts A containment save operation during a save,
checkin, saveasnew, or branch operation
suspend Suspension of an object
None
Examples
This example sets a deadlock trigger on the Checkin method:

WITH api='checkin',value=T
This example sets a deadlock trigger on the Promote and Revert methods:
WITH api='promote',value=T,
api='revert',value=T
This example removes the deadlock trigger from the Checkin method:
WITH api='checkin',value=F
SET_CONTENT_ATTRS
SET_CONTENT_ATTRS
Purpose Sets the content‑related properties of a content object.
Syntax
EXECUTE set_content_attrs FOR object_id

WITH format='format_name',[page=page_number,]
[page_modifier='value',]
parameters='name="value"{,name="value"}'[,truncate=T|F]
Arguments
Table 84. SET_CONTENT_ATTRS arguments

FORMAT S format_name Name of the content format.
This is the name of the format
object.
PAGE I page_number Page number of the content in
the document’s set of content
files. If unspecified, the
default is 0.
PAGE_ MODIFIER S value Identifies the rendition. Refer
to the General Notes for a
detailed description of the
purpose of the page modifier.
SET_CONTENT_ATTRS

PARAMETERS S name = value Comma separated list of
pairs property names and values.
value is one of:
ʺcharacter_stringʺ
FLOAT(number)
DATE(date_value)
Refer to the General Notes for

examples.
TRUNCATE B T (TRUE) or F Whether to remove existing
(FALSE) values in the content
properties before setting
the new values. The default
value is F.
Return value
SET_CONTENT_ATTRS returns a collection with one query result object. The object has
the operation.
Permissions
You must have at least Write permission on the object or Sysadmin privileges to use this
method.
General notes
SET_CONTENT_ATTRS sets five properties of a content object:

• content_attr_name
• content_attr_value
• content_attr_num_value
• content_attr_date_value
• content_attr_data_type
SET_CONTENT_ATTRS
The Media Server uses this method to store the metadata it generates for a content file in
the file’s content object.
Using the PARAMETERS argument

The metadata is specified in SET_CONTENT_ATTRS as a comma‑separated list of name
and value pairs in the PARAMETERS argument. The format is:
'name=value{,name=value}'
Because the PARAMETERS argument is a string argument, enclose the full string in
single quotes. Additionally, if value is a character string, enclose the individual value
in double quotes. For example:
EXECUTE set_content_attrs FOR 0900038000ab4d13
WITH format='jpeg',page=0,
PARAMETERS='name="photo_closeup"'
If the metadata value is a numeric value, use the FLOAT function to specify the value:
PARAMETERS='width=FLOAT(12.5)'
If the metadata value is a date, use the DATE function to specify the value:
PARAMETERS='take_down_date=DATE(09/30/2002)'
The method sets the content object properties with values specified in the PARAMETERS
argument beginning at the zero index position. The values are set in the order in which
they are included in the PARAMETERS argument.
The content_attr_name and content_attr_data_type values are set to the name of the
property and its datatype. If the property’s datatype is string, the value is stored
in content_attr_value and the remaining two properties (content_attr_date_value
and content_attr_num_value) are set to the default NULL values (NULLDATE
and NULLINT). If the property’s datatype is numeric, the value is stored in
content_attr_num_value and the remaining two properties (content_attr_value
and content_attr_date_value) are set to the default NULL values (NULLSTRING
and NULLDATE). If the property’s datatype is date, the value is stored in
content_attr_date_value and the remaining two properties (content_attr_num_value and
content_attr_value) are set to the default NULL values (NULLINT and NULLSTRING).
For example, suppose an application executes the following statement:
PARAMETERS='name="photo_closeup",width=FLOAT(12.5),take_down_date=DATE(09/30/2002)'
Table 85, page 355, shows the resulting values in the properties in the content object.
SET_CONTENT_ATTRS
Table 85. Example settings for content metadata properties in content objects
Property Index position

[0] [1] [2]
content_attr_name name width take_down_date
content_attr_data_ 2 4 5
type
content_attr_value photo_closeup NULLSTRING NULLSTRING
content_attr_num_ NULLINT 12.5 NULLINT
value
content_attr_date_ NULLDATE NULLDATE 09/30/2002
value
The TRUNCATE argument controls how existing values in the content properties are
handled. If TRUNCATE is set to T (TRUE), existing values in the properties are removed
before the properties are set to the new names and values. If TRUNCATE is F (FALSE),
existing names and values are not removed. If the PARAMETERS argument includes
a name that already present in the properties, the name’s value is overwritten. Names
specified in the PARAMETERS argument that are not currently present in the properties
are appended to the properties. The default for TRUNCATE is F.
Using PAGE_MODIFIER
Use the PAGE_MODIFIER argument to define an identifier that distinguishes a rendition
from any other rendition in the same format associated with a particular content page.
There are no constraints on the number of renditions that you can create for a document.
Additionally, you can create multiple renditions in the same format for a particular
document. To allow users or applications to distinguish between multiple renditions in
the same format for a particular document, define a page modifier.
Including the PAGE_MODIFIER argument in SET_CONTENT_ATTRS sets the
page_modifier property of the content object. This property, along with three others
(parent_id, page, i_format) uniquely identifies a rendition. Applications that query
renditions can use the modifier to ensure that they return the correct renditions.
PUSH_CONTENT_ATTRS, page 328
SET_CONTENT_ATTRS
Examples
EXECUTE set_content_attrs FOR 090002134529cb2e

parameters='name="garage_band",sales=FLOAT(100.2),
release_date=DATE(01/02/2002)'
SET_OPTIONS
SET_OPTIONS
Purpose Turns tracing options off or on.
Syntax
EXECUTE set_options
WITH option='option_name',"value"=true|false
Arguments
Table 86. SET_OPTIONS arguments

OPTION S option_name Identifies the tracing option
you want to turn on or off.
Refer to Table 87, page 358
VALUE B T (TRUE) or F TRUE turns tracing on.
(FALSE) FALSE turns tracing off.
Return value
SET_OPTIONS returns a collection with on result object. The object has one Boolean
Permissions
General notes
The tracing results for the options representing server operations are printed to the
server log file. The trace_method_server option traces method server operations. The
SET_OPTIONS
tracing results generated by setting trace_method_server are printed to the method

server log file.
To turn off the nettrace option, disconnect all client sessions. After about one minute,
the tracing turns off.
Table 87, page 358, lists the values for the OPTION argument:
Table 87. Trace options for SET_OPTIONS
Value for the OPTION Meaning

argument
ca_store_trace Enables tracing for operations in a content‑addressed
storage system. The trace messages, up to 2047
characters, are placed in the server log file.
Tracing content‑addressed storage operations is only

recommended when needed to troubleshoot the
system.
clean Removes the files from the server common area.
debug Traces session shutdown, change check, launch and
fork information
docbroker_trace Traces connection broker information
file_store_trace Traces digital shredding of content files. Also
traces content checking and duplication prevention
operations.
i18n_trace Traces client session locale and code page.
An entry is logged identifying the session locale

and client code page whenever a session is started.
An entry is also logged if the locale or code page is
changed during the session.
last_sql_trace Traces the SQL translation of the last DQL statement
issued before access violation and exception errors.
If an error occurs, the last_sql_trace option causes the

server to log the last SQL statement that was issued
prior to the error. This tracing option is enabled by
default.
It is strongly recommended that you do not turn

off this option. It provides valuable information to
Technical Support if it ever necessary to contact them.
SET_OPTIONS
Value for the OPTION Meaning

argument
lock_trace Traces Windows locking information
net_ip_addr Traces the IP addresses of client and server for
authentication
nettrace Turns on RPC tracing. Traces Netwise calls,
connection ID, client host address, and client host
name
retention_trace Turns on tracing for the following retention‑related
operations:
• Assigning a retention policy to a document
• Recording a retention period applied by a retention
policy at the storage area level
• Removing a retention policy from a document
rpctrace Traces RPC calls.
sqltrace Traces SQL commands sent to the underlying RDBMS
for subsequent sessions, including the repository
session ID and the database connection ID for each
SQL statement.
ticket_trace Traces import and export operations for the login
ticket key and operations the use a single‑use login
ticket.
trace_authentication Traces detailed authentication information
trace_complete_launch Traces Unix process launch information
trace_method_server Traces the operations of the method server.
trace_workflow_agent Traces operations of the workflow agent. Messages
are recorded in the server log file.
LOG_OFF, page 280

LOG_ON, page 282
MODIFY_TRACE, page 312
SET_OPTIONS
Examples
This example turns on SQL tracing:

EXECUTE set_options
WITH option='sqltrace',"value"=true
The following example turns on logon authentication tracing:

EXECUTE set_options
WITH option='trace_authentication',
"value"=true
This example turns off tracing for logon authentication:

EXECUTE set_options
WITH option='trace_authentication",
"value"=false
SET_STORAGE_STATE
SET_STORAGE_STATE
Purpose Takes a storage area offline, places an off‑line storage area back online, or makes a
storage area read‑only.
Syntax
EXECUTE set_storage_state [[FOR] 'storage_area_obj_id']

[WITH store=storage_area_name{,argument=value}]
If you include the STORE argument, do not include the FOR clause.
Arguments
Table 88. SET_STORAGE_STATE arguments

OFFLINE B T (TRUE) or F If set to TRUE, the storage
(FALSE) area is taken off‑line.
READONLY B T (TRUE) or F If set to TRUE, the storage
(FALSE) area is read‑only.
STORE S storage_area_ Identifies the storage area
name whose state you are changing.
Use the name of the area’s
storage area object.
Return value
SET_STORAGE_STATE returns a collection with one result object. The object has one
Boolean property whose value indicates the success (TRUE) or failure (FALSE) of the
operation.
Permissions
SET_STORAGE_STATE
General notes
A storage area has three possible states:

• Online
Users can read from and write to an online storage area.
• Offline
Users can neither read from nor write to an offline storage area.
• Readonly
Users can only read from a readonly storage area. Users cannot write to a readonly
storeage area.
To set a storage area’s state to offline, issue SET_STORAGE_STATE with the OFFLINE
argument set to T (TRUE); for example:
EXECUTE set_storage_state WITH store=filestore_33,OFFLINE=true
To set a storage area’s state to readonly, issue SET_STORAGE_STATE with the

READONLY argument set to T (TRUE); for example:
EXECUTE set_storage_state WITH store=filestore_33,READONLY=true
To change either an offline or readonly storage area back to the online state (users can
read and write the storage area), issue the SET_STORAGE_STATE method without
specifying a state argument; for example:
EXECUTE set_storage_state WITH store=filestore_33
Setting either OFFLINE or READONLY to FALSE directly has no effect.

To use SET_STORAGE_STATE, you must be using one server for both data and content
request that bypasses the content server to use SET_STORAGE_STATE in the session.
None
Example
The following example moves the storage area called manfred offline:
EXECUTE set_storage_state
WITH store = 'manfred', offline = T
SHOW_SESSIONS
SHOW_SESSIONS
Purpose Lists information about all the currently active sessions and a user‑specified
number of historical sessions.
Syntax
EXECUTE show_sessions
Arguments
SHOW_SESSIONS has no arguments.
Return value
SHOW_SESSIONS returns a collection. Each query result object in the collection

represents one currently active repository session. The properties of the objects contain
information about the sessions. The properties returned by SHOW_SESSIONS are the
same as those for LIST_SESSIONS when LIST_SESSIONS is run to return a full set of
properties. For a description of the properties, refer to Table 61, page 273.
Permissions
General notes
SHOW_SESSIONS does not return information about historical (timed out) sessions.
It only returns information about currently active sessions. The information for each
session is identical to the information returned by LIST_SESSIONS for active sessions if
that method is run with the BRIEF_INFO argument set to FALSE.
Note: You can use SHOW_SESSIONS to obtain the process ID if you need to shutdown
or kill a session or server.
SHOW_SESSIONS
Examples
Refer to the syntax description for examples.
TRANSCODE_CONTENT
TRANSCODE_CONTENT
Purpose Queues a transformation request for a content file to the Media Server.
Syntax
EXECUTE transcode_content FOR 'object_id'

WITH [page=page_number,] [priority=priority_level,]
message='message',source_format='format_name',
target_format='format_name'
Arguments
Table 89. TRANSCODE_CONTENT arguments

PAGE I page_number Page number of the content
file. If unspecified, the default
is 0.
PRIORITY I priority_level Identifies the priority of
the request. A value of
zero indicates no priority.
Priority rises as the value
rises. The Media Server
processes higher priority
requests before lower priority
requests.
If unspecified, the default is 5.
TRANSCODE_CONTENT

MESSAGE S ’‑profile_id= Identifies the profile that
“object_id”’ contains the definition of
the transformation to be
performed on the content.
The profile is identified by its
object ID. You must enclose
the object ID in double quotes,
and the entire value in single
quotes. Refer to the usage
notes for an example.

a more detailed description.
TARGET_FORMAT S format_name Identifies the format to which
to transform the content. Use
the name of the format as it is
defined in the format’s format
object.
SOURCE_ S format_name Identifies the content file’s
FORMAT starting format. Use the name
of the format as it is defined
in the format’s format object.
Return value
TRANSCODE_CONTENT returns a collection with one query result object. The object
has two properties, result and result_id. The result property is a Boolean property whose
value indicates the success (TRUE) or failure (FALSE) of the operation. The result_id
property records the object ID of the queue item that is created as by the method.
Permissions
You must have at least Write permission on the object or Sysadmin privileges to use this
method.
TRANSCODE_CONTENT
General notes
TRANSCODE_CONTENT is issued by WebPublisher™ to request a transformation

operation on a content file by the Media Server. The method generates an event,
dm_transcode_content, that is queued to the Media Server. When the Media Server
processes the event, the server performs the transformation on the content as defined
in the specified profile.
The dm_queue_item that represents the event is queued to the dm_mediaserver user,
who represents the Media Server. (dm_mediaserver is created when Documentum
Media Transformation Services is installed.) TRANSCODE_CONTENT sets the
following properties in the queue item:
Table 90. Queue item properties set by TRANSCODE_CONTENT
Property Set to
event dm_transcode_content
item_id object ID of the SysObject that triggered the request
instruction_page page number of the content in the SysObject
content_type starting format of the SysObject
message value specified in the MESSAGE argument
item_type format to which to transform the content
date_sent date the request was made
name dm_mediaserver
sent_by session user
priority priority level identified in the REGISTER_ASSET call
The MESSAGE argument specifies the transformation operation to perform by

specifying a profile. A profile is an XML document, stored in the repository, that defines
transformation operations. The value for a MESSAGE argument has the following
format:
'profile_id="object_id"'
object_id is the object ID of the profile document.

For example, suppose that 090000132400c2e198 is the object ID of a document that you
want to transform and that 09000013240053ae1b is the object ID of a profile containing
the definition of the desired transformation. The following DQL EXECUTE statement
generates a request to the Media Server to perform the transformation:
EXECUTE transcode_content FOR '090000132400c2e198'
WITH page=0,message='profile_id="09000013240053ae1b"',
source_format='jpeg',target_format='gif'
TRANSCODE_CONTENT
REGISTER_ASSET, page 333
Example
EXECUTE transcode_content FOR '090000017456ae1c'

WITH page=0,priority=5,
message='profile_id="090000018125ec2b"',
source_format='jpeg',
target_format='jpeg_lres'
UPDATE_STATISTICS
UPDATE_STATISTICS
Purpose Updates statistics for RDBMS tables in the repository.
Syntax
EXECUTE update_statistics WITH table_name='name'

[,count=integer][,extra_data=value]
Arguments
Table 91. UPDATE_STATISTICS arguments

TABLE_NAME S name Name of the database table
whose statistics you want to
update.
COUNT I integer This argument is available
only if the database is Oracle,
SQL Server, or Sybase. It is
not available on DB2.
The argument is used

differently for each database.
details.
EXTRA_DATA S value The argument is used
differently for each database.
details.
Return value
UPDATE_STATISTICS returns a collection with one query result object. The object has
one property, called result, that contains T if the method was successful or F if the
UPDATE_STATISTICS
Permissions
You must be a Superuser to execute this method.
Caution: Do not use this method unless directed to do so by Technical Support.
General notes
UPDATE_STATISTICS is used by the UpdateStatistics administration tool when the tool

is run on a DB2 database. However, the method can be used on any supported database.
The COUNT argument

This is an optional argument. It is used differently in Oracle, SQL Server, and Sybase. It
is not used if the database is a DB2 database.
For Oracle, it defines the number of buckets to use when calculating the histogram
statistics. The valid range for COUNT on an Oracle database is 1 to 254. The default is
75. Setting COUNT to 0 deletes all histogram statistics for the table.
For SQL Server, this argument defines what percentage of table rows to use when
calculating the statistics. For example, if you set this to 50, the method uses one half
(50%) of the table rows to calculate the statistics. The default is 100, meaning all rows are
used to calculate the statistics.
For Sybase, this argument defines how many steps to use when calculating the statistics.
The default is 20.
The EXTRA_DATA argument

The EXTRA_DATA argument is an optional argument. Its use differs depending on
the database.
For Oracle and Sybase, this identifies a specific set of table columns to be analyzed
for statistics. The columns must exist in the table. The columns are specified as a
comma‑separated list of column names. Enclose the entire list in single quotes. For
example:
EXECUTE update_statistics
WITH table_name='dm_sysobject_s',
extra_data='keywords,authors'
If you do not include EXTRA_DATA, all columns in the table are used.
Including this argument for Sybase databases can be expensive because the RDBMS must
scan the table and perform a sort operation on the table.
UPDATE_STATISTICS
For SQL Server and DB2, the argument identifies an index for which you want to
generate statistics. The index must be an index on the table identified in TABLE_NAME.
If you do not include the argument, the database table identified in TABLE_NAME and
all of its indexes are analyzed.
REORGANIZE_TABLE, page 337
Examples
This example updates statistics for the dm_sysobject_s table:

WITH table_name='dm_sysobject_s'
This example updates the statistics for the dm_user_s table, specifying that only the
user_name, user_os_name and user_address columns be used for the analysis:
WITH table_name='dm_user_s',
extra_data='user_name,user_os_name,user_address'
WEBCACHE_PUBLISH
WEBCACHE_PUBLISH
Purpose Invokes the dm_webcache_publish method to publish documents to a Web site.

(This administration method cannot be run using the EXECUTE statement.)
Syntax
apply,session,webc_config_obj_id,
WEBCACHE_PUBLISH[,ARGUMENTS,S,argument_list]"
Arguments
Table 92. WEBCACHE_PUBLISH arguments

ARGUMENTS S argument _list Identifies the arguments
that you want to pass to
the dm_webcache_publish
method. The valid entries for
argument_list are described
in Table 93, page 372.
Table 93, page 372, lists the valid entries for the ARGUMENTS argument.
Table 93. Valid arguments for ARGUMENTS
Argument Value Description

‑source_object_id object_id Identifies the object
or source folder to be
refreshed. If this identifies
an object, the object
must reside under the
source folder identified
in the webc config object
specified in the command
line. If this identifies a
folder, the folder must be
the source folder or reside
under the source folder.
WEBCACHE_PUBLISH
If you specify a folder, all

objects in and underneath
the folder are refreshed.
If you don’t include this

argument, the entire source
data set is refreshed.
This option is ignored if

‑full_refresh is set to TRUE.
‑full_refresh TRUE or FALSE When this is set to
TRUE, the content and
property data at the target
WebCache are deleted and
republished.
You must have Superuser

privileges to set this option
to TRUE. The default is
FALSE.
‑force_refresh TRUE or FALSE When this is set to TRUE,
documents are refreshed
even if their modification
dates do not indicate a
need for a refresh.
The default for this option

is FALSE.
‑method_trace_level trace_level Turns on tracing for the
method at the indicated
level. Valid trace levels
correspond to the levels
available for the IDfSession.
setServerTraceLevel
method.
WEBCACHE_PUBLISH

‑recreate_property_schema TRUE or FALSE Performs a full refresh and
destroys and recreates the
propdb tables.
You must have Superuser

privileges to set this option
to TRUE. The default is
FALSE.
—resync_state_table TRUE or FALSE TRUE deletes state
information in the
probdb_tablename_m
table and recreates the
information based on
the current configuration
object.
The default for this flag is

FALSE.
‑store_log TRUE or FALSE Creates a log file object
in the repository for each
publish operation.
By default, this flag is

TRUE for all full refresh
and incremental publishing
operations and FALSE
when the method is issued
for a single item.
Return value
The WEBCACHE_PUBLISH administration method returns a collection identifier for

a collection with one property. The property, method_return_val, contains 0 if the
operation was successful.
Permissions
You must have Sysadmin or Superuser privileges to use this administration method.
WEBCACHE_PUBLISH
Generating a log file
When the operations generate a log file, the document is stored in the repository in
/System/Sysadmin/Reports/Webcache. By default, the method does not generate a
log file if you are publishing only a single item. To force it to generate a log file for
single‑item operations you can include the ‑store_log argument, set to TRUE
Example
dmAPIGet("apply,s0,080015b38001a43c,WEBCACHE_PUBLISH,
ARGUMENTS,S,source_object 090015b38007bf19")
WEBCACHE_PUBLISH
Chapter 4
Using DQL
This chapter introduces DQL and then provides usability information for DQL. The chapter includes
the following topics:
• Introducing DQL, page 377, introduces the Document Query Language and its basic query
statements.
• Quoting object type and property names, page 379, describes a recommended best practice for
referencing object type and property names in queries.
• NULLs, default values, and DQL, page 380, describes how DQL handles NULLs and default
values.
• Repeating properties in queries, page 382, describes how to reference repeating properties
in queries.
• Querying virtual documents, page 387, describes how to query virtual documents.
• Full‑text searching and virtual documents, page 388, describes how you can conduct a fulltext
search on an assembled virtual document.
• Querying registered tables, page 388, describes how to reference registered tables in queries.
• Caching queries, page 390, describes how to cache query results.
• Privileges, permissions, and queries, page 390, describes how privileges and permissions affect
query results.
For information about using DQL and XDQL to query XML documents, refer to the XML Application
Development Guide.
Introducing DQL
DQL is the acronym for Document Query Language, the SQL‑like language that you
use to query the objects in a repository. Using DQL, you can retrieve, update, and
delete objects and create new objects. DQL also allows you to search indexed content
and metadata (property values).
Using DQL
You can also use DQL to access registered tables—tables in the underlying RDBMS that
are known to Content Server but that are not part of the repository. (Content Server
Fundamentals describes the database tables that make up a repository.)
The basic DQL query statements retrieve information about the objects in a repository
and manipulate those objects. Table 94, page 378, describes the basic query statements.
Table 94. DQL basic query statements
Statement Description
SELECT The SELECT statement is the primary
query statement. SELECT statements
return a wide variety of information from
the repository. SELECT statements are
not only stand‑alone statements but are
also used in other DQL statements.
There are two variants of the SELECT

statement. One is the standard SELECT
statement, and the other is called an
FTDQL SELECT statement. FTDQL
queries are run entirely against the
fulltext index, which provide performance
benefits. However, the syntax for an
FTDQL query is a subset of that for a
standard query. For more information,
refer to Select, page 130 or to the summary
of the syntax in Appendix C, DQL Quick
Reference
UPDATE The UPDATE statement changes the
RDBMS table that underlies a registered
table.
UPDATE...OBJECT The UPDATE...OBJECT[S] statement
modifies objects in the repository. Using
this statement, you can:
• Set the value of a single‑valued

property
• Append or insert values in a repeating
property
• Remove a value from a repeating
property
• Truncate a repeating property (remove
all values)
Using DQL
Statement Description
• Link an object to a folder or cabinet or
unlink an object
• Move an object to a new folder or
cabinet
CHANGE...OBJECT The CHANGE...OBJECT[S] statement
moves one or more objects from one
object type to another. With some
constraints, you can change an object of
a particular type to any type that is a
subtype or supertype of the current type.
For example, you can change an object
of type dm_document to a user‑defined
document subtype.
INSERT The INSERT statement adds a row to the
RDBMS table that underlies a registered
table.
DELETE The DELETE statement destroys rows
in the RDBMS table that underlies a
registered table.
DELETE...OBJECT The DELETE...OBJECT[S] statement
deletes objects from the repository.
When you issue one of these statements, only those objects for which you have the
appropriate permissions are affected. For example, if you issue an UPDATE...OBJECT
statement to update document objects, only those documents for which you have at least
Write permission are considered for updating. In addition, the statements have optional
clauses that let you identify specifically which objects are the target of the operation.
For a complete description of query statement syntax and usage, refer to the statement
descriptions in Chapter 2, DQL Statements, in the Content Server DQL Reference Manual.
Quoting object type and property names

Place double quotes around all references to object type names and property names in
DQL queries. While not required, this best practice ensures that the names will not
conflict with words reserved by DQL or the underlying RDBMS.
To encourage this practice, object type and property names are double quoted in all
Content Server documentation.
Using DQL
NULLs, default values, and DQL

Documentum does not allow you to assign NULLs as a property value because NULLs
are used to terminate the lists of values in repeating properties.
When you create an object, any properties that you do not set are assigned default values
by the server. If a default value is defined in the data dictionary, the server assigns that
value. Otherwise, the default value depends on the data type of the property. Table 95,
page 380, lists the default values by data type.
Table 95. Default property values by datatype
Datatype Default value

String A single blank
Numeric data type 0
Date The NULLDATE value:
• For Oracle and DB2, it is 01/01/0001.

• For Sybase, the value is 1/1/1753.
• For MS SQL Server, it is 1/1/1753.
When you query a property containing a default value using DQL, the default values are
returned in the following manner:
• The default character string value (a single blank) is returned as an empty string.
• DQL also returns a single blank found in a registered table column as an empty string.
• The default numeric value (zero) is returned as zero.
• NULLDATE values are returned as the word NULLDATE.
If you are using SQL (for example, in a user‑written report writer), the default values are
returned in the following manner:
• The default character string value (a single blank) is returned as a single blank.
• SQL also returns a single blank found in a registered table column as a single blank.
• The default numeric value (zero) is returned as zero.
• NULLDATE values are returned as the actual date (for example, 1/1/1 in Oracle).
Testing for default and NULL values

Documentum provides predicates for use in WHERE clauses to test for the presence of
default values or NULLs. Table 96, page 381, briefly describes these predicates. For
a complete list of predicates, refer to Predicates, page 30, of the Content Server DQL
Reference Manual.
Using DQL
Table 96. Predicates that test for NULL and default values
IS [NOT]NULL Used only for columns in registered
tables. Tests for the presence of NULL.
ANY...IS [NOT]NULL Tests for the presence of the NULL
terminator in a repeating property. This is
primarily useful if you are testing values
in two or more repeating properties at
corresponding index levels.
[ANY]...IS [NOT]NULLDATE Tests for the presence of the NULLDATE
or a NULL. Use the ANY option if the
property is a repeating property.
[ANY]...IS [NOT]NULLSTRING Tests for the presence of the default string
value (a single blank) or a NULL in a
property. Use the ANY option if the
[ANY]...IS [NOT]NULLINT Tests for the presence of the default
numeric value (a zero) or a NULL in a
property. Use the ANY option if the
For more information about querying repeating properties, refer to Repeating properties
in queries, page 382.
Default values and aggregate functions

Aggregate functions are functions that operate on a group of values and return a single
value. For example, count is an aggregate function. It counts the values in a property
and returns the number.
Aggregate functions do not ignore the default values assigned to a property. These
values are included in any calculations performed by the function. For example, suppose
a repeating property value can range from 1 to 10. If an object has three actual values (4,
7, and 6) and one default value (one zero) for the property, the AVG function adds 4, 7, 6,
and 0, then divides the total by 4 to obtain the average:
(4 + 7 + 6 + 0)/4 = 4.25
If the function ignores the default value, the average is:

(4 + 7 + 6)/3 = 5.66
As another example, look at the following SELECT statement:
Using DQL
SELECT COUNT(DISTINCT ratings) FROM "recipe"

WHERE "object_name" = 'lemon cake'
This statement (assuming the property values for ratings described for the previous
example) returns the number 4 because the default value is counted.
You can use the WHERE clause to exclude the default value when you are selecting
aggregate functions. For example, the following statement returns the correct number of
ratings for the lemon cake recipe:
SELECT COUNT(DISTINCT rating) FROM "recipe"
WHERE "object_name" = 'lemon cake'
AND "rating" IS NOT NULLINT
Sorting and nulls

Different databases handle NULLs differently when they are sorting values in a table.
Here is how each repository handles NULLs if the sort order is ascending:
• In Oracle and DB2, NULLs are sorted to the bottom of the list.
• In Sybase, NULLs are sorted to the top of the list.
• In MS SQL Server, NULLs are sorted to the top of the list.
Repeating properties in queries

Repeating properties store multiple values. In Documentum, many object types have
repeating properties. For example, because a document can have multiple authors, the
authors property of the dm_document type is a repeating property.
You can reference repeating properties in:
• The selected values list in a SELECT statement
• WHERE clause qualifications for SELECT, UPDATE...OBJECT, CHANGE...OBJECT,
and DELETE...OBJECT statements
• The update clauses of the CREATE...OBJECT, UPDATE...OBJECT, and
CHANGE...OBJECT statements
For information about using a repeating property in SELECT statement, as a selected
value or in the WHERE clause qualification, refer to Select, page 130.
Using DQL
Modifying repeating attributes

You can use the UPDATE...OBJECT statement to add, delete, and modify individual
values for repeating properties. In most of these operations, you must specify the index
position of the value you want to change. The index indicates the value’s position in the
list of values assigned to the repeating property. Index numbers begin with zero for the
first value and increment by 1 for each additional value.
For example, suppose the a recipe object type has a repeating property called ingredients.
One recipe has the following ingredients: eggs, sugar, cream cheese, and amaretto.
Assuming the ingredients were added to the ingredients property for a recipe object in
the order listed, they would have the following index values:
ingredient[0] (eggs)
ingredient[1] (sugar)
ingredient[2] (cream cheese)
ingredient[3] (amaretto)
Index positions are always specified inside square brackets after the name of the property.
Adding new values
To add a value to a repeating property, you can:

• Insert the new value, which lets you choose where to put the new value in the
property’s value list
• Append the value, which automatically places the value at the end of the property’s
value list
Inserting values
When you want to control where the new value is placed in the repeating property, use
the insert option as the update clause in the UPDATE...OBJECT statement. The syntax is:
UPDATE object_type OBJECTS
INSERT property_name[x] = value
...
For example, suppose that the authors of the Espresso Cheesecake recipe forgot to
include one of the ingredients for the crust. The ingredients for the crust are listed ahead
of the ingredients for the filling in the document. Consequently, the authors want to
insert the forgotten ingredient ahead of the filling ingredients so that it appears with the
other crust ingredients. The ingredients for the crust occupy positions 0 through 3 in
the ingredients property, and the filling ingredients begin at position 4. The following
statement inserts the forgotten ingredient at position 4.
Using DQL
UPDATE "recipe" OBJECTS

INSERT ingredients[4] = '2 T ground bittersweet chocolate'
WHERE "title" = 'Espresso Cheesecake'
The server inserts the requested value and renumbers all other values from position 4 on.
The filling ingredients now begin at position 5.
Inserting values into a repeating property never overwrites a current value. Any
value currently at the specified insertion point and any following values are always
renumbered.
If you do not specify an insertion point, the server automatically inserts the new value in
the first position (property_name[0]).
You can identify the value you want to insert either as literal value or by using a
subquery. If you use a subquery, it can return only one value. If it returns multiple
values, the INSERT statement fails with an error.
Appending values
When you append values, the server automatically adds the new value to the end of
the list of values in the property. You do not have to specify an index value when
you append. To illustrate, suppose the authors want to add another ingredient to the
Espresso Cheesecake recipe: strawberries to be used as a garnish. To append this
ingredient, they use the following statement:
UPDATE "recipe" OBJECT
APPEND "ingredients" = '1 pint strawberries'
WHERE "title" = 'Espresso Cheesecake'
You can identify the appended value as a literal value or by using a subquery. For
example, perhaps your company is reorganizing and employees currently working for
Mr. Rico are being moved to a group called frontline. The following statement uses a
subquery to find those employees and append them to the list of users in the frontline
group:
UPDATE "dm_group" OBJECTS
APPEND "users_names"=(SELECT "user_name"
FROM "dm_user","employees" e
WHERE e."manager"='rico' AND "r_is_group"=F)
WHERE "group_name" = 'frontline'
When using a subquery, you can specify the maximum number of values that you want
to append. The syntax in the update clause is:
APPEND n property_name = subquery
where n represents the maximum number of appended values.
Using DQL
Updating values
To update a value, use the set option as the update clause.

For example, the authors of Heavenly Cheesecakes have decided to update one of the
recipes in the book. They want to replace the cream cheese requirement with a lower‑fat
substitute—ricotta cheese. Knowing that cream cheese is the third ingredient in the
ingredients list, they use the following statement to make the substitution:
SET ingredients[2] = '1 lb ricotta cheese'
WHERE "title" = 'mocha cheesecake'
Note that the index value for cream cheese is [2]. This is because index values are
counted from zero, so the first two ingredients (eggs and sugar) have index values of
zero and one ([0] and [1]), respectively.
Deleting values
To delete a value in a repeating property, use the remove option as the update clause and
specify the index value associated with the value. To illustrate, the following example
removes the fifth ingredient in a list of ingredients for brownies:
REMOVE ingredients[4]
WHERE "object_name" = 'Mandarin Brownies'
If you do not specify which value to remove, the system automatically removes the
first ([0]) value.
Forcing index correspondence in query results

Note: The query syntax described in this section may not be used in an FTDQL SELECT
statement. (For information about FTDQL SELECT statements, refer to Select, page 130.)
In some queries, you may only want objects for which the repeating property values are
in the same relative positions. For example, perhaps you want only those recipes for
which a particular author and keyword occupy the same index position.
To require index correspondence for expressions referencing repeating properties, use
the following syntax:
ANY ([NOT] predicate AND [NOT] predicate
{AND [NOT] predicate})
To force index correspondence, the predicates must be ANDed inside the parentheses.
Using the OR operator to link the predicates inside the parentheses increases the query’s
Using DQL
performance but does not force index correspondence. The query returns any object that
contains one of the ORed values.
To illustrate, assume that the keywords untried, tested, approved, and rejected are
assigned to recipes in various stages of acceptance and that these keywords are always
placed in the first position in the keywords list, to correspond to the implicit version
label (the numeric label) associated with the recipe. The following statement finds only
original recipes (version 1.0) that were rejected by the testers:
SELECT "r_object_id", "object_name" FROM "recipe"
WHERE ANY ("r_version_label" = '1.0'
AND "keywords" = 'rejected')
In the above example, for the recipes returned, r_version_label[0] = 1.0 and keywords[0]
= rejected.
You can’t specify which position is searched when you force index correspondence. You
can only specify that the values be found in the same position. In the above example,
it was easy to know that the values are in the first position for all pairs because the
implicit version label is always stored in the first position. However, for other repeating
properties this will not be true. For example, look at the following statement:
UPDATE "recipe" OBJECTS
SET "subject" = 'lowfat meals'
WHERE ANY ("ingredients" IN ('skim milk','margarine')
AND "keywords" = 'fat free')
The statement updates the subject property for any recipe for which skim milk and
fat free or margarine and fat free occupy the same respective positions within their
individual properties. For one recipe, the positions might be the fourth: ingredients[3]
= margarine and keywords[3] = fat free. For another, the values might be found in the
seventh position: ingredients[6] = skim milk and keywords[6] = fat free. In all instances,
the values are at the same index position within their properties.
It is possible to combine both forms of the syntax. For example:
SELECT "r_object_id", "title" FROM "recipe"
WHERE ANY "ingredients" IN ('cream cheese','chocolate')
AND ANY("authors" = 'daphne' AND "keywords" IN ('cheesecake','brownies','mousse'))
This statement returns all recipes that have cream cheese or chocolate as an ingredient
and also have the author daphne paired with the keyword cheesecake, brownies, or
mousse.
Performance note for Sybase or MS SQL Server users

DQL turns repeating property predicates (and the FOLDER predicate) into ORed
subselects internally. Queries that contain ORed subselects run slowly against Sybase
Using DQL
and MS SQL Server, and performance degrades in direct proportion to the number of
SysObjects in your repository.
To improve performance, here are some suggested alternative ways to formulate queries:
Instead of:
SELECT "r_object_id" FROM "dm_sysobject"
WHERE ANY "authors" = 'a' OR ANY authors = 'b'
Use:
WHERE ANY ("authors" = 'a' OR "authors" = 'b')
Instead of:
WHERE FOLDER ('/Temp) OR FOLDER ('/System')
Use:
WHERE FOLDER ('/Temp', '/System')
Querying virtual documents

Virtual documents are documents that contain other documents. The documents they
contain can be simple documents or other virtual documents. Nesting virtual documents
inside other virtual documents creates a hierarchy of components within the top‑level
virtual document. Documentum allows you to nest virtual documents to any depth
you choose.
To identify the virtual document you want to query, you can use either the IN
DOCUMENT clause or the IN ASSEMBLY clause in a SELECT statement. The IN
DOCUMENT clause allows you to choose which set of the document’s components to
query at runtime. The IN ASSEMBLY clause directs the query to the virtual document’s
snapshot, which is a previously selected set of the document’s components.
If you are querying a virtual document in an UPDATE...OBJECT or DELETE...OBJECT
statement, you must use the IN ASSEMBLY clause.
Both the IN DOCUMENT and IN ASSEMBLY clauses include the optional keyword
DESCEND. This keyword directs the server to search any components contained
by components that are themselves virtual documents. The only exception is if the
component is a reference link. In such cases, the server can’t search for the component’s
contained components. The search returns only the reference link.
Documentum also allows you to specify one particular component of a virtual document
as the target of a query. This feature can make it easy for users who are working on a
Using DQL
virtual document to pull out a specific part of the document for work. The NODE option
of the IN ASSEMBLY clause implements this feature.
Fulltext searching and virtual documents

Like simple documents, virtual documents can have associated content files. Marking a
virtual document for indexing directs Content Server to index the content files associated
with the virtual document—not the components of the virtual document.
In SELECT statements, if you include a SEARCH clause and an IN DOCUMENT clause,
the server first searches to see whether the content files of the specified virtual document
meet the full‑text search criteria. Then, as the server assembles the virtual document,
the criteria in the SEARCH clause are applied to the content files associated with each
component.
If you want to conduct fulltext searches on the assembled document components,
you must create a file from the assembled document and associate it with the virtual
document as a content file. Use the following procedure:
To index an assembled document as a whole:

1. Assemble the document.
2. Print the document to a file.
3. Use Setfile or Setcontent to associate the resulting file with the virtual document as
a content file.
Now you have a content file for the virtual document that represents the assembled
document and that can be indexed.
Querying registered tables

Registered tables are tables in the underlying RDBMS that have been registered with
the repository. You must register any RDBMS table that you wish to query using DQL.
Registering a table creates an object of type dm_registered for that table. (Refer to
Register, page 123, in the Content Server DQL Reference Manual for information about
registering tables.)
To obtain information about the repository object that represents the table, specify the
dm_registered type in the FROM clause of the SELECT statement. The server searches
for the object representing the table. To query the table itself, specify the registered
table’s name in the FROM clause. When you query the table, the server searches the
actual underlying RDBMS table—not the dm_registered object type.
Using DQL
Referencing registered tables in queries

To avoid ambiguity in a query, it is often useful to reference a database table by its fully
qualified name; that is, owner_name.table_name.
The owner name is the name of the person who created the table. Tables created by the
system when a repository is created (for example, dm_sysobject_r or dm_sysobject_s)
are owned by the repository owner. For these tables, Oracle and DB2 use the value in
the repository owner’s user_db_name property as the owner name. Sybase and MS SQL
Server prefixes the names of all tables created by the repository owner with the alias
dbo. This alias makes it possible to write applications that are portable across Sybase
and MS SQL Server databases.
For application portability across all repositories, Documentum provides an alias,
dm_dbo, that you can substitute for the repository owner’s name in any fully qualified
reference to registered tables. (For Sybase and MS SQL Server, when referencing
registered tables, the aliases dm_dbo and dbo are equivalent.)
Security controls
Access to a registered table is controlled by the object‑level permissions and table permits
defined for the table’s dm_registered object. The object‑level permissions must give
you at least Browse access to the dm_registered object and the table permits must give
you permission for the operation that you want to perform. For example, if you want
to update a table, the table permits must grant you DM_TABLE_UPDATE permission.
Table permits are defined for three user levels: owner, group, and world. (For complete
information about table permits and Documentum security, refer to the Content Server
Administration Guide.)
Additionally, the user account under which Content Server is running must have the
appropriate RDBMS permission to perform the requested operation on the specified
table. (The actual name of this permission depends on your RDBMS.) For example, if
you want to update the table, the server account must have permission in the RDBMS
to update the table.
All three of these conditions must be met to gain access to a registered table. Even if a
user has permission to access the underlying table through the RDBMS, the user will not
have access through DQL unless the object‑level permissions and table permits on the
dm_registered object permit access. Similarly, a user might have the correct object‑level
permissions and table permits, but if the server’s user account in the RDBMS does not
have permission, then access is denied.
Using DQL
Default objectlevel permissions and table permits
The REGISTER statement automatically sets the object‑level permissions for a table’s
dm_registered object to default values. The statement also sets the default table permit to
SELECT for the owner (group and world have no default table permit).
You can change the object‑level permissions and table permits by setting the appropriate
properties directly. The Content Server Administration Guide provides more information
about these properties.
Caching queries
Some queries return the same results every time you run the query. For example, a
payroll application may ask for the names and social security numbers of the employees
in the company. Although the query results may change over a long period of time,
they may not change from week to week. Rather than incur the performance cost of
rerunning the query that returns the users and social security numbers each time the
payroll application executes, you can cache the query results on the client host. For
information about persistent caching, refer to Content Server Fundamentals.
Privileges, permissions, and queries

DQL query statements affect only those objects for which users have the appropriate
permissions or privileges.
When a SELECT statement references a SysObject type (dm_sysobject or any of its
subtypes), by default, only those objects of the referenced type for which the user has
at least Browse permission are retrieved. If the SELECT statement includes a SEARCH
clause that accesses the object’s content, then the user must have at least Read permission.
However, the SELECT statement supports an option to allow you to specify another
base permission level. For example, you might use a query that returns only objects for
which a user has at least Relate permission.
If the object type specified in the SELECT statement is modified by the keyword PUBLIC,
then the statement retrieves only objects that have a world permission of at least Browse
(or Read for full‑text searches) or objects that are owned by the user.
When a SELECT statement references a registered table, the user must have at least
Browse permission on that registered table for the query to succeed. In addition, Content
Server must have the SELECT privilege in the RDBMS.
Using DQL
The Superuser user privilege bypasses all Documentum security checks. However,
Content Server must still have the SELECT privilege in the RDBMS for a superuser to
query registered tables.
You must have Write permission to update an object with the UPDATE...OBJECT
statement. You must have Delete permission for an object to delete it using the
DELETE...OBJECT statement.
Using DQL
Appendix A
Using DQL Hints
This appendix describes how DQL hints are implemented and how to use them in your queries.
• General guidelines for all, page 393
• SQL_DEF_RESULT_SET N, page 394
• FORCE_ORDER, page 395
• RETURN_TOP N, page 396
• OPTIMIZE_TOP N, page 398
• FETCH_ALL_RESULTS N, page 399
• OPTIMIZATION_LEVEL level_1 level_2, page 399
• UNCOMMITTED_READ , page 400
• IN and EXISTS, page 400
• ROW_BASED, page 401
• FTDQL and NOFTDQL, page 403
• TRY_FTDQL_FIRST, page 403
• FT_CONTAIN_FRAGMENT, page 403
• GROUP_LIST_LIMIT N, page 404
• HIDE_SHARED_PARENT, page 404
• Including multiple hints limiting rows returned, page 405
• Passthrough hints, page 405
General guidelines for all

Database hints affect how a query is executed. When deciding whether to use a hint, it
is recommended that you execute the query with and without the hint. Compare the
generated SQL queries and compare the response time and the resource use to determine
whether the hint is helpful.
Using DQL Hints
You can use any of the hints except ROW_BASED in an FTDQL query. The ROW_BASED
hint may not be included in an FTDQL query.
Additionally, you may not use the ROW_BASED hint in query that includes a lightweight
object type in the FROM clause.
SQL_DEF_RESULT_SET N
The SQL_DEF_RESULT_SET N is most useful on a SQL Server database. On a SQL
Server database, including SQL_DEF_RESULT_SET in a query causes the RDBMS to use
default result sets to return the query results rather than a cursor. Using default result
sets is the way that Microsoft recommends accessing a SQL Server database.
On other databases, it only controls how many rows are returned, and is identical to
the RETURN_TOP hint.
On SQL Server, using default result sets allows the RDBMS server to perform fewer
logical read operations. Table 97, page 394 shows some test examples:
Table 97. Comparison of logical reads with and without default result sets
Query Number of returned Number of Number of

rows logical reads logical reads
without DRS with DRS
SELECT object_name 1 36 5
FROM dm_document
WHERE r_object_id=
’0900014c8000210b’
FROM dm_document
WHERE r_creator_name=
’user2’
FROM dm_document
WHERE r_creator_name=
’user1’
However, the reduction in I/O may be offset by higher CPU costs. Additionally, because
using default result sets requires Content Server to buffer the results of a query in
memory, higher memory use is a result. (When using default result sets, two queries
cannot be open simultaneously. If a query is issued, before another can be issued from
the same session, all results from the first must be processed. To work around this
Using DQL Hints
limitation, Content Server internally buffers the results of queries that are executed
using default result sets.)
To determine whether using SQL_DEF_RESULT_SETS is useful for a query, run the
query with and without the hint and trace the results using the SQL Server Profiler.
Setting N to 0 causes all results to be returned. Setting N to an integer value limits the
number of rows returned to that value.
Using SQL_DEF_RESULT_SETS is recommended if:
• You are running on a SQL Server database.
• The query returns limited result sets.
• The query is a commonly executed query.
• Tests show that using the hint greatly improves query performance.
FORCE_ORDER
The FORCE_ORDER hint controls the order in which the tables referenced in the query’s
FROM clause are joined. The tables may be RDBMS tables or object type tables.
Oracle and SQL Server implement this hint at the statement level. For example, suppose
you issue the following DQL:
SELECT object_name
FROM DM_SYSOBJECT ENABLE(FORCE_ORDER)
The generated SQL for Oracle is:

select /*+ ORDERED */ object_name from dm_sysobject_s;
The generated SQL for SQL Server is:

select object_name from dm_sysobject_s
OPTIONS (FORCE_ORDER)
Sybase implements the hint at the session level. If you include the hint, Content Server
uses the ct_options function to set the CS_OPT_FORCEPLAN variable to true and unsets
it after the query executes.
Using FORCE_ORDER may not ensure that you obtain a particular join order. When
you examine the SQL query generated by a DQL query, you may find there are more
tables in the FROM clause than are present in the DQL query. This is because Content
Server often uses views to generate the SQL for many DQL queries and may also add
ACL tables to the queries for security checks.
If you are considering using this hint, run the query without the hint and obtain the
generated SQL statement and the execution plan. If the join order in the generated query
appears incorrect and you believe that joining the tables in the order they appear in
Using DQL Hints
the DQL query will result in better performance, run the query with FORCE_ORDER.
Compare the results to the query execution results without the hint.
If you use this hint, it is recommended that you retest the query with and without the
hint occasionally to ensure that the hint is still useful. Database changes can make the
plan chosen by the hint incorrect.
RETURN_TOP N
The RETURN_TOP N hint limits the number of rows returned by a query.
Databasespecific implementations
The following sections describe how RETURN_TOP is handled for individual databases.
SQL Server
On SQL Server, using this hint results in fewer database rows being touched by a query.
The internal behavior of query on SQL Server is:
1. The query executes on the database (touching whatever tables are required) and
generates a list of keys or lookup IDs inside the tempdb.
2. Each time a row is fetched from the cursor, the lookup ID accesses the actual table to
return the full result set with all columns.
When you include the RETURN_TOP hint, the second step is executed only as many
times as the hint directs. For example, if the hint is RETURN_TOP 20, then only 20 rows
are returned and the table is accessed only 20 times.
Including RETURN_TOP adds the SQL Server TOP hint to the generated SQL statement.
For example, suppose you issue the following DQL statement:
SELECT user_name FROM dm_user ENABLE (RETURN_TOP 3)
The generated SQL for SQL Server is:

select TOP 3 user_name from dm_user_s
Using DQL Hints
Subqueries and the hint
If the query includes a subquery, the hint is not applied to the subquery.
DB2
On a DB2 database, including RETURN_TOP adds the FETCH FIRST N ROWS ONLY
hint to the generated SQL statement. For example, the following DQL query
SELECT user_name FROM dm_user ENABLE (RETURN_TOP 3)
is translated to the following SQL statement

select user_name from dm_user_s
FETCH FIRST 3 ROWS ONLY
It is recommended that you use RETURN_TOP in conjunction with OPTIMIZE_TOP.

The previous example becomes:
SELECT user_name FROM dm_user
ENABLE (RETURN_TOP 3, OPTIMIZE_TOP 3)
The statement generates the following SQL:

select user_name from dm_user_s
FETCH FIRST 3 ROWS ONLY OPTIMIZE FOR 3
Oracle and Sybase
If you include RETURN_TOP in a query running against Oracle or Sybase, the returned
results are not limited at the database level, but by Content Server itself. Consequently,
using RETURN_TOP on Oracle or Sybase results in no database performance gains,
but may reduce network traffic.
Effects of a SEARCH clause

If the DQL query includes a SEARCH clause, to limit results to documents that are
indexed, the implementation of RETURN_TOP depends on whether the searched
documents are public or not.
If all the searched documents are public, the returned results are limited at the fulltext
index level. If the searched documents are not all public, then the limits are imposed
when Content Server performs the security checking on the returned results.
Using DQL Hints
Recommended use
Use RETURN_TOP when:
• Only a particular number of rows is needed from the database.
• The application accepts ad hoc queries from users and you want to limit the potential
damage an unbounded query might cause.
Using RETURN_TOP if the query sorts the results or includes the DISTINCT keyword
reduces the efficiency of the hint.
OPTIMIZE_TOP N
The OPTIMIZE_TOP N hint directs the database server to return the first N rows
returned by a query quickly. The remaining rows are returned at the normal speed.
On SQL Server and DB2, you can include an integer value (as N) to define how many
rows you want returned quickly. On Oracle, the number is ignored. The OPTIMIZE_TOP
hint is not available on Sybase.
For example, suppose you issue the following DQL query:
SELECT r_object_id FROM dm_sysobject
ENABLE (OPTIMIZE_TOP 4)
On SQL Server, the generated SQL statement is:

select r_object_id from dm_sysobject_s
OPTION (FAST 4)
On DB2, the generated SQL statement is:

select r_object_id from dm_sysobject_s
OPTIMIZE FOR 4 ROWS
On Oracle, the generated SQL statement is:

select /*+ OPTIMIZE_TOP */ r_object_id
from dm_sysobject_s
OPTIMIZE_TOP is recommended for use:

• When you want to return all the results but want the first few rows more quickly
• With the RETURN_TOP hint, to optimize the return of specified rows
• When the execution plan chosen for query is a bad plan and there is no obvious
solution
Using OPTIMIZE_TOP if the query sorts the results or includes the DISTINCT keyword
reduces the efficiency of the hint.
Using DQL Hints
FETCH_ALL_RESULTS N
The FETCH_ALL_RESULTS N hint fetches all the results from the database immediately
and closes the cursor. The hint does not affect the execution plan, but may free up
database resources more quickly.
To fetch all the results, set N to 0.
On SQL Server, it is recommended that you use SQL_DEF_RESULT_SETS instead of the
FETCH_ALL_RESULTS hint. SQL_DEF_RESULTS_SETS provides the same benefits and
is the recommended way to access SQL Server databases.
Use FETCH_ALL_RESULTS if you want to reduce the resources used by the database
server by quickly closing cursors. On SQL Server, try FETCH_ALL_RESULTS if using
SQL_DEF_RESULT_SETS did not improve query performance.
SQL Server, the hint, and subqueries

If you use this hint on query against a SQL Server database and the query includes a
subquery, the hint is not applied to the subquery.
OPTIMIZATION_LEVEL level_1 level_2

Use the OPTIMIZATION_LEVEL hint against a DB2 database when you want to change
the optimization level for a particular query. The level you set in the level_1 argument
is used for the current query and after the query is finished, Content Server sets the
optimization level to the level specified in the level_2 argument.
Using this hint generates a SQL trace that looks like the following:
set current optimization level level_1
run query
set current optimization level level_2
This hint is ignored for all databases except DB2.

For more information or assistance on the level_1 and level_2 parameters, please contact
your DB2 database vendor.
Using DQL Hints
UNCOMMITTED_READ
Use the UNCOMMITTED_READ hint in read only queries, to ensure that the query
returns quickly even if another session is holding locks on the tables queried by the
read only query.
This hint is useful only on SQL Server, DB2, and Sybase databases.
IN and EXISTS
IN and EXISTS are mutually exclusive hints that you can use in a standard WHERE
clause, in a repeating property predicate that contains a subquery. These hints may not
be used in a WHERE clause in an FTDQL query.
The syntax is:
WHERE ANY [IN|EXISTS] property_name (subquery)
For example:
WHERE ANY IN "authors" IN
(SELECT "user_name" FROM "dm_user")
If you do not include either IN or EXISTS explicitly, when Content Server translates the
query, it includes one or the other automatically. Which hint Content Server chooses to
include is determined by the indexes present in the repository, the properties referenced
in the query, and other factors.
The queries generated by each option are different and perform differently when
executed. For example, here is the generated SQL statement for the query in the previous
example:
select all dm_sysobject.r_object_id
from dm_sysobject_sp dm_sysobject
where (dm_sysobject.r_object_id in
(select r_object_id from dm_sysobject_r
where authors in
(select all dm_user.user_name
from dm_user_sp dm_user)))
and (dm_sysobject.i_has_folder=1 and
dm_sysobject.i_is_deleted=0)
If the DQL query used the EXISTS hint, the generated SQL statement would look like this:
select all dm_sysobject.r_object_id
from dm_sysobject_sp dm_sysobject
where (exists (select r_object_id
from dm_sysobject_r
where dm_sysobject.r_object_id = r_object_id
and authors in
Using DQL Hints
(select all dm_user.user_name

from dm_user_sp dm_user )))
and (dm_sysobject.i_has_folder=1 and
dm_sysobject.i_is_deleted=0)
If you feel that a query that references a repeating property predicate that uses a
subquery is performing badly, run the query and examine the generated SQL statement
to determine which hint Content Server is adding to the generated SQL and note the
performance time. Then, rewrite the DQL query to include the hint that the server isn’t
choosing. For example, if the server is choosing to add the EXISTS hint to the generated
SQL statement, rewrite the DQL query to include the IN hint. Then, rerun the query to
determine if the performance improves.
ROW_BASED
The ROW_BASED hint changes both the way query results are returned and the syntax
rules for the query itself.
This hint may not be used in FTDQL queries or queries that reference a lightweight
object type in the FROM clause.
Effects on returned results

The ROW_BASED hint forces Content Server to returns query results in a row format,
as opposed to an object‑based format. The difference is most readily apparent if the
query selects values from a repeating property. In an object‑based format, the server
returns all selected repeating values for a particular object in one query result object.
In a row‑based format, the server returns each selected repeating property value in a
separate query result object.
For example, by default the following query returns results in an object‑based format:
SELECT "r_object_id","title","authors" FROM "dm_document"
WHERE "subject"='new_book_proposal'
That query returns the authors values as a list of authors in one query result object for
each returned object. Table 98, page 402, shows how the results are returned. Each
row in the table represents one query result object and each column is one property in
the query result objects.
Using DQL Hints
Table 98. Example of objectbased query results

090000015973a2fc Our Life and Times Jennie Doe Carol Jones
Hortense Smith
0900000123ac12f6 Life of an Amoeba James Does Jules Doe
There is one query result object (one row) for each object returned by the query. Now,
add the ROW_BASED hint to the query:
SELECT "r_object_id","title","authors" FROM "dm_document"
WHERE "subject"='new_book_proposal'
ENABLE(ROW_BASED)
Table 99, page 402, illustrates how Content Server returns the results for that query.
Table 99. Example of rowbased query results

090000015973a2fc Our Life and Times Jennie Doe
090000015973a2fc Our Life and Times Carol Jones
090000015973a2fc Our Life and Times Hortense Smith
0900000123ac12f6 Life of an Amoeba James Doe
0900000123ac12f6 Life of an Amoeba Jules Doe
There is one query result object (one row) for each repeating property value returned.
The returned repeating property values for each object are not aggregated into one
result object.
Effects on query syntax rules

In addition to the changes the hint causes in the returned results, including the hint also
changes some of the syntax rules for a query. The hint affects:
• Query syntax rules when a repeating property is a selected property
Repeating properties, page 138, describes how the hint affects query syntax rules
when a repeating property is selected.
• The use of repeating properties in expressions in WHERE clauses
Using repeating properties in qualifications, page 162, describes how the hint affects
the use of repeating properties in WHERE clause qualifications.
Using DQL Hints
• The behavior of the asterisk as a selected value

The asterisk (*) as a selected value, page 148, describes how the hint affects the
returned values for an asterisk.
FTDQL and NOFTDQL

The FTDQL hint supports the FTDQL functionality. If you include this hint in query,
Content Server attempts to execute the query as an FTDQL query. If the remaining
syntax in the query conforms to the required syntax for an FTDQL query, the query is
executed as an FTDQL query. If the syntax does not conform to FTDQL query rules,
an error is returned.
If you include the NOFTDQL hint, the query is run as a standard SELECT query whether
the syntax satisfies the FTDQL query rules or not.
TRY_FTDQL_FIRST
The TRY_FTDQL_FIRST hint is useful if a query is timing out or exceeds a resource
limit in the full‑text engine. When it is included in a query, the query is first executed
as an FTDQL query, and if a timeout or resource exceeded error occurs, the query is
then retried as a standard query.
FT_CONTAIN_FRAGMENT
The FT_CONTAIN_FRAGMENT hint expands the range of matches for full‑text searches
that include a search clause of the form LIKE ’%string%’ clause, such as:
subject LIKE '%work%'
When the query includes the DQL hint FT_CONTAIN_FRAGMENT, this clause returns
all objects whose subject contains “work” in any position, including where the string
appears as part of a larger string. For example, it returns any object whose subject
contains “networking” or “workers”. However, if the query does not include this
hint (the default behavior), a full‑text search that uses this clause returns only those
objects whose subject contains “work” (or a variant form of the word if grammatical
normalization is enabled) as a separate word. Limiting the results to separate word
matches improves the performance of the query. Beginning with release 6.0, the default
behavior was changed. In previous releases, the default was to return objects as though
FT_CONTAIN_FRAGMENT was specified.
Using DQL Hints
The FT_CONTAIN_FRAGMENT hint affects only full‑text searches. Database searches

return partial string matches regardless of this hint. The hint only applies to search
clauses that include a percent sign both before and after the literal string; The behavior
for LIKE ’%work’ and LIKE ’work%’ are unaffected.
GROUP_LIST_LIMIT N
The GROUP_LIST_LIMIT hint may improve query performance when a user is a
member of a large number of groups. For example, suppose a user who is a member of
500 groups executes the following query:
SELECT r_object_id FROM dm_document WHERE object_name LIKE '%dm%'
When this query is translated to SQL, a subquery is needed to perform the ACL checking
because the default group list limit for queries is 250. The performance is slower due
to the need for the subquery. You can use the DQL hint to override the default value
for group list limit. For example:
SELECT r_object_id FROM dm_document
WHERE object_name LIKE '%dm%'
ENABLE(GROUP_LIST_LIMIT 600)
Setting this hint overrides the default value and the DM_GROUP_LIST_LIMIT
environment variable, if that is set.
HIDE_SHARED_PARENT
HIDE_SHARED_PARENT directs Content Server to return only the rows in the query
results that are not shared parents. In order to accomplish this, the server will add two
additional attributes, r_object_id and r_object_type to the SQL statement select list, if
not already there (only applies to dm_sysobject or any of its subtypes). The server will
run the SQL query against the database and then for each qualified row it will get the
value of r_object_type, fetch the type object and check to see if it is a shareable type.
For non‑shareable types it will just return the row, but for shareable types it will do
the following:
• Look in the sysobject cache for the r_object_id object, or issue an SQL statement if the
object is not in the cache, and examine the i_sharing_type.
• Return the row if i_sharing_type is empty, or skip the row if it is not empty
(indicating that the row is from a shared parent).
The results of a query that uses the HIDE_SHARED_PARENT DQL hint will not contain
any shared parents.
Using DQL Hints
Including multiple hints limiting rows returned

If you include more than one hint that limits the rows returned by a query, the number
of rows returned is the least number of rows defined in an included hint. For example,
suppose you issue the following DQL statement:
SELECT object_name FROM dm_document ENABLE
(FETCH_ALL_RESULTS 10, RETURN_TOP 5)
Content Server returns 5 rows for the query because the RETURN_TOP hint is the most
constraining hint in the list.
On SQL Server, if the list includes SQL_DEF_RESULT_SET, the query is always executed
using default result sets regardless of where the hint falls in the list of hints. For example,
suppose you issue the following statement:
SELECT object_name FROM dm_document ENABLE
(SQL_DEF_RESULT_SET 10, RETURN_TOP 5)
The query executes using default result sets but returns only 5 rows.
Passthrough hints
Passthrough hints are hints that are passed to the RDBMS server. They are not handled
by Content Server.
SQL Server and Sybase have two kinds of hints: those that apply to individual tables
and those that apply globally, to the entire statement. To accommodate this, you can
include passthrough hints in either a SELECT statement’s source list or at the end of the
statement. The hints you include in the source list must be table‑specific hints. The hints
you include at the end of the statement must be global hints. For example, the following
statement includes passthrough hints for Sybase at the table level and the statement level:
WITH (SYBASE('NOHOLDLOCK'))
WHERE "object_name"='test' ENABLE (FORCE_PLAN)
For DB2 and Oracle, include passthrough hints only at the end of the SELECT statement.
Syntax
To include a passthrough hint, you must identify the database for which the hint is valid.
To identify the target database, keywords precede the hints. The valid keywords are:
ORACLE, SQL_SERVER, SYBASE, and DB2. For example, the following statement
includes passthrough hints for SQL Server:
Using DQL Hints

WHERE "object_name" ='test'
ENABLE SQL_SERVER('ROBUST PLAN','FAST 4',
'ROBUST PLAN')
For portability, you can include passthrough hints for multiple databases in one
statement. The entire list of hints must be enclosed in parentheses. The syntax is:
(database_hint_list {,database_hint_list})
where database_hint_list is:

db_keyword('hint'{,'hint})
db_keyword is one of the valid keywords identifying a database. hint is any hint valid
on the specified database.
For example:
SELECT object_name FROM dm_document doc dm_user u
WHERE doc.r_creator_name = u.user_name
ENABLE (ORACLE('RULE','PARALLEL'),
SYBASE('AT ISOLATION READ UNCOMMITTED'),
SQL_SERVER('LOOP JOIN','FAST 1')
Error handling and debugging

It is possible to execute a DQL statement that the server considers correct DQL but is
incorrect at the RDBMS level if you incorrectly specify a passthrough hint. If this occurs,
any errors returned are returned by the RDBMS server, not Content Server. Not all
databases return errors on database hints. For example, Oracle does not return an error
if a database hint is incorrect—it simply ignores the hint. For the other databases, the
error messages may be difficult to decipher.
To debug problems with queries containing database hints, you can turn on SQL tracing.
By default, Content Server runs with the last SQL trace option turned on. You can
turn on full SQL tracing using an IDfSession.setServerTraceLevel race method or the
SET_OPTIONS administrative function. The SET_OPTIONS administration method is
described in SET_OPTIONS, page 357.
Appendix B
Implementing Java Evaluation of
Docbasic Expressions
This appendix describes how to implement Java evaluation of Docbasic expressions defined for check
constraints or value assistance in the data dictionarẏ. The appendix includes the following topics:
• Docbasic expression handling by Content Server, page 407
• How DFC Version 6 and later handles the expressions, page 408
• Migrating the expressions for pre‑6 clients, page 408
• Disabling or re‑enabling Java evaluation, page 413
• Docbasic expression components support, page 413
Docbasic expression handling by Content

Server
This section describes how Content Server describes how Docbasic expressions defined
for check constraints or value assistance in the data dictionary are stored in the repository
Figure 2, page 408, illustrates the architecture.
Implementing Java Evaluation of Docbasic Expressions
Figure 2. Repository storage of Docbasic expressions for object types
For each object type that has Docbasic expressions defined as check constraints or in
conditional value assistance for one or more properties, Content Server creates one
expr code object and a number of func expr objects. Each func expr objects records one
Docbasic expression. The expr code object contains the compiled code and pcode that
implements the expressions recorded in the func expr objects. The routine_id property in
the func expr objects points to the expr code object.
How DFC Version 6 and later handles the

expressions
DFC Version 6 and later generates the Java code equivalent to the Docbasic expressions
defined for check constraints or value assistance at runtime. The result is cached in
memory for the life of the DFC process.
Migrating the expressions for pre6 clients

Prior to Version 6, DFC required that the expressions be manually migrated to Java if
you wished to have the expressions evaluated as Java code. If you are running pre‑6
clients, use the information in this section to migrate the Docbasic expressions to Java
code. This section describes how that implementation was stored in the repository and
the methods used to migrate the expressions.
Manually migrating a Docbasic expression for DFC Version 6 and later clients is not
useful. DFC Version 6 (and later) automatically generates Java code at runtime for
Docbasic expressions and will ignore the results of manual migration.
Repository storage of migrated expressions

Migrating an expression manually creates additional repository objects that are
associated with the objects created by Content Server for the expression.
If you migrate an expression to Java, the migration method compiles the expression into
Java code. If the expression is the first expression compiled into Java for the object type,
the migration method also creates a dmc_jar object and a dmc_validation_module object.
The compiled code is stored with the dmc_jar object. The jar object is related to the
validation module object through a relationship named dmc_module_to_jar.
The validation module object points back to the associated expr code object through a
property and is related to the func expr objects using dmc_validation_relation objects.
Validation relation objects are a subtype of dm_relation. The name of the relationship
represented by validation relation objects is dmc_expr_to_module. Both the validation
module and validation relation objects have properties used to manage the Java
evaluation. Figure 3, page 410, illustrates this architecture.
Figure 3. Repository storage of manually migrated Docbasic expressions
If additional Docbasic expressions are added later for an object type, the migration
method updates the validation module and jar objects.
Migrating expressions to Java is currently a manual operation. EMC Documentum
provides two migration methods, described in Migrating Docbasic expressions to Java,
page 410. You can migrate expressions already defined in the data dictionary. You can
migrate new expressions after the expressions are defined using an ALTER TYPE or
CREATE TYPE statement.
Migrating Docbasic expressions to Java

There are two methods that create compiled Java code for Docbasic expressions stored
with expr code objects. These methods are:
• dmc_MigrateDbExprsToJava
Use this method if you want to migrate expressions defined for multiple object types.
• dmc_MigrateDbExprsToJavaForType
Use this method if you want to migrate expressions added to a single object type (or
the type’s properties) using an ALTER TYPE or if you want to migrate expressions
defined while creating a new type using CREATE TYPE.
Arguments for both methods let you select which Docbasic expressions to migrate to
Java code. You can choose to compile only new Docbasic expressions, or those that failed
compilation previously, or all expressions within the scope of the method.
The methods are executed using either a DFC script or using a DO_METHOD
administration method. The DO_METHOD syntax is:
dmAPIGet("apply,session,NULL,DO_METHOD,METHOD,S,migration_method_
name,SAVE_RESULTS,B,T,ARGUMENTS,S,argument_list
migration_method_name is either dmc_MigrateDbExprsToJava or dmc_

MigrateDbExprsToJavaForType.
Use a space to separate arguments in argument_list.Table 100, page 411, lists the valid
arguments for argument_list. .
Table 100. Arguments for the Docbasic expression migration methods
‑docbase docbase_name Name of the repository that contains the expressions you
want to migrate. This must a 5.3 (or later) repository.
‑user user_name Name of a user who has at least Sysadmin privileges in the
specified repository.
‑ticket login_ticket String containing a login ticket.
Note: For information about login tickets and generating
those tickets, refer to the Content Server Administration
Guide.
‑select selection_choice Identifies which expressions you wish to migrate.
selection_choice is one of:
• new_only, includes only new expressions, that is, those
for which migration has not been previously attempted
• new_and_failed, includes all new expressions and
those for which migration previously failed
• new_and_disabled, includes all new expressions and
those that do not have a corresponding enabled Java
version
• all, includes all expressionsAny existing Java code
is replaced if currently migrated expressions are
recompiled.
For dmc_MigrateDbExprsToJava, expressions for

all object types are considered for inclusion. For
dmc_MigrateDbExprsToJavaForType, only expressions
defined for the object type identified in the type argument
are considered for inclusion.
‑maxerrs value Maximum number of errors that can occur before code
generation stops. By default, there is no maximum.
Setting this argument is recommended only if there are

large numbers of expressions to compile.
‑listExprsOnly value Whether to actually perform the migration or only create
a file that records the expressions selected for migration.
Setting value to true directs the method to only create
the file. Setting the value to false directs the method to
migrate the expressions.
If you set this argument to true, you must include

the SAVE_RESULTS argument in the DO_M,ETHOD
command line.
‑type type_name Name of the object type. Include this argument only if you
are executing the dmc_MigrateDbExprsToJavaForType
method. Use the type’s internal name; for example:
dm_document.
It is strongly recommended that you include the SAVE_RESULTS argument on the
DO_METHOD command line regardless of the ‑listExprsOnly setting. The content of
the generated results document varies depending on the circumstances of the method’s
execution:
• If ‑listExprsOnly is set to true, the results document contains a list of all expressions
selected for migration.
• If ‑listExprsOnly is false and non‑fatal errors occur during migration, the results
document contains the errors.
• If ‑listExprsOnly is false and fatal errors occur during migration, the results
document contains the exception stack trace embedded in the HTML error message.
• If ‑listExprsOnly is false and no errors occur during migration, the results document
contains only the text “There were no errors.”
Both methods return 0 unless a fatal error occurred during execution. If a fatal error
occurs, the methods return 1. Fatal errors are reported using the standard method
server mechanism.
Disabling or reenabling Java evaluation

It is possible to disable Java evaluation of a particular Docbasic expression. If you disable
Java evaluation of an expression, the Docbasic library is used to evaluate the expression,
rather than the compiled Java code.
To disable Java evaluation, execute the dmc_SetJavaExprEnabled method. This method
has an argument that turns evaluation of a specified expression on or off. The method
is executed by a DFC script or a DO_METHOD administration method. Here is the
syntax for the DO_METHOD call:
apply,session,NULL,DO_METHOD,METHOD,S,dmc_SetJavaExprEnabled,SAVE_
RESULTS,B,T,ARGUMENTS,S,argument_list
Table 101, page 413, lists the arguments for dmc_SetJavaExprEnabled. All arguments for
this method are required. Use a space to separate arguments in argument_list.
Table 101. dmc_SetJavaExprEnabled arguments
‑docbase repository_ Name of the repository that contains the Java expression
name implementation you want to disable or re‑enable.
‑user user_name Name of the user performing the operation. Use the user’s
login name. The user must have at least Sysadmin privileges
in the repository.
‑ticket login_ticket A string containing a login ticket generated for the specified
user.
‑func_expr_id Object ID of the dm_func_expr object representing the
func_expr_obj_id Docbasic expression
‑enable value Set this to true to enable the Java evaluation of the Docbasic
expression identified in the ‑func_expr_id argument. Or, set
it to false, to disable Java evaluation of that expression.
Docbasic expression components support

This section lists and briefly describes the Docbasic components, such as operators,
functions, and constants, that are supported for Java migration.
Operators
Table 102, page 414, lists the Docbasic operators for which Java evaluation is supported.
Table 102. Docbasic operators supported by Java evaluation
Operator Operation performed

& String concatenation
* Multiplication
+ Addition or concatenation
– Subtraction
/ Floating point division
< Comparison (less than)
<= Comparison (less than or equal to)
<> Comparison (not equal to)
= Comparison (equal to)
> Comparison (greater than)
>= Comparison (greater than or equal to)
\ Integer division
^ Exponentiation
And Logical or binary conjunction
Eqv Logical or binary equivalence (not Xor)
Imp Logical or binary implication
Is Compares two operands and returns true if they refer to the
same object; otherwise, returns false.
Because objects are not supported, using this operator always

results in a type mismatch error at runtime.
Like Compares two strings and returns true if the expression
matches the given pattern; otherwise, returns false.
Mod Returns the remainder of the expression_1/expression_2 as
whole number
Not Returns either a logical or binary negation of an expression
Or Logical or binary disjunction on two expressions
Xor Exclusive Or operation
Supported functions for Java evaluation

Table 103, page 415, lists the Docbasic functions for which Java evaluation is supported.
Table 103. Docbasic functions supported for Java evaluation
Function Description
abs(expr) Returns the absolute value of expr
Asc(text$) Returns the integer containing the numeric code for the
first character of the text$ (0–255)
AscB or AscW Returns the byte or wide‑character equivalents of Asc
Atn(number) Returns the inverse tangent of number
CBool(expr) Converts the expr to a Boolean
CDate(expr) or Converts the expr to a Date
CVDate(expr)
Note: If expr is a string, it is expected that the date is in
canonical form unless a specific date format string was
passed to the validation method.
CDbl(expr) Converts expr to a Double
Choose(index, expr1, Returns the expression whose position in the list of expr
expr2,...exprN) arguments matches the value specified index. If none is
found, returns null.
Chr(code) or Chr$(code) Returns the character whose value is code
The Java implementation returns a String variant in both

functions.
CInt(expr) Converts expr to a Docbasic integer.
The Java implementation converts expr to a Java short.

CLng(expr) Converts expr to a Docbasic long
The Java implementation converts expr to a Java int.

Cos(angle) Returns the cosine of angle where angle is assumed to be
expressed in radians
CSng(expr) Converts expr to a Docbasic Single
The Java implementation converts expr to a Java float.

CStr(expr) Converts expr to a String
CVar(expr) Converts expr to a Variant
Date Returns the current date as a Date Variant
Date$ Returns the current date as a String
The Java implementation will always be in canonical form

or in the format passed to the validation method.
DateAdd(interval$, Increments the date field identified in interval$ of the
increment&, date) given date by the amount specified in interval&
DateDiff(interval$, date1, Returns a Date variant representing the number of given
date2) time intervals between date1 and date2
DatePart(interval$, date) Returns an Integer representing a specific part of a
date/time expression
DateSerial(year, nonth, Returns a Date variant representing the specified date
day)
DateValue(dateString$) Returns a Date variant representing the date specified by
dateString$
Day(date) Returns the day of the month represented by date
Exp(val) Returns the value of e raised to the power of val
Fix(number) Returns the integer part of number
Format or Format$(expr, Returns a string formatted to user specification (supports
userFormat) both named and unnamed formats)
Hex[$](number) Returns a String containing the hexadecimal equivalent
of number
Hour(time) Returns the hour of the day encoded in time
If(condition, Returns TrueExpression if condition is true; otherwise,
TrueExpression, returns FalseExpression
FalseExpression)
InStr([start,] search, find Returns the first character position of string “find” within
[,compare]) string “search”
InStrB([start,] search, find Returns the first character position of string “find” within
[,compare]) string “search”
Int(number) Returns the integer part of number
IsDate(expr) Returns true if expr can be legally converted to a date;
otherwise, returns false
IsNull(expr) Returns true if expr is a Variant variable that contains no
valid data; otherwise, returns false
IsNumeric(expr) Returns true if expr can be converted to a number;
otherwise, returns false
Item$(text$, first, last Returns all items between first and last within the
[,delimiters$]) specified formatted text list
ItemCount(text$ Returns an integer containing the number of items in the
[,delimiters$]) specified delimited list
LBound(arrayVar Returns an integer containing the lower bound of the
[,dimension]) specified dimension of the specified array variable
LCase[$](text) Returns the lowercase equivalent of text
Left[$](text, nChars) or Returns the leftmost nChars characters (Left and Left$)
LeftB[$](text, nChars) or bytes (LeftB and LeftB$) from text
Note: Use LeftB with caution. Multibyte characters can
be split in the middle, resulting in the construction of
illegal strings.
Len(expr or lenB(expr) Returns the number of characters in expr or the number
of bytes required to store expr
Line$(text$, first [,last]) Returns a string containing a single line or a group of
lines between first and last
LineCount(text$) Returns an integer representing the number of lines in
text$
Log(number) Returns a double representing the natural logarithm of
number
LTrim[$](text) Returns text with the leading spaces removed
Mid[$](text, start [,length]) Returns a substring of the specified text, beginning with
or MidB[$](text, start start for length number of characters or bytes
[,length])
Note: Use MidB with caution. Multibyte characters can
be split in the middle, resulting in the construction of
illegal strings.
Minute(time) Returns the minute of the day encoded in the time
argument
Month(date) Returns the month of the date
Now Returns a date variant representing the current date and
time
Oct(number) or Returns a string containing the octal equivalent of the
Oct$(number) specified number
Random(min,max) Returns a long value greater than or equal to min and less
than or equal to max
Right[$](text,nChars) or Returns the rightmost nChars characters or bytes from
RightB[$](text,nChars) the text.
RightB and RightB$ are used to return byte data from

strings containing byte data.
Note: Use RightB with caution. Multibyte characters
can be split in the middle, resulting in the construction
of illegal strings.
Rnd[(number)] Returns a random Single number between 0 and 1
RTrim[$](text) Returns text with the trailing spaces removed
Second(time) Returns the second of the day encoded in the time
argument
Sgn(number) Returns an integer indicating whether a number is less
than, greater than, or equal to 0
Sin(angle) Returns a double value specifying the sine of angle
Space[$](NumSpaces) Returns a string containing the specified number of spaces
Sqr(number) Returns a double representing the square root of number
Str[$](number) Returns a string representation of number
StrComp(string1, string2 Returns an integer indicating the result of comparing
[,compare]) string1 and string2
String[$](number, Returns a string of length number consisting of a
[CharCode | text$]) repetition of the specified filler character
Swith(condition1, expr1 Returns the expression corresponding to the first true
[,condition2,expr2... condition.
[condition7,expr7]])
Tan(angle) Returns a double representing the tangent of angle
Time/Time$ Returns the system time as a string or as a Date variant
In the Java implementation, the time is in canonical form..

Timer Returns a Single representing the number of seconds that
have elapsed since midnight
TimeSerial(hour, minute, Returns a Date variant representing the given time with a
second) date of zero
TimeValue(time_string$) Returns a date variant representing the time contained
in time_string$
The date must be in canonical form or in a format that

conforms to the format string passed to the validation
method.
Trim[$](text) Returns a copy of text with leading and trailing spaces
removed
TypeName(varname) Returns the type name of the specified variable
UBound(arrayVar Returns an integer containing the upper bound of the
[,dimension]) specified dimension of the specified array variable
UCase[$](text) Returns the uppercase equivalent of the specified string
Val(numberString) Converts a given string expression to a number
Vartype(variable) Returns an integer representing the type of data in
variable
Weekday(date) Returns an integer value representing the day of the week
given by date
Sunday is 1, Monday is 2, and so forth.

Word$(text$, first [,last]) Returns a string containing a single word or sequence of
words between first and last
WordCount(text$) Returns an integer representing the number of words in
text$
Year(date) Returns the year of the date encoded in the date argument
The value returned is between 100 and 9999, inclusive.
Unsupported functions for Java evaluation

The functions listed in Table 104, page 419 are not supported for Java evaluation. For
detailed information about these functions, refer to the Docbasic documentation.
Table 104. Docbasic functions not supported for Java evaluation
Names of unsupported functions

CCur(expr) EOF GetSession Pmt(Rate, NPer, Pv,
Fv, Due)
Names of unsupported functions

Clipboard$ Erl GetSetting([app‑ PPmt(rate, Per,
name], section, Nper, Pv, Fv, Due)
key[, default])
Command or Err Input, Input$, PrinterGetOrienta‑
Command$ InputB, and tion
InputB$(...)
CreateObject(Clas‑ Error and InputBox and PrintFile(file‑
sID) Error$(errNum) InputBox$ name$)
CurDir and Exter‑ IPmt(Rate, Per, Pv(reate, NPer,
CurDir$(drive) nal(pathOrObjID) Nper, Pv, Fv, Due) Pmt, Fv, Due)
CVErr FileAttr(fileNum, IRR(ValueArray(), Rate(NPer, Pmt, Pv,
attr) Guess) Fv, Due, Guess)
DDB(Cosot, FileDateTime(file‑ IsError(expr) ReadIni$(section$,
Salvage, Life, name) item$[, filename$])
Period)
DDEInitiate(appli‑ FileExists(filename) IsMissing(variable) SaveFilename$[([ti‑
cation$, topic$) tle$[, exten‑
sions$]])]
DDERequest[$](chan‑ FileLen(filename) Loc(filenumber) Seek(filenumber)
nel, DataItem$)
Dir[$][(file‑ FileParse(filename, Lof(filenumber) SetAppInfo(sec‑
spec$[,properties])] op) tion$, entry$,
string$, filename$)
Disk‑ FileType(filename) MacID(text$) Shell(command$[,
Free&([drive$]) WindowStyle])
dmAPIExec FreeFile MIRR(valArray, ShellSync(com‑
rate, reinvestRate) mand)
dmAPIGet Fv(Rate, Nper, Pmt, MsgBox(msg) Spc(numspaces)
Pv, Due)
dmAPISet GetAppInfo(sec‑ NPer(rate, Pmt, Pv, SYD(cost, salvage,
tion$, entry$, file‑ Fv, Due) life, period)
name$)
dmExit GetAttr(filename$ Npv(rate, valArray) Tab(column)
[,class$])
Environ or GetOption(name$ | OpenFile‑ TypeOf<objectVar>
Environ$(varName id) name$([([title$[, Is ObjectType
| varNum) extensions$]])]
Supported constants
Table 105, page 421, lists the Docbasic constants that are supported for Java evaluation.
Table 105. Docbasic constants supported for Java evaluation
Constant Description
ebBoolean Integer representing Boolean datatype
ebCurrency Integer representing Currency type
ebDataObject Integer representing a data object
ebDate Integer representing a Date type
ebEmpty Integer representing an Empty variant
ebError Integer representing an Error variant
ebInteger Integer representing the Integer type
ebLong Integer representing the Long type
ebNull Integer representing Null variant type
ebObject Integer representing the OLE automation object type
ebSingle Integer representing the Single type
ebString Integer representing the String type
ebVariant Integer representing the Variant type
Empty Constant representing an initialized variant
False Boolean constant
Nothing Null Object reference
Null Explicit Docbasic value distinguishable from Empty or
Nothing. (Refer to the Docbasic documentation for complete
information.)
Pi Value of Pi
True Boolean constant
Unsupported constants
Table 106, page 422, lists the constants that are not supported for Java evaluation.
Table 106. Constants not supported for Java evaluation
Constant names
ebCancel ebNone ebSystem
ebCritical ebNormal ebSystemModal
ebHidden ebReadOnly ebVolume
Implicit objects
The implicit objects provided by Docbasic, such as the implicit object named Basic, are
not supported for use in expressions that are compiled for Java evaluation.
Appendix C
DQL Quick Reference
This appendix contains only the formal syntax descriptions of the DQL statements and the DQL
reserved words. For a full description of each statement, refer to Chapter 2, DQL Statements.
The DQL statements

This section contains the formal syntax for each of the DQL statements.
Abort
ABORT [TRAN[SACTION]]
Alter Aspect
ALTER ASPECT aspect_name ADD
[[NO]OPTIMIZEFETCH]
ALTER ASPECT aspect_name ADD_FTINDEX ALL
ALTER ASPECT aspect_name DROP_FTINDEX ALL
ALTER ASPECT aspect_name ADD_FTINDEX property_list
ALTER ASPECT aspect_name DROP_FTINDEX property_list
Alter Group
ALTER GROUP group_name ADD members
DQL Quick Reference
ALTER GROUP group_name DROP members

ALTER GROUP group_name SET ADDRESS email_address
Alter Type
type_modifier_list [PUBLISH]
MODIFY (property_modifier_clause)[PUBLISH]
ADD property_def {,property_def}[PUBLISH]
DROP property_name {,property_name}[PUBLISH]
ALTER TYPE type_name ALLOW ASPECTS
ADD|SET|REMOVE DEFAULT ASPECTS aspect_list
ALTER TYPE type_name ENABLE PARTITION
ALTER TYPE type_name SHAREABLE [PUBLISH]
Begin Tran
BEGIN TRAN[SACTION]
Change...Object
CHANGE current_type OBJECT[S] TO new_type[update_list]
[IN ASSEMBLY document_id [VERSION version_label] [DESCEND]]
Commit
COMMIT [TRAN[SACTION]]
DQL Quick Reference
Create Group
CREATE GROUP group_name [WITH] [ADDRESS mail_address]
[MEMBERS member_list]
Create...Object
CREATE type_name OBJECT update_list
Create Type
CREATE TYPE type_name [(property_def {,property_def})]
[WITH] SUPERTYPE parent_type
To create a partitionable type:

CREATE PARTITIONABLE TYPE type_name
[WITH] SUPERTYPE NULL
To create a shareable type:

CREATE SHAREABLE TYPE type_name
[WITH] SUPERTYPE parent_type [PUBLISH]
To create a lightweight type:

CREATE LIGHTWEIGHT TYPE type_name
SHARES shareable_type
[AUTO MATERIALIZATION |
MATERIALIZATION ON REQUEST |
DISALLOW MATERIALIZATION]
[FULLTEXT SUPPORT NONE |
FULLTEXT SUPPORT |
FULLTEXT SUPPORT LITE | BASE [ADD attribute_list | ALL]
]
[PUBLISH]
Delete
DELETE FROM table_name WHERE qualification
DQL Quick Reference
Delete...Object
DELETE [PUBLIC]type_name[(ALL)]
[correlation_variable]
[WITHIN PARTITION (partition_id {,partition_id})
OBJECT[S]
Drop Group
DROP GROUP group_name
Drop Type
DROP TYPE type_name
Execute
EXECUTE admin_method_name [[FOR] object_id]
[WITH argument = value {,argument = value}]
Grant
GRANT privilege {,privilege} TO users
Insert
INSERT INTO table_name [(column_name {,column_name})]
VALUES (value {,value}) | dql_subselect
Register
REGISTER TABLE [owner_name.]table_name (column_def {,column_def})
DQL Quick Reference
[[WITH] KEY {column_list)]

[SYNONYM [FOR] 'table_identification']
Revoke
REVOKE privilege {,privilege} FROM users
Select
The syntax for a standard query is:
[WITHIN PARTITION (partition_id{,partition_id})
| IN DOCUMENT clause
| IN ASSEMBLY clause]
[SEARCH [FIRST|LAST]fulltext_search_condition
[GROUP BY value_list]
[HAVING qualification]
[UNION dql_subselect]
[ORDER BY value_list]
where the IN DOCUMENT clause is:

IN DOCUMENT object_id [VERSION version_label]
[DESCEND][USING ASSEMBLIES]
[WITH binding condition]
[NODESORT BY property {,property} [ASC|DESC]]
and the IN ASSEMBLY clause is:

IN ASSEMBLY object_id [VERSION version_label]
[NODE component_id][DESCEND]
The syntax for an FTDQL SELECT statement is:

[SEARCH fulltext_search_condition
[ORDER BY SCORE]
Table 107, page 428, lists the constraints imposed on the clauses in an FTDQL query.
DQL Quick Reference
Table 107. Summary of FTDQL query rules
Applicable to Rule
FTDQL queries in general An FTDQL query must contain one of the following:
• SEARCH clause
• One of: SCORE, SUMMARY, or TEXT as a selected
value
• ENABLE(FTDQL)
The query may not contain:

• An IN DOCUMENT or IN ASSEMBLY clause
• The FIRST or LAST keyword in a SEARCH clause
• A UNION, GROUP BY, or HAVING clause
selected values list The selected values list must satisfy the following
rules:
• Only the following keywords are acceptable:
CONTENTID, ISCURRENT, OBJTYPE,
SCORE, SUMMARY, SYSOBJ_ID, TEXT, and
THUMBNAIL_URL
• Literals or expressions of any type may not be
included.
• An asterisk (*) is not allowed.
AS clause The AS clause is acceptable with no restrictions.
FROM clause The following rules apply to the FROM clause:
• You may include only one object type reference,
and that reference must be to dm_sysobject or a
SysObject subtype.
• You may not include references to a registered table.
SEARCH clause The SEARCH clause may not reference the FIRST
or LAST keyword. There are no restrictions on the
full‑text search condition. However, note that the
SEARCH DOCUMENT CONTAINS syntax is the
preferred way to specify a SEARCH clause.
DQL Quick Reference
Applicable to Rule
WHERE clause A WHERE clause in an FTDQL query is subject to the
following rules:
• Any repeating properties referenced in the clause
must be of type string or ID.
• Only the DQL UPPER and LOWER functions are
allowed. The functions SUBSTR, MFILE_URL, and
all aggregate functions are not acceptable.
• The following predicates are not allowed:
— BETWEEN
— NOT LIKE
— NOT FOLDER
— [NOT] CABINET
— ONLY
— TYPE
• The IN and EXISTS keywords are not allowed.
• Any valid form of the FOLDER predicate (except
NOT FOLDER) may be used. The DESCEND
option is also allowed.
• The following rules apply to the LIKE predicate:
— The LIKE predicate may be used with pattern
matching characters.
— The LIKE predicate may not be used with an
escape clause.
• The keywords TODAY, YESTERDAY, TOMORROW
may not be used in the DATE function.
• The following rules apply to all expressions in the
WHERE clause:
— Expressions may not contain the ISREPLICA or
USER keywords.
— Expressions may use any comparison operator.
— Expressions may use an arithmetic operator,
but they may not be used to form a compound
expression.
— Expressions that compare one property to another
are not allowed. For example, subject=title is
invalid.
— Expressions in the following format are not
allowed:
DQL Quick Reference
Applicable to Rule
property_name operator('literal' operator

'literal)
— Expressions that force index correspondence
between repeating properties are not allowed.
Such expressions AND together expressions that
reference repeating properties in the format:
predicate(repeating_attr_expr AND
repeating_attr_expr)
(For more information about forcing index
correspondence, refer to Forcing index
correspondence in query results, page 385.)
• The following additional rules apply to
expressions in the format first_expression operator
second_expression
— The first_expression is limited to one of the
following:
property name upper(property name)
lower(property name)
— The second_expression is limited to one of the
following:
literal value upper(literal value)
lower(literal value) the DATE() function
— The operator may be any valid operator.
ORDER BY clause If included, this clause must be:

ORDER BY SCORE
SCORE must be referenced by name, not position, in

the selected values list, also.
ENABLE clause There are no restrictions on this clause.
Unregister
UNREGISTER [TABLE] [owner_name.]table_name
DQL Quick Reference
Update
UPDATE table_name SET column_assignments
WHERE qualification
Update...Object
UPDATE [PUBLIC]type_name [(ALL)][correlation_var]
[WITHIN PARTITION partition_id {,partition_id}]
OBJECT[S] update_list
DQL reserved words

If you using DQL reserved words as object or property names, enclose name in double
quotes when using in a DQL query.
Table 108. DQL reserved words
Initial letter Reserved words

A
ABORT ALTER ASSEMBLIES
ACL AND ASSEMBLY
ADD ANY ASSISTANCE
ADD_FTINDEX APPEND ATTR
ADDRESS APPLICATION AUTO
ALL AS AVG
ALLOW ASC
B
BAG BOOL BUSINESS
BEGIN BOOLEAN BY
BETWEEN BROWSE
DQL Quick Reference

C
CABINET COMMENT CONTAINS
CACHING COMMIT CONTENT_
FORMAT
CHANGE COMPLETE CONTENT_ID
CHARACTER COMPONENTS COUNT
CHARACTERS COMPOSITE CREATE
CHAR COMPUTED CURRENT
CHECK CONTAIN_ID
D
DATE DELETED DISTINCT
DATEADD DEPENDENCY DM_SESSION_DD_
LOCALE
DATEDIFF DEPTH DOCBASIC
DATEFLOOR DESC DOCUMENT
DATETOSTRING DESCEND DOUBLE
DAY DISABLE DROP
DEFAULT DISALLOW DROP_FTINDEX
DELETE DISPLAY
E
ELSE ENFORCE EXEC
ELSEIF ESCAPE EXECUTE
ENABLE ESTIMATE EXISTS
F
FALSE FOR FT_OPTIMIZER
FIRST FOREIGN FULLTEXT
FLOAT FROM FUNCTION
FOLDER FTINDEX
G
GRANT GROUP
DQL Quick Reference

H
HAVING HITS
I
ID INT IS
IF INTEGER ISCURRENT
IN INTERNAL ISPUBLIC
INSERT INTO ISREPLICA
K
KEY
L
LANGUAGE LIGHTWEIGHT LIST
LAST LIKE LITE
LATEST LINK LOWER
M
MAPPING MEMBERS MONTH
MATERIALIZE MFILE_URL MOVE
MATERIALIZA‑ MHITS MSCORE
TION
MAX MIN
MCONTENTID MODIFY
N
NODE NOTE NULLINT
NODESORT NOW NULLSTRING
NONE NULL
NOT NULLDATE
O
OF ON ORDER
OBJECT ONLY OWNER
OBJECTS OR
DQL Quick Reference

P
PAGE_NO PERMIT PRIVATE
PARENT POLICY PRIVILEGES
PARTITION POSITION PROPERTY
PATH PRIMARY PUBLIC
Q
QRY QUALIFIABLE
R
RDBMS RELATE REPORT
READ REMOVE REQUEST
REFERENCES REPEATING REVOKE
REGISTER REPLACEIF
S
SCORE SMALLINT SUPERTYPE
SEARCH SOME SUPERUSER
SELECT STATE SUPPORT
SEPARATOR STORAGE SYNONYM
SERVER STRING SYSADMIN
SET SUBSTR SYSOBJ_ID
SETFILE SUBSTRING SYSTEM
SHAREABLE SUM
SHARES SUMMARY
T
TABLE TODAY TRUE
TAG TOMORROW TRUNCATE
TEXT TOPIC TYPE
TIME TRAN
TO TRANSACTION
DQL Quick Reference

U
UNION UNREGISTER UPDATE
UNIQUE USER UPPER
UNLINK USING
V
VALUE VERSION VIOLATION
VALUES VERITY
W
WHERE WITHOUT WEEK
WITH WORLD
WITHIN WRITE
Y
YEAR YESTERDAY
DQL Quick Reference
Appendix D
Document Query Language Examples
This appendix contains examples of Document Query Language (DQL) SELECT statements. The
examples begin with basic SELECT statements that retrieve information about objects using the
standard SELECT clauses, such as the WHERE clause and GROUP BY clause. Then the examples
show SELECT statements that make use of the DQL extensions to the statement, such as the ability
to use folder and virtual document containment information or registered tables to retrieve object
information.
This appendix does not attempt to describe the syntax of the DQL SELECT statement in detail. For a
complete description of SELECT, refer to Select, page 130.
Basic examples
This section presents basic SELECT statements. These examples demonstrate the use
of standard clauses such as the WHERE, GROUP BY, and HAVING clauses, as well as
how to use aggregate functions in a query. Some of these examples also demonstrate
how to query repeating properties.
The simplest format

The basic SELECT statement has the format:
SELECT target_list FROM type_name
The target_list identifies the value or values that you want to retrieve and type_name
identifies the types or registered tables from which you want to retrieve the requested
information.
The following example returns the user names of all the users in the repository:
SELECT "user_name" FROM "dm_user"
This next example returns the names of the users and their user privileges within a
repository:
SELECT "user_name","user_privileges" FROM "dm_user"
Using the WHERE clause

The WHERE clause restricts the information retrieved by placing a qualification on
the query. Only the information that meets the criteria specified in the qualification is
returned. The qualification can be simple or complex. It can contain any of the valid
predicates or logical operators, such as AND, OR, or NOT.
The following example returns the user names of all users that belong to a specified
group:
SELECT "user_name" FROM "dm_user"
WHERE "user_group_name"='engr'
The next example retrieves all the types that do not have SysObject as their direct
supertype and have more than 15 properties:
SELECT "name" FROM "dm_type"
WHERE "super_name" != 'dm_sysobject'
AND "attr_count" > 15
Searching repeating properties in a WHERE Clause
To search a repeating property for a specific value, you use the ANY predicate in the
WHERE clause qualification unless you have included the ROW_BASED hint in the
query. When you use this predicate, or if the query includes ROW_BASED, if any of the
values in the specified repeating property meets the search criteria, the server returns
the object.
The following example searches the authors property to return any document that has
Jim as one of its authors:
WHERE ANY "authors" = 'jim'
This next example searches the authors property and returns any document that has
either Jim or Kendall as an author:
WHERE ANY "authors" IN ('jim', 'kendall')
The following example searches the keywords property and returns any document
that has a key word that begins with hap:
WHERE ANY "keywords" LIKE 'hap%'
Using aggregate functions

DQL recognizes several aggregate functions. Aggregate functions are functions that
operate on a set and return one value. For example, the count function is an aggregate
function. It counts some number of objects and returns the total. (For a full description
of all the aggregate functions that you can use in DQL queries, refer to Aggregate
functions, page 23.)
This example counts the number of documents owned by the user named john:
WHERE "owner_name"='john'
The following example returns the dates of the oldest and newest documents in the
repository:
SELECT MIN(DISTINCT "r_creation_date"),MAX(DISTINCT "r_creation_date")
FROM "dm_document"
This final example returns the average number of properties in Documentum types:
SELECT AVG(DISTINCT "attr_count") FROM "dm_type"
Using the GROUP BY clause
The GROUP BY clause provides a way to sort the returned objects on some property and
return an aggregate value for each sorted subgroup. The basic format of the SELECT
statement when you want to use the GROUP BY clause is:
SELECT property_name,aggregate_function FROM type_name
GROUP BY property_name
The property named in the target list must be the same as the property named in the
GROUP BY clause.
The following example retrieves the names of all document owners and for each,
provides a count of the number of documents that person owns:
SELECT "owner_name",count(*) FROM "dm_document"
Using the HAVING clause
The HAVING clause is used in conjunction with the GROUP BY clause. It restricts which
groups are returned.
The following example returns the owner names and a count of their documents for
those owners who have more than 10 documents:
HAVING COUNT(*) > 10
The ORDER BY clause

The ORDER BY clause lets you sort the values returned by the query. The clause has
the format:
ORDER BY num [ASC|DESC] {,num [ASC|DESC] }
or
ORDER BY property [ASC|DESC] {,property [ASC|DESC]}
The num identifies one of the selected values by its position in the selected values list.
The property identifies one of the selected values by its name. ASC (ascending) and
DESC (descending) define the order of the sort and must be specified for each element
specified in the ORDER BY clause.
The following example returns the owner’s name, the object’s title, and its subject for
all SysObjects. The results are sorted by the owner’s name and, within each owner’s
name group, by title:
SELECT "owner_name","title","subject" FROM "dm_sysobject"
ORDER BY "owner_name", "title"
This next example returns the owner names and a count of their documents for those
owners who have more than 10 documents. The results are ordered by the count, in
descending order.
GROUP BY "owner_name" HAVING COUNT(*) < 10
ORDER BY 2 DESC
Using the asterisk (*) in queries

DQL lets you use the asterisk in the target list. If the query does not include the
ROW_BASED hint and the asterisk is the selected value, the FROM clause may specify
only a type name or a registered table—it cannot specify both. If the query includes
the ROW_BASED hint, the FROM clause may include either or both object types and
registered tables. The values returned by the asterisk depend on what is specified in
the FROM clause and whether the ROW_BASED hint is included. For examples and
complete details, refer to The asterisk (*) as a selected value, page 148.
Searching cabinets and folders

In Documentum, objects of all SysObject subtypes except cabinets are stored in cabinets,
and sometimes, in folders within those cabinets. It may, at times, be advantageous to
restrict the search for an object or objects to a particular cabinet or folder. Or, you may
want to determine what a particular cabinet or folder contains. To make these operations
possible, DQL provides the CABINET and FOLDER predicates for use with the WHERE
clause. The CABINET predicate lets you specify a particular cabinet to search. The
FOLDER predicate lets you specify a particular folder or cabinet to search. (You can use
the FOLDER predicate for cabinets as well as folders because cabinets are subtypes of
folders.)
Use the cabinet or folder’s folder path or its object ID to identify it in the query. A folder
path has the format:
/cabinet_name{/folder_name}
To use the object ID, you must use the ID function and the object ID. The following
examples illustrate the use of both folder paths and object IDs with the CABINET and
FOLDER predicates.
This example returns all the folders contained in Research folder, which is identified
by its object ID:
SELECT "object_name" FROM "dm_folder"
WHERE FOLDER (ID('0c00048400001599'))
The next example returns all the objects in the Marketing cabinet sorted by their type
and, within each type, ordered alphabetically. The Marketing cabinet is identified by
its folder path.
SELECT "object_name","r_object_type" FROM "dm_sysobject"
WHERE CABINET ('/Marketing')
ORDER BY "r_object_type","object_name"
This final example returns all the objects in the Correspondence folder in the Marketing
cabinet. Again, the objects are sorted by their type and ordered alphabetically within
each type group. A folder path is used to identify the correct folder.
SELECT "object_name","r_object_type" FROM "dm_sysobject"
WHERE FOLDER ('/Marketing/Correspondence')
ORDER BY "r_object_type","object_name"
The CABINET and FOLDER predicates have an optional keyword, DESCEND, that
directs the server to return not only those objects directly contained within a cabinet or
folder but to also return the contents of any folders contained in that folder or cabinet,
and so forth. (There is a limit of 25,000 contained folders within the specified folder
when you include DESCEND in the predicate.)
The following example returns the name, object ID, and type of all objects in the
Clippings folder, including the contents of any folders that are contained by the
Clippings folder. The Clippings folder resides in the Marketing cabinet.
SELECT "object_name","r_object_id","r_object_type"
FROM "dm_sysobject"
WHERE FOLDER ('/Marketing/Clippings', DESCEND)
Querying registered tables

A registered table is a table from your underlying RDBMS that has been registered with
the repository. This registration allows you to specify the table in a DQL query, either by
itself or in conjunction with a type. The following examples illustrate each possibility.
(For a full discussion of the rules concerning the use of registered tables in SELECT
statements, refer to Chapter 2, DQL Statements.)
The first example returns all the name of all products and their owners from the
registered table named ownership:
SELECT "product","manager" FROM "ownership"
This second example joins the registered table called ownership to the user‑defined type
called product_info to return the names of all the objects in Collateral folder, along with
the names of the managers who own the products described by the objects:
SELECT p."object_name", o."manager"
FROM "product_info" p, "ownership" o
WHERE p."product" = o."product" AND
FOLDER ('/Marketing/Collateral', DESCEND)
Querying virtual documents

DQL provides a clause that facilitates querying virtual documents. The clause is the IN
DOCUMENT clause. The IN DOCUMENT clause lets you search a particular virtual
document.
The examples in this section are based on the virtual document shown in Figure 4,
page 443:
Figure 4. Virtual document model
Determining the components

The following example returns only the directly contained components of Book1:
IN DOCUMENT ID('Book1_object_id')
This query returns Book1, Chapter 1, and Chapter 2. Book1 is included because a virtual
document is always considered to be a component of itself.
To return all the components of a virtual document, including those that are contained in
its components, you use the keyword DESCEND. For example:
IN DOCUMENT ID('Book1_object_id') DESCEND
The above example returns Book1, Chapter 1, Doc 1, Doc2, Chapter 2, and Doc 3, in
that order.
Note: The components of a virtual document are returned in a pre‑determined order
that you cannot override with an ORDER BY clause.
You can limit the search to a particular object type by specifying the type in the FROM
clause. For example, the following statement returns only the documents that make up
Book1 (Doc 1, Doc 2, and Doc 3):
IN DOCUMENT ID('Book1_object_id')
Index
* (asterisk) GET_INBOX, 247

in queries, 440 GET_LAST_SQL, 251
wildcard in search queries, 160 GET_PATH, 253
% (percent sign) GET_SESSION_DD_LOCALE, 255
pattern matching character, 35 HTTP_POST, 257
_ (underbar) IMPORT_REPLICA, 262
pattern matching character, 36 IMPORT_TICKET_KEY, 264
[] (square brackets) for index values, 183 LIST_AUTH_PLUGINS, 266
(*) asterisk LIST_RESOURCES, 268
as selected value, 148 LIST_SESSIONS, 273
ROW_BASED hint, effect of, 148 LIST_TARGETS, 278
LOG_OFF, 280
LOG_ON, 282
A MAKE_INDEX, 284
ABORT (statement), 44 MARK_AS_ARCHIVED, 288
accent marks, in search strings, 159 MARK_FOR_RETRY, 290
access controls for registered tables, 389 MIGRATE_CONTENT, 292
ACLs MODIFY_TRACE, 312
object types, assigning to, 87 MOVE_INDEX, 314
setting default, 60 PING, 316
administration methods PURGE_AUDIT, 318
BATCH_PROMOTE, 194 PURGE_CONTENT, 326
CAN_FETCH, 196 PUSH_CONTENT_ATTRS, 328
CHECK_CACHE_CONFIG, 198 RECOVER_AUTO_TASKS, 331
CHECK_RETENTION_ REGISTER_ASSET, 333
EXPIRED, 201 REINDEX_PARTITIONABLE_
CHECK_SECURITY, 205 TYPE, 335
CLEAN_DELETED_OBJECTS, 208 REORGANIZE_TABLE, 337
CLEAN_LINKS, 210 REPLICATE, 340
DB_STATS, 212 RESET_TICKET_KEY, 343
DELETE_REPLICA, 214 RESTORE_CONTENT, 345
DESTROY_CONTENT, 216 ROLES_FOR_USER, 347
DO_METHOD, 218 scope, 188
DROP_INDEX, 227 SET_APIDEADLOCK, 349
ESTIMATE_SEARCH, 229 SET_CONTENT_ATTRS, 352
EXEC_SQL, 232 SET_OPTIONS, 357
executing SET_STORAGE_STATE, 361
Documentum Administrator, 187 SHOW_SESSIONS, 363
EXECUTE statement, 188 TRANSCODE_CONTENT, 365
EXPORT_TICKET_KEY, 234 UPDATE_STATISTICS, 369
FINISH_INDEX_MOVES, 236 WEBCACHE_PUBLISH, 372
Index
administrative methods removing defaults from object

FIX_LINK_CNT, 238 types, 58
GENERATE_PARTITION_SCHEME_ assemblies
SQL, 239 IN ASSEMBLY clause, 156
GET_FILE_ULR, 245 SELECT statements and, 154
MIGRATE_TO_LITE, 304 asterisk (*)
aggregate functions as selected value, 148
as selected values, 141 in queries, 440
AVG, 24 ROW_BASED hint, effect of, 148
COUNT, 23 wildcard in search queries, 160
examples of use, 439 audit trail entries
MAX, 23 to 24 i_is_archived, setting, 288
MIN, 23 to 24 removing from repository, 318
SUM, 25 auditing
aggregate functions, default values audit trail entries, removing, 318
and, 381 authentication
ALL (keyword), 105, 137 LIST_AUTH_PLUGINS
ALL (predicate), 32 administration method, 266
ALTER ASPECT (statement), 47 LIST_SESSIONS description, 274
ALTER GROUP (statement), 45 tracing, 359
ALTER TYPE (statement), 51 authentication plugins
AND (logical operator), 40 list of, obtaining, 266
ANSI format for dates, 17 automatic activities
ANY keyword in WHERE clauses, 162 RECOVER_AUTO_TASKS
ANY...comparison operator administration method, 331
(predicate), 33 AVG (aggregate function), 24
ANY...IN subquery (predicate), 33
ANY...IS NULL (predicate), 33
ANY...IS NULLDATE (predicate), 33
B
ANY...IS NULLINT (predicate), 33 BATCH_PROMOTE administration
ANY...IS NULLSTRING (predicate), 33 method, 194
ANY...LIKE (predicate), 33 BEGIN TRAN (statement), 70
application server brackets for index values, 183
sending request to, 257
Apply method C
operations, 188 CABINET (predicate), 39
archived documents, restoring, 345 cabinets
archiving CABINET (predicate), 39
audit trail entries, 288 querying (examples of), 441
archiving content files, 326 cache config objects
arithmetic expressions as selected consistency checking, 198
values, 142 cached queries, 390
arithmetic operators, 30 CAN_FETCH
ascending sort order, 167 administration method, 196
aspect properties case sensitivity
modifying, 47 scientific notation, 14
aspects case sensitivity, in search strings, 159
adding defaults to object types, 57 CHANGE OBJECT (statement), 71
adding/dropping properties, 47 CHANGE...OBJECT (statement), 379
Index
character strings tracing information, 358

converting dates to, 27 connections
dates within, 16 checking with PING, 316
dfc.compatibility.truncate_long_ constraints
values preference, 15 check (data validation), 94, 98
lengths, 15 creating with ALTER TYPE, 67
literal formats, 15 creating with CREATE TYPE, 92
lowercase and LOWER function, 21 dropping with property_drop_
pattern arguments, 17 clause, 67
returning substrings, 22 dropping with type drop clause, 63
short date formats, 16 foreign key, 94
uppercase and UPPER function, 21 foreign keys, 97
check constraints, 94, 98 NOT NULL, 94
CHECK_CACHE_CONFIG primary key, 93, 96
(administration method), 198 removing, 63
CHECK_RETENTION_EXPIRED specifying, 62
(administration method), 201 unique key, 93, 97
CHECK_SECURITY (administration CONTAIN_ID (keyword), 144
method), 205 content addressable storage
CLEAN_DELETED_OBJECTS PUSH_CONTENT_ATTRS
administration method, 208 administration method, 328
CLEAN_LINKS content files, 340
administration method, 210 archiving, 326
client applications deleting replicas, 214
checking for server connection, 316 fetching, 196
short date format defaults, 16 importing replicas, 262
client code pages MIGRATE_CONTENT administration
tracing, 358 method, 292
client machines obtaining file path, 253
short date format defaults, 19 removing, 216
tracing information for, 359 removing from content‑addressed
client roles storage, 217
determining, 347 restoring archived, 345
code page requirements transformations, requesting, 365
SYNONYM FOR clause, 127 content objects
columns destroying, 216
defining, 124 SET_CONTENT_ATTRS
inserting values into, 120 administration method, 352
updating, 175 Content Server
comments, in DQL, 43 common area, removing files
COMMIT (statement), 75 from, 358
common area Docbasic expressions, handling
removing files from, 358 of, 407
component specifications history_cutoff startup parameter, 276
dropping, 64 history_sessions startup
removing, 63 parameter, 276
specifying, 63 listing active sessions, 363
component_specification, 99 listing connection broker targets, 278
connection brokers obtaining resource information, 268
obtaining list of targets, 278 obtaining session information, 273
Index
content‑addressed storage OPTIMIZATION_LEVEL, 399

objects with expired retention, OPTIMIZE_TOP, 398
finding, 201 passthrough hints, 405
content‑addressed storage systems RETURN_TOP, 396
content, removing, 217 ROW_BASED, 401
tracing operations in, 358 SQL_DEF_RESULT_SET, 394
CONTENTID (keyword), 143 TRY_FTDQL_FIRST, 403
contents UNCOMMITTED_READ, 400
adding with SETFILE, 181 using, 393
correlation names, 153 datatypes
COUNT (aggregate function), 23 lengthening character string types, 57
CREATE...GROUP (statement), 76 date functions
CREATE...OBJECT (statement), 79 DATEADD, 26
CREATE...TYPE (statement), 83 DATEDIFF, 25
cursors, RDBMS, 213 DATEFLOOR, 27
DATETOSTRING, 27
date literals, 16
D DATEADD (date function), 26
data dictionary DATEDIFF (date function), 25
attribute information, defining, 89 DATEFLOOR (date function), 27
component specification, 99 dates
current locale, obtaining, 255 ANSI format, 17
default values for properties, 380 date literals, 15
defining earliest acceptable year, 16
check constraints, 94, 98 functions, 25
default property values, 92 input formats, 16
foreign key constraints, 94, 97 localized formats, 16
mapping table information, 91 NOW (keyword), 18
NOT NULL constraints, 94 output formats, 18
primary key constraints, 93, 96 short date format defaults, 19
unique key constraints, 93, 97 storage in repository, 19
value assistance information, 90 TODAY (keyword), 18
defining type information, 95 TOMORROW (keyword), 18
Java evaluation of Docbasic truncating, 27
expressions, 407 using in queries, 16
PUBLISH (DQL keyword), 56, 88 YESTERDAY (keyword), 18
update_modifier specification, 89, 95 DATETOSTRING (date function), 27
data partitioning, 59, 88 DB_STATS administration method, 212
data validation, check constraints, 94 DB2
database hints RETURN_TOP, 397
FETCH_ALL_RESULTS, 399 DB2 databases
FORCE_ORDER, 395 OPTIMIZATION_LEVEL (DQL
FT_CONTAIN_FRAGMENT, 403 hint), 399
FT_CONTAIN_WORD, 403 dbo alias, 389
FTDQL and NOFTDQL, 403 deadlocks, simulating, 349
GROUP_LIST_LIMIT DQL hint, 404 debug tracing, 358
HIDE_SHARED_PARENT DQL default aspects
hint, 404 adding to object types, 57
IN and EXISTS, 400 removing from object types, 58
including multiple hints, 405 default values
Index
aggregate functions and, 381 DO_METHOD result object

default property specification, 66 properties, 220
groups for a type, 61 Docbasic, 407
private and public groups, 77 See also Docbasic expression migration
returned format, 380 check constraints, 94, 98
storage area for types, 61 constants
testing for, 380 supported for Java
DELETE (statement), 101, 379 evaluation, 421
DELETE...OBJECT (statement), 103, 379 unsupported for Java
DELETE_REPLICA administration evaluation, 421
method, 214 executing scripts, 218
DEPTH (keyword), 145 expression handling by Content
DESCEND (keyword), 154 Server, 407
descending sort order, 167 expression handling, by DFC Version
DESTROY_CONTENT administration 6, 408
method, 216 expression handling, pre‑6 DFC, 408
DFC (Documentum Foundation Classes) expressions, migrating to Java, 407
Docbasic expression handling, 408 functions
dfc.compatibility.truncate_long_values supported for Java
preference, 15 evaluation, 415
diacritical marks, in search strings, 159 unsupported for Java
digital shredding evaluation, 419
tracing, 358 operators, supported for Java
disabling evaluation, 414
assume_user program, 225 value_assistance_modifier, 90
DISTINCT (keyword), 137 Docbasic expression migration
distributed storage dmc_MigrateDbExprsToJava
deleting replicas, 214 method, 410
fetching content files, 196 dmc_MigrateDbExprsToJavaForType
importing replicas, 262 method, 410
replicating files, 340 implicit objects, 422
dm_bp_batch method, 194 results document, 412
dm_CheckCacheConfig job, 200 supported expression
dm_dbo alias, 389 components, 413
dm_registered object type, 388 Docbasic expressions
DM_SESSION_DD_LOCALE Java evaluation, disabling, 413
(keyword), 20 Docbasic expressions migration
dmc_MigrateDbExprsToJava method, 410 return values, 412
dmc_MigrateDbExprsToJavaForType double quotes, using, 379
method, 410 DQL (Document Query Language)
dmc_SetJavaExprEnabled method, 413 arithmetic operators, 30
DMCL (client library) basic query statements, 378
version number returned by comments, in‑line, 43
LIST_SESSIONS, 274 comparison operators, 31
dmi_audittrail_attrs date functions, 25
SELECT constraint, 151 examples, 437
DO_METHOD administration functions, 20
method, 218 GET_LAST_SQL administration
DO_METHOD procedures method, 251
running as server, 224 ID function, 28
Index
keywords, 19 FINISH_INDEX_MOVES administration

literals, 13 method, 236
logical operators, 39 FIRST keyword, 157
MFILE_URL function, 28 FIX_LINK_CNT administrative
predicates, 30 method, 238
queries, caching, 390 floating point literals, 14
registered tables, referencing, 389 FOLDER (predicate), 38
repeating properties, referencing, 382 nested folder limit, 38
reserved words, 431 folders
tracing generated SQL, 358 FOLDER (predicate), 38
user privileges and, 390 querying (examples of), 441
DQL hints FORCE_ORDER, 395
ROW_BASED, 139 foreign key constraints, 94, 97
using, 168 formats
DROP GROUP (statement), 107 date literals, 16
DROP TYPE (statement), 109 date output, 18
DROP_INDEX administration floating point literals, 14
method, 227 folder path, 38
dump files integer literals, 13
date format in, 19 setting with DATETOSTRING
function, 27
value assistance, 90
E FROM clause
error messages disambiguating types and tables, 152
date formats in, 19 table name specification, 152
escape character, 36 type name specification, 151
ESTIMATE_SEARCH (administration FT_CONTAIN_FRAGMENT DQL
method), 229 hint, 403
EXEC_SQL administration method, 232 FT_CONTAIN_WORD DQL hint, 403
EXECUTE statement FTDQL DQL hint, 403
described, 111 FTDQL queries, see SELECT statement
EXISTS (database hint), 400 distinct_query_results server.ini key
EXISTS (predicate), 32 and, 136
EXPORT_TICKET_KEY administration full‑text indexes
method, 234 MARK_FOR_RETRY administration
expressions method, 290
Java evaluation, disabling, 413 querying, 229
external applications SEARCH clause, 157
deadlocks, simulating, 349 virtual documents and, 388
executing, 218 full‑text indexing
external procedures tracing operations, 312
method objects and, 222 full‑text keywords, 143
functions
F aggregate, 381
Apply method, 188
FALSE (keyword), 20
date, 25
FETCH_ALL_RESULTS, 399
DATEADD, 26
files
DATEDIFF, 25
removing from server common
DATEFLOOR, 27
area, 358
DATETOSTRING, 27
Index
defined, 20 IMPORT_REPLICA administration

EXECUTE statement, 112 method, 262
GROUP BY clause and, 165 IMPORT_TICKET_KEY administration
ID, 28 method, 264
LOWER, 21 IN (database hint), 400
MFILE_URL, 28, 142 IN (predicate), 32
SUBSTR, 22 IN and EXISTS, 400
UPPER, 21 IN ASSEMBLY clause
DELETE...OBJECT and, 106
SELECT and, 156
G unioned selects and, 166
GENERATE_PARTITION_SCHEME_SQL IN DOCUMENT clause
administrative method, 239 described, 153
GET_FILE_URL administrative NODESORT BY option, 155
method, 245 unioned selects and, 166
GET_INBOX administration method, 247 WITH option, 155
GET_LAST_SQL administration IN FTINDEX clause, 160
method, 251 inboxes
GET_PATH administration method, 253 GET_INBOX administration
GET_SESSION_DD_LOCALE method, 247
administration method, 255 index positions
GRANT (statement), 118 defined, 383
GROUP BY clause forcing correspondence, 385
described, 165 indexed properties
examples of use, 439 querying, 158
groups indexes, see object type indexes
alter group (statement), 45 input formats for dates, 16
CHECK_SECURITY (administration INSERT (statement), 120, 379
method), 205 integer literal format, 13
creating, 76 internationalization
default for type, 61 client code pages, tracing, 358
private, 46 object types
public, 46 altering and, 56
removing, 107 creating and, 88
session locales, tracing, 358
H IS NULL (predicate), 31
IS NULLDATE (predicate), 32
HAVING clause
IS NULLINT (predicate), 32
defined, 165
IS NULLSTRING (predicate), 32
examples of use, 440
ISCURRENT (keyword), 143
hierarchy, searching, 154
ISPUBLIC (keyword), 143
history_cutoff (startup parameter), 276
ISREPLICA (keyword), 146
history_sessions (startup parameter), 276
HTTP_POST administration method, 257
J
I Java
evaluation of Docbasic expressions,
i_is_archived property, 288
disabling, 413
ID function, 28
java servlets, invoking, 257
ID literal format, 15
jobs
Index
dm_CheckCacheConfig, 200 integer, 13

pattern matching, 35
types of, 13
K locales
keywords determining current, 255
as selected values, 143 DM_SESSION_DD_LOCALE
DQL, 19 keyword, 20
full‑text, 143 locking
miscellaneous, 146 tracing Windows, 359
PUBLISH, 56, 88 log files
THUMBNAIL_URL, 147 LOG_OFF administration
virtual document, 144 method, 280
LOG_ON administration method, 282
L MIGRATE_CONTENT administration
method, 301
LAST keyword, 157
LOG_OFF administration method, 280,
LAUNCH_DIRECT, run_as_server
282
and, 225
LOG_ON administration method, 282
lifecycles
logical operators
batch promotion, 194
described, 39
defining default for object types, 61
precedence order, 40
lightweight type
login ticket key
create, 88
EXPORT_TICKET_KEY
LIKE (predicate)
administration method, 234
described, 32
IMPORT_TICKET_KEY
pattern matching with, 35
link record object type, 210
RESET_TICKET_KEY administration
linked storage areas
method, 343
removing unneeded objects from, 210
login ticket keys
linking objects with UPDATE...
tracing import/export, 359
OBJECT, 184
login tickets
links
tracing, 359
removing with UPDATE...
logs
OBJECT, 184
tracing and, 313
LIST_AUTH_PLUGINS administration
LOWER (scalar function), 21
method, 266
LIST_RESOURCES administration
method, 268 M
LIST_SESSIONS administration MAKE_INDEX administration
method, 273 method, 284
LIST_TARGETS administration mapping information, dropping, 68
method, 278 mapping table specification, 65, 91
literals MARK_AS_ARCHIVED administration
character string, 15 method, 288
date, 15 MARK_FOR_RETRY administration
date keywords, 18 method, 290
escape character and pattern MAX (aggregate function), 23 to 24
matching, 36 max_nqa_string (server.ini key), 55, 87
floating point, 14 maximums
ID format, 15 characters in string literals, 15
Index
floating point literal values, 14 testing for, 380

number of properties in ALTER TYPE NULLDATE (keyword), 19
statements, 57
values returned by MAX aggregate
function, 24
O
method objects object IDs
run_as_server property, 224 IN DOCUMENT clause and, 154
running procedures as server, 224 object type indexes
method server creating, 284
tracing execution, 359 DROP_INDEX administration
methods method, 227
dm_bp_batch, 194 FINISH_INDEX_MOVES
dmc_SetJavaExprEnabled, 413 administration method, 236
executing with DO_METHOD, 187 moving, 314
tracing method server, 359 object types
MFILE_URL (DQL function), 28, 142 adding default aspects, 57
MIGRATE_CONTENT administration changing to another, 379
method, 292 changing with ALTER TYPE, 51
log file, 301 component specifications,
MIGRATE_TO_LITE administrative removing, 63
method, 304 component_specification, 99
MIN (aggregate function), 23 to 24 constraints, removing, 63
minimum values creating, 83
floating point literals, 14 data dictionary information,
returned by MIN aggregate defining, 95
functions, 23 defining default lifecycle for, 61
MODIFY_TRACE administration deleting, 109
method, 312 mapping table specification, 62, 95, 98
MOVE_INDEX administration names, quoting in applications, 43
method, 314 properties
maximum allowed number of, 87
properties, adding, 56
N referencing, 379
names referencing in queries, 150
user, 147 removing default aspects, 58
NODESORT BY, 155 removing indexes for, 227
NOFTDQL DQL hint, 403 object‑level permissions
non‑qualifiable properties DQL statements and, 390
constraint on string datatypes, 55, 87 objects
NOT (logical operator), 40 batch promotion, 194
NOT EXISTS (predicate), 32 changing to another type, 379
NOT IN (predicate), 32 changing type, 71
NOT LIKE (predicate) creating, 79
described, 32 deleting, 103
pattern matching with, 35 linking with UPDATE...OBJECT, 184
NOT NULL constraints, 94 moving to new folder/cabinet, 184
NOW (keyword), 18 unlinking with UPDATE...
NULL values OBJECT, 184
in properties, 380 Update...Object (statement), 178
sorting, 382 OBJTYPE (keyword), 143
Index
operators comparison operators, 31

arithmetic, 30 defined, 30
comparison, 31 FOLDER, 38
logical, 39 pattern matching, 35
OPTIMIZE_TOP, 398 repeating property predicates, 32
OR (logical operator), 40 single‑valued property predicates, 31
Oracle SysObject, 37
RETURN_TOP, 397 TYPE, 37
SYNONYM FOR code page where clause components, 161
requirement, 127 WHERE clause components, 30
ORDER BY clause primary key constraints, 93, 96
examples of use, 440 printing, assume user feature and, 225
SELECT statement, 167 private
groups, 46, 77
privileges
P granting, 118
PARENT (keyword), 146 revoking, 128
parentheses to change precedence of programs
logical operators, 41 assume user, 225
partition, 59, 88 properties, 382
partitioning types, 59, 88 See also repeating atttributes
passthrough database hints, 405 adding to type definition, 56
pattern matching aspect properties, selecting, 138
characters, 35 assume_user_location and disabling
escape character, 36 assume user program, 225
percent sign (%) data dictionary information,
pattern matching character, 35 defining, 89
performance default values, defining, 92
SEARCH clauses, 230 dfc.compatibility.truncate_long_
searches and PUBLIC keyword, 150 values preference, 15
WHERE clause, 162 dropping, 57
permits, registered tables, 389 lengthening character string types, 57
persistent client caching mapping table information,
CHECK_CACHE_CONFIG defining, 91
(administration method), 198 modifiers, 64
dm_CheckCacheConfig job, 200 modifying, 57
PING administration method, 316 names, quoting in applications, 43
precedence non‑qualifiable, selecting, 138
date formats, 17 NULL values and, 380
logical operators, 40 querying indexed, 158
predicates referencing, 379
ANY...comparison operator, 33 string length constraint, 55, 87
ANY...IN, 33 property drop clause, 67
ANY...IS NULL, 33 property values, retrieving, 137
ANY...IS NULLDATE, 33 public
ANY...IS NULLINT, 33 groups, 46, 77
ANY...IS NULLSTRING, 33 objects, selecting, 143
ANY...LIKE, 33 PUBLIC keyword
arithmetic operators, 30 creating public groups, 76
CABINET, 39 DELETE...OBJECT statement, 105
Index
SELECT statements and, 150 updating rows, 175

PUBLISH keyword, 56, 88 RECOVER_AUTO_TASKS administration
publishing, to Web site, 372 method, 331
PURGE_AUDIT administration REGISTER (statement), 123
method, 318 REGISTER_ASSET administration
PURGE_CONTENT administration method, 333
method, 326 registered tables
PUSH_CONTENT_ATTRS administration creating, 123
method, 328 deleting rows, 101
described, 388
DQL predicates for, 31
Q inserting rows, 120
qualifying table names, 152 permissions, default, 390
queries querying, 140
database hints, 393, 406 querying (examples of), 442
executing SQL, 232 referencing in queries, 150, 389
FROM clause limitations, 150 security, 389
query optimization SYNONYM clause, 126
OPTIMIZATION_LEVEL (DQL table names, qualifying, 152
hint), 399 unregistering, 173
query performance updating rows, 175
GROUP_LIST_LIMIT DQL hint, 404 REINDEX_PARTITIONABLE_TYPE
HIDE_SHARED_PARENT DQL administration method, 335
hint, 404 removing
query result objects repeating property values, 184
ROW_BASED DQL hint effects, 401 REORGANIZE_TABLE administration
query results method, 337
returning as object‑based, 139 repeating properties
ROW_BASED DQL hint, 139 adding values, 383 to 384
queue items comparison expressions, use in, 163
marking for indexing retry, 290 compound ANY predicates, use
in, 162
R deleting values, 385
forcing index correspondence, 385
RDBMS
index positions, 383
deleting table rows, 101
NULL values and, 380
inserting table rows, 120
predicates for, 32
operation statistics, 212
querying (examples of), 438
passthrough hints for SELECT, 168
removing multiple values, 184
permissions for Superusers, 391
truncating, 184
registered tables
updating values, 385
described, 388
values
permissions for, 389
appending, 183
referencing in queries, 389
inserting, 183
security, 389
removing, 184
REORGANIZE_TABLE
WHERE clause use, 162
replicas
unregistering tables, 173
deleting, 214
UPDATE_STATISTICS administration
determination of, 146
method, 369
importing, 262
Index
REPLICATE administration method, 340 SELECT statement, 157

replicating, 340 TOPIC format, 160
repositories words and phrases, specifying, 158
audit trail entries, removing, 318 search string
IMPORT_TICKET_KEY words and phrases, specifying, 158
administration method, 264 search strings
owner name aliases, 389 accent marks in, 159
repository sessions asterisk as wildcard, 160
query caching, 390 case sensitivity, 159
reserved words diacritical marks in, 159
table of, 431 security
RESET_TICKET_KEY administration CHECK_SECURITY (administration
method, 343 method), 205
RESTORE_CONTENT administration DQL statements and, 390
method, 345 SELECT (statement)
retention policies ALL keyword, 137, 151
tracing use, 359 arithmetic expressions as selected
retention_trace tracing option, 359 values, 142
RETURN_TOP AS clause, 149
described, 396 assigning result property names, 149
SEARCH clause and, 397 asterisk as selected value, 148
REVOKE (statement), 128 DELETED keyword, 151
roles, see client roles described, 378
ROLES_FOR_USER administration disambiguating types and tables, 152
method, 347 DISTINCT (keyword), 137
ROW_BASED DQL hint, 401 DQL functions as selected values, 141
affect on asterisk as selected value, 148 DQL hints, 168
RPC calls, tracing, 359 FROM clause, 150
RPC logging FROM clause limitations, 150
turning off, 280 GROUP BY clause, 165
turning on, 282 HAVING clause, 165
RPC tracing, 359 IN ASSEMBLY clause, 156
run_as_server property, 224 IN DOCUMENT clause, 153
keywords as selected values, 143
LITE keyword, 151
S MFILE_URL as selected value, 142
scalar functions ORDER BY clause, 167
as selected values, 141 permissions and, 390
LOWER, 21 retrieving column values, 140
SUBSTR, 22 retrieving property values, 137
UPPER, 21 SEARCH clause, 157, 229
SCORE (keyword), 143 table name specification, 152
SEARCH clause type name specification, 151
accents and diacritical marks in, 159 UNION clause, 166
asterisk as wildcard, 160 WHERE clause, 161
case sensitivity, 159 where clause qualification
DOCUMENT CONTAINS components, 161
format, 158 WITH option, 155
IN FTINDEX option, 160 SELECT statement
RETURN_TOP and, 397 aspect properties, referencing, 136
Index
aspect properties, selecting, 138 restoring archived content, 345

described, 130 setting default, 61
dmi_audittrail_attrs constraint, 151 string datatypes
FTDQL queries, 135 non‑qualifiable property
non‑qualifiable properties, constraint, 55, 87
selecting, 138 SUBSTR (function), 22
server.ini file, session information SUM (aggregate function), 25
parameters, 276 SUMMARY (keyword), 144
servers. See Content Server, 390 Superuser user privilege
session locales RDBMS permissions, 391
tracing, 358 Sybase
sessions RETURN_T0P, 397
listing active, 363 SYNONYM clause, 126
listing current and historical, 273 SYNONYM FOR clause
SET_APIDEADLOCK administration internationaliztion requirements, 127
method, 349 syntax
SET_CONTENT_ATTRS administration dates, 15
method, 352 SYSOBJ_ID (keyword), 143
SET_OPTIONS administration SysObjects
method, 357 predicates, 37
SET_STORAGE_STATE administration system administration
method, 361 execute (statement), 111
SETFILE clause, 181
shareable type
alter type, 59
T
create, 88 table permits, 389
short date formats tables
defaults, 18 deleting rows, 101
described, 16 inserting rows, 120
SHOW_SESSIONS administration querying, 140
method, 363 registering, 123
SOME predicate, 32 unregistering, 173
sorting (ORDER BY clause), 167 updating rows, 175
SQL (Structured Query Language) tablespaces
executing queries, 232 moving type indexes, 314
tracing last statement, 358 TEXT (keyword), 144
tracing statements, 359 THUMBNAIL_URL (keyword), 147
SQL Server thumbnails
FETCH_ALL_RESULTS hint generating, 333
constraint, 399 TODAY (keyword), 18
RETURN_TOP, 396 TOMORROW (keyword), 18
RETURN_TOP hint constraint, 397 tracing
SQL_DEF_RESULT_SET, 394 content‑addressed storage
square brackets for index values, 183 operations, 358
statistics full‑text index operations, 312
RDBMS, determining, 212 login ticket keys, 359
storage areas login tickets, single‑use, 359
archiving files, 326 retention policy use, 359
making read‑only, 361 RPC calls, 282
moving offline/online, 361 trace file storage, 357
Index
turning on/off, 357 USER (keyword), 20, 147

workflow agent operations, 359 user privileges
transactions granting, 118
aborting explicit, 44 revoking, 128
committing, 75 user privileges, DQL statements and, 390
starting explicit, 70 users
TRANSCODE_CONTENT administration CHECK_SECURITY (administration
method, 365 method), 205
transformations, requesting, 365 name of current, 147
TRUE (keyword), 20 USING ASSEMBLIES, 154
truncating repeating properties, 184
TRY_FTDQL_FIRST DQL hint, 403
TYPE (predicate), 37
V
types va_clause (data dictionary), 90
alter type statement, 51 value assistance
create...object (statement), 79 dropping, 68
deleting, 109 format, 90
dropping properties, 57 specification, 65
modifying properties, 57 VERSION (keyword), 154
setting default ACL, 60 virtual documents
full‑text indexes and, 388
IN DOCUMENT clause, 153
U keywords for, 144
UNCOMMITTED_READ (database querying, 387
hint), 400 querying (examples of), 442
underbar ( _ )
pattern matching character, 36
UNION clause, 166
W
unique key constraints, 93, 97 Web sites
UNIX process launch, tracing, 359 publishing to, 372
unlinking WEBCACHE_PUBLISH administrative
objects with UPDATE...OBJECT, 184 method, 372
Unregister (statement), 173 WHERE clause, 161
UPDATE (statement), 175, 378 examples of use, 438
update modifier, 65 predicates, 30
UPDATE...OBJECT (statement), 178, 379 valid qualifications, 161
update_modifier specification, 89, 95 wildcards for pattern matching, 35
UPDATE_STATISTICS administration workflow agent
method, 369 tracing, 359
UPPER (scalar function), 21
URLs Y
MFILE_URL (DQL function), 28 YESTERDAY (keyword), 18
THUMBNAIL_URL (keyword), 147
use_estimate_search (server.ini key), 230

DQL Reference Manual 6.5

Uploaded by

Copyright:

Available Formats

DQL Reference Manual 6.5

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DQL Reference Manual 6.5

Uploaded by

Copyright:

Available Formats

EMC® Documentum®

DQL Reference Manual

EMC Documentum Content Server Version 6.5 DQL Reference Manual 3

SysObject predicates ............................................................................... 37

Chapter 2 DQL Statements .................................................................................... 43

Chapter 4 Using DQL ........................................................................................... 377

Appendix A Using DQL Hints .................................................................................. 393

4 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Effects of a SEARCH clause ................................................................... 397

Appendix B Implementing Java Evaluation of Docbasic Expressions .................... 407

Appendix C DQL Quick Reference .......................................................................... 423

Appendix D Document Query Language Examples ................................................ 437

EMC Documentum Content Server Version 6.5 DQL Reference Manual 5

Searching cabinets and folders .................................................................. 441

6 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Figure 1. Sample virtual document ............................................................................. 145

EMC Documentum Content Server Version 6.5 DQL Reference Manual 7

Table 1. Valid ranges for floating point literals .............................................................. 14

8 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Table 38. CLEAN_DELETED_OBJECTS arguments ...................................................... 208

EMC Documentum Content Server Version 6.5 DQL Reference Manual 9

Table 80. RESTORE_CONTENT arguments.................................................................. 345

10 EMC Documentum Content Server Version 6.5 DQL Reference Manual

EMC Documentum Content Server Version 6.5 DQL Reference Manual 11

Revision Date Description

12 EMC Documentum Content Server Version 6.5 DQL Reference Manual

This chapter describes the building blocks of a DQL statement, including:

where n is any number between ‑2147483647 and +2147483647.

EMC Documentum Content Server Version 6.5 DQL Reference Manual 13

Floating point literals

DQL accepts either uppercase or lowercase in the notation.

Table 1. Valid ranges for ﬂoating point literals

RDBMS Range Significant digits

Oracle 1.0 x 10‑129 to 9.99 x 10‑129 15

14 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Character string literals

EMC Documentum Content Server Version 6.5 DQL Reference Manual 15

Table 2. Default character string formats for dates

Short date formats

16 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Other character string formats

EMC Documentum Content Server Version 6.5 DQL Reference Manual 17

Date literal keywords

Four keywords represent dates. They are:

Date output formats

18 EMC Documentum Content Server Version 6.5 DQL Reference Manual

The default short date formats, by platform, are:

Date storage and handling

EMC Documentum Content Server Version 6.5 DQL Reference Manual 19

• USER, which identifies the current user.

20 EMC Documentum Content Server Version 6.5 DQL Reference Manual

• Date functions, page 25

EMC Documentum Content Server Version 6.5 DQL Reference Manual 21

SELECT LOWER("subject") FROM "dm_document"

22 EMC Documentum Content Server Version 6.5 DQL Reference Manual

The COUNT function counts values. The syntax is:

EMC Documentum Content Server Version 6.5 DQL Reference Manual 23

WHERE "style" = 'apt' AND "bedroom" = 2

The AVG function returns an average. The syntax is:

24 EMC Documentum Content Server Version 6.5 DQL Reference Manual

Predicates for columns and singlevalued properties

Table 5. Predicates for columns and singlevalued properties

Fulltext indexing of aspect properties

Table 9. Syntax variations for fulltextindexing of aspect properties