MaxL DDL Definitions

This section contains the following topics:


Syntax Notes

The following syntax scheme applies to the creation of MaxL statements.

A MaxL statement corresponds to a sentence telling Analytic Services what to do with users and database objects. In this documentation, the grammar of MaxL statements is illustrated using railroad diagrams.

When issued via the MaxL Shell (essmsh), statements must be terminated by semicolons. Semicolons are used to tell the shell when to terminate the statement. When issuing MaxL statements programmatically through Perl or API programs, do not terminate with a semicolon.

A token is a delimited sequence of characters recognized by MaxL as a single readable unit. Tokens may be singleton names, keywords, strings, or numbers. Names can have one, two, or three tokens, delimited by periods. The space delimiting tokens can be any white space: spaces, tabs, new lines, or blank lines.

A keyword is a sequence of alphabetic characters that is part of the MaxL grammar. Each keyword is recognized as one token. To be recognized as keywords, keywords cannot be enclosed in quotation marks. However, if you wish to use MaxL keywords outside of the grammar as terminals (for example, as database names or passwords), they must be enclosed in single or double quotation marks.

A terminal is something referenced in the grammar for which you provide the correct name or definition. Terminals can be names, numbers, or strings. Examples: user-name, filter-name, size-string.

A name is any string that starts with an alphabetic character, or any quoted string. Names in MaxL are used to uniquely identify databases and database objects, such as users, applications, or filters.

Names in MaxL may be one of three types:

A string is unquoted or quoted. An unquoted string can be any sequence of non-special characters. A quoted string can be any sequence of characters (special, alphabetic, or numeric) in the MaxL Alphabet, enclosed in single or double quotation marks.

A number is one kind of token which may be passed to Analytic Services by MaxL. To have meaning, the number must be in the correct format for the Analytic Services value it represents. In the MaxL grammar documentation, labels for numbers indicate whether the allowed number is positive, negative, an integer, or a real. See Numbers.

The MaxL alphabet consists of the following elements:

Element Description
Special characters Valid special characters: .   ,   ;   :   %   $   "   '   SPACE   TAB   *   +   -   =
<   >   [   ]   {   }   (   )   ?   !   /   \   |   ~   `   #   &   @   ^  

When using special characters in MaxL terminals, note the quoting rules.

Non-special characters Alphabetic characters and numbers.
Alphabetic characters Letters of the alphabet, and the underscore. [a-z, A-Z, _]
Numbers See Numbers

Numbers

Numbers in MaxL statements fit into one of the following categories.


INTEGER Zero or a positive integer. Decimals and scientific notation are permitted. Examples: 0, 1, 1000, 1.3e4
REAL Zero or a positive real number. Decimals and scientific notation are permitted. Examples: 0.0, 1, 1000, 1000.4, 13.1e-4

Terminals


TerminalDescription
ACCESS-TYPE
(string)
The domains that a user can access based on the named user license.

The only possible input value for this string is:

        Essbase
        
ACTION
(string)

mail [smtp],[sender],[receiver1,reciever2,...],[subject]
spool FILE-NAME
The required action if a data-monitoring trigger is activated. Available actions are:
  • mail - sends an email from the specified sender, to a specified email address or addresses, with the specified subject line (optional). Enclose email addresses containing special characters in square brackets ([]).

    The mail action is not supported for after-update triggers, which are the only triggers available for use with aggregate storage databases.


  • spool - logs a message in a specified file in the $ARBORPATH\app\appname\dbname\trig folder.

Examples:

mail manager.sales.com, [mktdir@CC.com, Monitor@acnts.com]

spool "trgmonitor"

ADMIN-SVCS-LOCATION
(string)
The name (or IP address) and port number of the computer on which Administration Server runs.
Examples: Aspen:10080     127.0.0.1:10080
ALG-CLASS
(string)
The Java class and the method representing a data-mining algorithm. Must be the fully qualified name of the Java class that contains the logic for the algorithm. Must be enclosed in single or double quotation marks.
Example: 'com.hyperion.essbase.algorithms.Regression'
ALG-MODE
(string)
The task mode for the data-mining algorithm. Possible values for this string are: build.
ALG-NAME
(name)
The name of a data mining algorithm. If the name contains special characters, it must be enclosed in single or double quotation marks.
Examples:

AssocRules Regression
'Naive Bayes'
ALT-NAME-SINGLE
(name)
The name of an alias table. If the name contains special characters, it must be enclosed in single or double quotation marks.
Examples:

 Region
'Long Names'
APP-NAME
(name)
The name of the application. Limit 8 characters.

 

If the name contains any allowed special characters, it must be enclosed in single or double quotation marks. Only the following special characters are allowed by Analytic Services within application names:

% (percent sign)
$ (dollar sign)
- (minus sign)
{ (open brace)
} (close brace)
( (open parenthesis)
) (close parenthesis)
! (exclamation mark)
~ (tilde)
` (accent mark)
# (pound sign)
& (ampersand)
@ (at sign)
^ (caret)


Example: Sample
AREA-ALIAS
(name)

A shorthand name used in the in the CREATE PARTITION statement for referring to an already-specified member expression that designates which areas of the databases should be partitioned.

Example:
In the create partition statement below, "foo" is an area-alias for the member expression specified in the area specification. To create area-aliases, enter the alias names after the member expression in each area specification. To specify which area is relevant when mapping members (if applicable), refer to its alias name in the mapped phrase.

In the example below, the alias name as created is shown in this color, and it specifies which area (in other words, it refers to the entire member expression string, '@IDESCENDANTS(East) @IDESCENDANTS(Qtr1)'). The alias name as referenced is shown in this color.

create or replace replicated partition sampeast.east
area '@IDESCENDANTS("Eastern Region"), @IDESCENDANTS(Qtr1)' to samppart.company at aspen as admin identified by 'password' area '@IDESCENDANTS(East) @IDESCENDANTS(Qtr1)' foo mapped foo (Year) to (Yr) update allow validate only;
Note: All area aliases used in a mapping should be associated with the target (as in the example above), and the direction of member names listed in the mapped clause should go from source to target.
AUTH-PARAMETERS
(string)
Leave unspecified if you are implementing the Hyperion security platform.

Custom Analytic Services external-authentication connection parameters. If the AUTHENTICATIONMODULE setting in the server configuration file essbase.cfg file contains the full authentication parameters, then identified by AUTH-PARAMETERS can be omitted from the MaxL statement.

Valid values can be anything representing private data needed to authenticate the user with the custom Analytic Services authentication protocol. For example, in an LDAP schema, default connection parameters would be the portion of the DN (Distinguished Name) other than the user name, followed by @hostname:port_number.

Example: 'ou=Groups, dc=yahoo, dc=com@server2:389'

The parameter list must be enclosed in single or double quotation marks, so that MaxL can interpret it as one string.

BUFFER-ID
(number)
A number between 1 and 4294967296. To destroy a buffer before a data load is complete, you must use the same BUFFER-ID number that was used to initialize the buffer. Only one buffer is allowed per import statement. Therefore, it is recommended to simply use a BUFFER-ID of 1.
CALC-NAME

name1.name2.name3 (db-level calc)
OR
name1.name3 (app-level calc)
  • name1 - Application name.
  • name2 - Database name (not required for application-level calcs).
  • name3 - Calc script name.

A stored calculation.

For calculations associated with databases, three tokens are required, to indicate application and database context and the calculation name.

Example: Sample.basic.'alloc.csc'

For application-level calculations, two tokens are required, indicating application context and the calculation name. When executing application-level calculations, you must specify which database to calculate using the syntax 'on database STRING.'

Example:
  • Sample.'alloc.csc' is the application-level CALC-NAME.
  • execute calculation Sample.'alloc.csc' on database Basic; is a way to execute the application-level calculation on a database.

If any part of the name contains special characters, or if any part of the name begins with a number, it must be enclosed in single or double quotation marks.

CALC-NAME-SINGLE
(name)

A stored calculation name that is the third token of a database-level CALC-NAME.

For example, if the full database-level calc name is sample.basic.'alloc.csc', then CALC-NAME-SINGLE is 'alloc.csc'.

If any part of the name contains special characters, it must be enclosed in single or double quotation marks.

CALC-SPEC-STRING
(string)
An optional Analytic Services calculator-syntax specification string. Must be enclosed in single quotation marks.

Example: '@COVARIANCE (expList1, expList2)'

Use CALC-SPEC-STRING only if the function or macro needs to be returned through the API that lists functions.
CALC-STRING
(string)

A calculation string. The body of an anonymous (unstored) calculation, or the string used to specify the body of a stored calculation at create time.

Because calculations are terminated with a semicolon, and semicolons are special characters to MaxL, CALC-STRING should be enclosed in single or double quotation marks.

Example: CALC DIM(Year, Measures, Product);

COLUMN-WIDTH
(number or default)
A number (at least 8) representing character-width of columns; or, the keyword default, representing 20 characters wide.
Examples:
80    default   109
COMMENT-STRING
(string)
A string of user-defined informational text. If the string contains special characters, it must be enclosed in single or double quotation marks.
Example: 'This is a comment.'
CONDITION
(string)
A numeric-value-expression developed in MDX. Must be enclosed in double quotation marks. Enclose strings containing special characters in square brackets ([]).

Example: "Jan>20".

CUBE-AREA
(string)
A cube area specification developed in MDX as a symmetric, syntactically-valid set. The area specification must be static, for example it cannot contain Dynamic Calc members or runtime functions such as Filter, TopSum, or BottomSum. Must be enclosed in double quotation marks. Enclose strings containing special characters in square brackets ([]). For information about defining cube areas, see Set Specification in the MDX section.

Example: "(Jan, Sales, Actual, [100], East)"

DATE
(string)
A valid date string formatted according to these rules:
  • MM/DD/YYYY or MM/DD/YY
  • Any character can be used as a separator; for example, MM~DD~YY is valid.

If the string contains special characters, it must be enclosed in single or double quotation marks.

Examples:
'04/16/03'
'04.16.2003'
04_16_2003

DIM-NAME
(string)
The name of a database dimension.

If the string contains special characters, it must be enclosed in single or double quotation marks.

Examples:
Year
Market

DBS-EXPORT-DIR
(string)

Suffix for the name of a database directory to contain export files, to be created (upon export lro) on the server or client as $ARBORPATH/app/appname-dbname-suffix.

After export lro, the directory contains file-type LRO binary files (if applicable to the database), and the LRO-catalog export file with file-extension .exp.

For example, if for a Sample.Basic export, DBS-EXPORT-DIR is given as lros, then the sample-basic-lros directory is created in the $ARBORPATH/app directory structure. The sample-basic-lros directory contains file-type LRO binary files and the LRO-catalog export file 'sample-basic-lros.exp'.

Notes:

  • MaxL creates exactly one export directory; it does not create a directory structure.
  • If the specified export directory already exists, the export LRO statement will fail. This is a safeguard against overwriting existing export directories.
DBS-NAME
(name1.name2)
  • name1 - The name of the application containing the database. Limit 8 characters.
  • name2 - The name of the database. Limit 8 characters.

The name of a database. Two tokens are required, to indicate application context.

If the name contains any allowed special characters, it must be enclosed in single or double quotation marks. Only following special characters are allowed by Analytic Services within database names:

% (percent sign)
$ (dollar sign)
- (minus sign)
{ (open brace)
} (close brace)
( (open parenthesis)
) (close parenthesis)
! (exclamation mark)
~ (tilde)
` (accent mark)
# (pound sign)
& (ampersand)
@ (at sign)
^ (caret)


Example: Sample.basic
DBS-STRING
(string)

The second token of DBS-NAME. Limit 8 characters.

If the name contains special characters, it must be enclosed in single or double quotation marks.

Example: basic

EXPORT-DIR
(string)

The exact name of a directory in $ARBORPATH\app where LRO-catalog information was exported using export lro. Give only the directory name; do not give the full path. Must be enclosed in single or double quotation marks. The typical format is appname-dbname-suffix.

Example: 'sample-basic-out'

FILE-NAME
(string)
A file name or an absolute path to a file. If the string contains special characters, it must be enclosed in single or double quotation marks. Double quotation marks allows variable expansion; single quotation marks does not. If the file path contains a backslash ( \ ), it must be preceded with another backslash ( \\ ) to be interpreted correctly by the MaxL Shell.
Examples:
  • file01
  • 'D:\\filename'
  • "$ARBORPATH/errors.txt"
  • "$ARBORPATH\\app\\sample\\basic\\calcdat.txt" (double quotation marks to expand the variable)
  • '/homes/fiona/scriptfile.msh' (UNIX file path)
FILTER-NAME
(name1.name2.name3)
  • name1 - Application name.
  • name2 - Database name.
  • name3 - Filter name.

The name of a security filter. Three tokens are required, to indicate application and database context.

Example: Sample.basic.filt1
FULL-EXPORT-DIR
(string)

Full path for the name of a directory for LRO export files, to be created (upon export lro) anywhere on the client or server.

After export lro, the directory contains file-type LRO binary files (if applicable to the database), and the LRO-catalog export file named in the format directoryname.exp.

For example, if for a Sample.Basic export, FULL-EXPORT-DIR is given as home/temp/lros, then the lros directory structure is created under home/temp if home/temp exists. The lros subdirectory contains file-type LRO binary files and the LRO-catalog export file 'lros.exp'.

Notes:

  • MaxL creates exactly one export directory; it does not create a directory structure. In the above example, if the home/temp directory structure exists, MaxL creates the lros directory as a subdirectory of home/temp, but if home/temp does not exist, MaxL will not create home/temp/lros.
  • If the specified export directory already exists, the export LRO statement will fail. This is a safeguard against overwriting existing export directories.
  • On Windows, use double backslashes ( \\ ) to represent backslashes in file paths. This is so that the MaxL Shell can interpret the second backslash literally, and not as an escape sequence. Example: 'C:\\temp\\lros'
FUNC-NAME

name1.name2
(local)
OR
name2 (global)
  • name1 - Application name.
  • name2 - Function name.

The name of a custom-defined Analytic Services function. Using one token indicates a global function. For a local (application-level) function, use two tokens.

The name of a custom-defined function is a unique string that begins with a letter or a @, #, $, _ symbol. The name can include alphanumeric characters or the aforementioned symbols. It is recommended that you start a function name with @.

Any token of the name that contains special characters must be enclosed in single or double quotation marks.

Example:
  • Sample.'@COVARIANCE' (a local function)
  • '@COVARIANCE' (a global function)
GROUP-NAME
(name)
The name of the Analytic Services security group. Not applicable for externally stored groups. Group names must start with a letter or a number. If the name contains any special characters, it must be enclosed in single or double quotation marks.
Example: Sales
HOST-NAME
(name)
The name of a computer.
Example: Aspen

You can optionally use IP addresses in place of hostnames when creating, dropping, or altering partition definitions. For example: '127.0.0.1'.

If you are creating, altering, or dropping a partition to or from another agent on the same computer, see Specifying Port Numbers in Partition Host Names for more information.

If you are using host name aliases, see also Using Host Name Aliases When Partitioning.

Leading or trailing spaces in the host name are illegal and will be trimmed off.

IMPORT-DIR
(string)

A string representing the full path to the directory used in the export lro statement.

Note: If importing lros from a server directory (using from server syntax of import lro), you can give just the full directory name instead of the full path, as specified by EXPORT-DIR.

The string must be enclosed in single or double quotation marks.

Examples:

  • 'c:\\hyperion\\AnalyticServices\\app\\sample-basic-lros'
  • 'c:\\hyperion\\AnalyticServices\\client\\sample-basic-lros'
  • 'home/exports/temp/sample-basic-lros'
  • "$ARBORPATH\\app\\sample-basic-lros"
    Note: If variables are used, the string should be enclosed in double quotation marks.


For information about how IMPORT-DIR is created, see the grammar and definitions for export lro.

IMP-FILE
(string)
A name or absolute path to a server-side rules file or data file, used for import data and import dimension statements.

If the data or rules file is specified to be on the server, the following rules apply. If the data or rules file is specified to be local (or left unspecified, in which case it is also local), skip the following and use FILE-NAME.

If you are using server data_file or server rules_file, you can get the file from any application (not just the current application) by starting the IMP-FILE string using the following pattern:

FILE_SEP AppName FILE_SEP DbName FILE_SEP rest_of_file_name

where FILE_SEP must be either / or \\.

Examples:

Consider the MaxL statement

import database demo.basic data 
from server rules_file 'IMP-FILE' 
on error abort;

If IMP-FILE is 'calcdat.txt', the file will be looked for in \Demo\Basic\calcdat.txt.

If IMP-FILE is '/Sample/Basic/calcdat.txt' (or '\\Sample\\Basic\\calcdat.txt'), the file will be looked for in \Sample\Basic\calcdat.txt.

If the FILE_SEP string FILE_SEP string FILE_SEP pattern does not start the string, the entire string is used as the filename, but the current application directory is assumed. For example, if the initial file separator is omitted and IMP-FILE is incorrectly specified as 'Sample/Basic/calcdat.txt', the file will be looked for in /Demo/Basic/Sample/Basic/calcdat.txt.

import database demo.basic data 
from server file '/Sample/Basic/Calcdat.txt' 
on error abort; 

Analytic Services looks for calcdat.txt inside the Sample.Basic directory, and loads the data to Demo.Basic.

JAVACLASS.METHOD
(string)
The java class and the method representing the custom-defined function. Must be a fully qualified java method name and signature, enclosed in single or double quotation marks.
Example: 'com.hyperion.essbase.calculator.Statistics.covariance'
For Java code examples and MaxL registration scripts for custom-defined functions, see Custom-Defined Calculation Function Examples
LOCATION-ALIAS-NAME
(name1.name2.name3)
  • name1 - Application name.
  • name2 - Database name.
  • name3 - Location alias name.

The name of a location alias referencing another database.
Example: Sample.Basic.EasternDB

MACRO-NAME

name1.name2 (local)
OR
name2 (global)
  • name1 - Application name.
  • name2 - Macro name.

The name of a custom-defined Analytic Services macro. Macro names are a shorthand way to refer to macro expansions.

The name of a macro is a unique string that begins with a letter or a @, #, $, _ symbol. The name can include alphanumeric characters or the aforementioned symbols. It is recommended that you start a macro name with @. Although macros must have unique names within a given application, a global macro and a local macro can share the same name. However, the local macro takes precedence.

To create or refer to a local (application-level) macro, use the double name (for example, Sample.'@JSUM').

Any part of the name that contains special characters must be enclosed in single or double quotation marks.

Examples:
  • Sample.'@COUNTRANGE' - Application-level (local) macro name without a signature, meaning that there are no restrictions on its arguments.
  • Sample.'@COUNTRANGE(Any)' - Same as Sample.'@COUNTRANGE'. Once registered for the application, @COUNTRANGE can take any arguments.
  • '@JCOUNTS' - System-level (global) macro name.
  • '@JCOUNTS(single,group)' - Same as '@JCOUNTS', but with a signature restricting its arguments.
For more information about macro signatures (input parameters), see Custom-Defined Macro Input Parameters
MACRO-EXPANSION
(string)
Extended definition of the macro, to be substituted in wherever the registered macro name is referenced in a calculation. If the string contains special characters, it must be enclosed in single or double quotation marks.
Example: '@COUNT(SKIPMISSING,@RANGE(@@S))'
For more information, see Custom-Defined Macros.
MEMBER-EXPRESSION
(string)

Outline member specification of members from one or more dimensions, member combinations separated by commas, or member sets defined with functions. Must be enclosed in single or double quotation marks.
Example: '@ANCESTORS(Qtr2)'.

If MEMBER-EXPRESSION contains MEMBER-NAMES that begin with numbers or contain special characters, then enclose those member names in double quotation marks, and the entire MEMBER EXPRESSION in single quotation marks. For example:

  • create or replace filter demo.basic.numfilt no_access on '"2"';
  • '@DESCENDANTS("Eastern Region"), @CHILDREN(Qtr1)'


MEMBER-NAME
(name)
The name of a database outline member.

If the name contains special characters, it must be enclosed in single quotation marks.
Examples:

  • Jan
  • 'New York'

If MEMBER-NAME is part of MEMBER-EXPRESSION and MEMBER-NAME begins with a number or contains special characters, enclose MEMBER-NAME in double quotation marks and enclose MEMBER-EXPRESSION in single quotation marks.

MODEL-ACCESSOR
(string)
The entity in a data-mining model that accesses data. The data can be input, output, or model data. The accessor name reflects the type of data it accesses, for example, predictor or target.
MODEL-MODE
(string)
The task mode for the data-mining model. Possible values for this string are: apply or test.
MODEL-NAME
(name)
The name of a data-mining model to apply to create data mining results. The model must exist.
MODULE-STRING
(string)
Leave unspecified if you are implementing the Hyperion security platform.

The name of the Analytic Services custom authentication module. Can be any string. Must be enclosed in single or double quotation marks. Supported modules are Lightweight Directory Access Protocol (LDAP) and Microsoft Active Directory. Suggested acronyms to use for MODULE-STRING are:
  • LDAP
  • MSAD
NEW-ALIAS-NAME
(name)
The name of a new location alias you are creating from the current database to reference a remote database.
Example: EasternDB
OBJ-NAME
(name1.name2.name3)
  • name1 - Application name.
  • name2 - Database name.
  • name3 - Object name.

The name of a database object. Three tokens are required, to indicate application and database context.

Example: Sample.basic.Calcdat
OBJ-NAME-SINGLE
(name)

A stored database object name that is the third token of a database-level OBJ-NAME.

For example, if the full database object name is sample.basic.calcdat, then OBJ-NAME-SINGLE is calcdat.

If any part of the name contains special characters, it must be enclosed in single or double quotation marks.

OUTLINE-ID
(number)

The numeric identification of an aggregate storage outline associated with a view. The outline ID is returned by the execute aggregate selection statement. The execute aggregate selection statement returns a set of views, including the outline ID for the views it returns.

Example: 4142187876

PASSWORD
(string)
A user's password. Not applicable for externally authenticated users. If the string contains special characters, it must be enclosed in single or double quotation marks. Leading or trailing spaces are illegal and will be trimmed off.
PRECISION-DIGITS
(string)
An integer between 0 and 15, inclusive.
RECORD-EXPR
(string)
Used for scoring, a data mining expression of data as a list of MDX tuples. For example, {([New_York],[Bagel],[Profit]),(New_York],[Rye_bread],[Cost]),([Boston],[Wheat_bread], [Cost])} . For more information see the Database Administrator's Guide chapter entitled "Mining an Analytic Services Database."
RESULT-ACCESSOR
(string)
The entity in a data-mining result record that accesses data. The data can be input, output, or model data. The accessor name reflects the type of data it accesses, for example, predictor or target.
RESULT-MODE
(string)
The task mode for the data-mining result. Possible values for this string are: apply or test.
RESULT-NAME
(name)
The name of a data-mining result record.
ROLE-NAME
(name)
The name of the security role. For more information, see Privileges and Roles.
Example: manager
SESSION-ID
(number)
The unique session ID. This ID can be used to logout a user session, or kill the current request in that session.
Example: 3310545319
SIZE-STRING
(number units)
OR
(number)
  • number - Any positive number. Decimals and scientific notation are permitted. Whitespace between number and units is optional.
  • units - One of the following: b, kb, mb, gb, tb (case-insensitive).
    If units are unspecified, bytes are assumed.
Examples:
51040b  51040 b  11MB  11000kb  12.34gb 1234e-2gb
SPOOL-NAME
(name1.name2.name3)
The name of a trigger's output file, as specified in the THEN or ELSE section of the create trigger statement.
Example: In the following create trigger statement, the bold section is the spool name.
create or replace trigger Sample.Basic.Trigger_Jan_20
where "(Jan,Sales,[100],East,Actual)"
when Jan > 20 and is(Year.currentmember,Jan) then
spool Trigger_Jan_20
end;
STOPPING-VAL
(number)
Optional stopping value for the execute aggregate process statement. Use this value to give the ratio of the growth size you want to allow during the materialization of an aggregate storage database, versus the pre-aggregation size of the database (Before an aggregation is materialized, the database contains only level 0 input-level data.)
For example, a stopping value of 1.5 means that during the materialization of the aggregation, the aggregate cells are allowed to occupy up to 50% of the disk space occupied by the level-0 data.
TABLSP-NAME
(name1.name2)
  • name1 - Application name.
  • name2 - Tablespace name.
The name of a tablespace. Tablespaces are applicable only to aggregate storage databases. For this release, possible names for tablespaces you can alter are default and temp. Other tablespace names reserved by the system are metadata and log.
TASK-MODE
(string)
The mode for the data-mining task template. Possible values for this string are: build, apply, test or score.
TASK-NAME
name
The name of a data-mining build, apply, or test template. You use a template to create the corresponding model.
TASK-XML-STRING
(string)
A string of XML representing a data-mining task to execute. Must be enclosed in single quotation marks.

There are several ways of obtaining the XML string. For the build task, the XML can be obtained either from display algorithm template (for a new build template) or from display mining template with mode 'build' (for an existing build template). For the apply task, the XML can be obtained either from display model template (for a new apply template) or from display mining template with mode 'apply' (for an existing apply template).

You may need to do the following before pasting the XML string into a MaxL statement:

  1. modify expressions in the template

  2. escape all single quotation marks in the XML (replace all ' with \' )
TRANSF-CLASS
(string)
The Java class and the method representing a data-mining transformation. Must be the fully qualified name of the Java class that contains the logic for the transformation. Must be enclosed in single quotation marks.
Example: com.hyperion.essbase.transformations.Log
TRANSF-NAME
(name)
The name of a data-mining transformation. Must be enclosed in single quotation marks.
TRIGGER-NAME
name1.name2.name3
  • name1 - Application name.
  • name2 - Database name.
  • name3 - The name of the trigger.

The name of the trigger device created to track and respond to database updates. Trigger names must be triple names, specifying application name, database name, and trigger name (f you rename the application or database, the trigger is invalidated). Trigger names are case-insensitive, are a maximum of 30 bytes, and cannot contain special characters.

Example: Sample.Basic.MyTrigger

UNIQUE-VOL-NAME
(name1.name2.name3)
  • name1 - Application name.
  • name2 - Database name.
  • name3 - Disk volume name.

The unique name of the disk volume definition. Unlike the name used when the disk volume definition was created (VOLUME-NAME), the unique disk-volume name must be a triple. The first two parts of the name specify application and database context. The third part of the name, on Windows, is a drive letter. On UNIX, it is a path to the AnalyticServices directory.

If any part of the name contains special characters, that part must be enclosed in single or double quotation marks.
Examples:
sample.basic.'vol3/hyperion/AnalyticServices'
sample.basic.c
.

If a Windows file path is used which contains a backslash ( \ ), it must be preceded with another backslash ( \\ ) to be interpreted correctly by the MaxL Shell. If variables are used, enclose the single-quoted string in double quotes so that the MaxL Shell knows to expand the variables.
Example:
sample.basic."'$ARBORPATH\\diskvol_area'"

USER-NAME
(name)
The name of the user. If the name contains special characters, it must be enclosed in single or double quotation marks. User names can contain any characters except for the backslash (\). User names must begin with a letter or a number. Leading or trailing spaces are illegal and will be trimmed off. If the user is being created for authentication on the Hyperion security platform, the name must match a valid login name on one of the configured corporate authentication repositories.
VARIABLE-NAME
(name)

The name of the substitution variable. The name can only contain alphanumeric characters and the underscore (a-z A-Z 0-9 _).

Example: curmonth

VIEW-FILE-NAME
(string)
An aggregation script containing information derived during aggregate view selection.

The file is created under ARBORPATH\app\app_name\db_name\ with a .csc extension.

Aggregation scripts are valid as long as the dimension level structure in the outline has not changed.

Executing an aggregation script (using execute aggregate build) materializes the aggregate views specified within it.

Omit the .csc file extension from the view file name when you issue the execute aggregate build statement.

VIEW-ID
(number)

The numeric identification of an aggregate view, returned by the execute aggregate selection statement. The concept of views applies only to aggregate storage databases.

VIEW-IDs persist only as long as their associated OUTLINE-IDs. OUTLINE-IDs change when changes are made to the outline.

Example: 8941

VIEW-SIZE
(number)
Approximate view size as a fraction of input data size. For example, a view size of 0.5 means that the view is 2X smaller than the input-level view. The concept of views applies only to aggregate storage databases.
VOLUME-NAME
(name)

The name of the disk volume. On Windows, a drive letter. On UNIX, a path to the AnalyticServices directory.

If the name contains special characters, it must be enclosed in single or double quotation marks.

Example: 'vol3/hyperion/AnalyticServices'.

If a Windows file path is used which contains a backslash ( \ ), it must be preceded with another backslash ( \\ ) to be interpreted correctly by the MaxL Shell. If variables are used, enclose the single-quoted string in double quotes so that the MaxL Shell knows to expand the variables.
Example:
"'$ARBORPATH\\diskvol_area'"

Privileges and Roles

Analytic Services system privileges are indivisible database access types. In MaxL, privileges are grouped together to form permission-sets called roles. With the exception of create_user and create_application, privileges themselves are not grantable using MaxL; you typically grant roles, which are the equivalent of privilege levels. The scope of a role can be the system, the application, or the database.

While one privilege does not imply another, roles are hierarchical. The following table illustrates the Analytic Services system privileges that are contained in each MaxL system role.

MaxL System Role Analytic Services System Privileges
read write calculate manage
database
create
database
start
application
manage
application
create/drop
application
create/drop
user
no access . . . . . . . . .
read . . . . . . . .
write . . . . . . .
execute . . . . . .
manager (database) . . . . .
manager (application) . .
administrator

System-Level System Privileges

The following privileges apply at the system level. These privileges are built-in; they do not apply to any specific application or database. They are not included in any role except for the role of administrator.


create_application Ability to create and delete applications.
create_user Ability to create and delete users and groups.

System-Level System Roles

System-level system roles are applicable to the Analytic Services system. The following roles have a system-wide scope:


no_access No access to the system.
administrator Full access to the entire system, including other administrators.

Application-Level System Roles

Application-level system roles are applicable to an application. The following roles may have an application-wide scope:


no_access No access to the application or any databases within it.
manager Manager access to the application and any databases within it. Manager access means ability to create, delete, and modify databases within the application, in addition to having Read, Write, and Execute access for that application.

Database-Level System Roles

Minimum Database Permissions

Database-level system roles are applicable to databases. The following roles have a database-wide scope and are available when assigning minimum database permissions:


no_access No access to the database (if assigned using alter database) or to any databases in the application
(if assigned using alter application).
read Read-only access to the database (if assigned using alter database) or to all databases in the application
(if assigned using alter application). Read access means ability to view files, retrieve data values, and run report scripts.
write Write access to the database (if assigned using alter database) or to all databases in the application
(if assigned using alter application). Write access means ability to update data values, in addition to having Read access.
execute Calculate access to the database (if assigned using alter database) or to all databases in the application
(if assigned using alter application). Calculate access means ability to update data values, in addition to having Read and Write access.
manager Manager access to the database (if assigned using alter database) or to all databases in the application
(if assigned using alter application). Manager access means ability to modify database outlines, in addition to having Read and Write access.

Database Roles Grantable to Users and Groups

The following database-level system roles are available for granting to users and groups:


no_access No access to the database.
read Read-only access to the database. Read access means ability to view files, retrieve data values, and run report scripts.
write Write access to the database. Write access means ability to update data values, in addition to having Read access.
manager Manager access to the database. Manager access means ability to modify database outlines, in addition to having Read and Write access.
Note: After granting read, write, or manager privilege to a user or group, these can be revoked by subsequently granting no_access. However, to prevent users from being able to load the application, you should also grant no_access at the application level. For example:
/* Grant read permission on a database */
grant read on database Sample.Basic to user1;

/* Revoke read permission on the database */
grant no_access on database Sample.Basic to user1;

/* Revoke read permission at the application level, to remove application-startup permission */
grant no_access on application Sample to user1;

Filter Roles

The following subset of database-level system roles may be granted or revoked using filters.


no_access No access to the specified data object.
read Read-only access to the specified data object. Read access means ability to view files, retrieve data values, and run report scripts.
write Write access to the specified data object. Write access means ability to update data values, in addition to having Read access.
meta_read Restricted access to sibling and ancestral metadata (dimensions and members). In case of a filtering conflict, the MetaRead filtering overrides the other filter permissions. For more information about metatdata filtering, see Metadata Filtering.
Note: After granting permissions using a filter, the permission can be revoked by subsequently granting no_access to the database. However, to prevent users from being able to load the application, you should also grant no_access at the application level. For example:
/* Grant read permission on a database, using a filter */
grant filter Sample.basic.filter8 to user1;

/* Revoke the filter, removing read permission on the database */
grant no_access on database Sample.Basic to user1;

/* Revoke read permission at the application level, to remove application-startup permission */
grant no_access on application Sample to user1;

Quoting and Special Characters Rules for MaxL Language

These rules apply to terminals of MaxL statements; for example, USER-NAME or FILE-NAME. Rules for MaxL Shell also apply.

Tokens enclosed in single quotation marks
Tokens enclosed in double quotation marks
Use of backslashes
Use of apostrophes
Use of dollar signs

Tokens enclosed in single quotation marks

Contents are preserved as literal, with the following exceptions:

Example: export database sample.basic data to data_file 'D:\\export.txt';
Result: Exports data to D:\export.txt.

Example: create user 'O'Brian' identified by 'password';
Result: Error.

Example: create user 'O\'Brian' identified by 'password';
Result: User O'Brian is created.

Tokens enclosed in double quotation marks

Contents are preserved as literal, with the following exceptions:

Example: export database sample.basic data to data_file "D:\\export.txt";
Result: Exports data to D:\export.txt.

Example: export database sample.basic data to data_file "$ARBORPATH\\App\\Sample\\Basic\\export.txt";
Result: Exports data to C:\Hyperion\AnalyticServices\App\Sample\Basic\export.txt.

Example: create user "O'Brian" identified by 'password';
Result: Error.

Example: create user "O\'Brian" identified by 'password';
Result: User O'Brian is created.

Use of backslashes

Ignored unless preceded by another backslash (the escape character). Must use single or double quotation marks around the token containing the two backslashes.

create application 'finance\\budget';
Result: Application finance\budget is created.

Example (Windows):

  export database sample.basic using report_file 
  'AnalyticServices\\App\\Sample\\Basic\\asym.rep' 
  to data_file 'c:\\home\\month2.rpt';
  

Result: The Windows file paths are interpreted correctly as AnalyticServices\App\Sample\Basic\asym.rep and c:\home\month2.rpt.

Use of apostrophes (single quotation marks)

Syntax error returned, unless preceded by a backslash (the escape character) and enclosed in single or double quotation marks.

Example:create user 'O\'Brian' identified by 'password';
Result: User O'Brian is created.

Note: Use sparingly. Apostrophes are permitted by Analytic Services in user and group names, but not in application or database names.

Use of dollar signs

Syntax error returned, unless preceded by a backslash (the escape character) and enclosed in single quotation marks. Dollar signs ($) intended literally need to be escaped by the backslash so that they are not considered variable indicators.

Example:create application '\$App1';
Result: Application $App1 is created.