MaxL Grammar

The MaxL Language has its own grammar that you use to create statements.
In this document, the syntax for the MaxL language is illustrated using BNF diagrams.

alter application
alter database
alter group
alter system
alter user
create application
create calculation
create database
create filter
create function

create group
create location alias
create macro
create partition
create user
display application
display calculation
display database
display disk volume
display filter

display filter row
display function
display group
display location alias
display macro
display partition
display privilege
display system
display user
display variable

drop application
drop calculation
drop database
drop filter
drop function
drop group
drop location alias
drop macro
drop partition
drop user

execute calculation
export
grant
import
login *
refresh replicated partition

The MaxL grammar is case-insensitive. Semicolon statement-terminators are required when using the MaxL Command Shell. However, do not use semicolons at the end of statements passed using Perl functions. Key words of the MaxL grammar are represented in this document in lower-case. Terminals, represented in upper-case, are to be replaced by the appropriate names, numbers, privileges, or strings. For more information about components of MaxL statements, see Language Definition.

* Note: Login is part of the separate command shell grammar, not the MaxL language itself. You can use the login statement with the MaxL Command Shell, but it is not embeddable in Perl. For Perl, use connect.

ALTER APPLICATION

Change application-wide settings. Permission required: Application designer.

Examples

alter application Sample set minimum permission read;

Grants all users read access to all databases in the Sample application. Users can retrieve data values and run report scripts.

alter application Sample disable commands;

Prevents all users from making requests of databases in the application. Use this statement before performing application-wide update and maintenance operations.

alter application Acme set variable Current_month July;

Assigns the string value July to the substitution variable "Current_month." "Current_month" may be referenced by calculations in the Acme application.

Note on Semicolons: Examples in this document follow the syntax requirements of the MaxL Command Shell. Semicolon statement-terminators are required by the shell, but not by the MaxL language. Therefore, terminate statements with semicolons when using the MaxL Command Shell, but not when issuing MaxL statements via Perl functions.

ALTER DATABASE

Change database-wide settings. Permission required: Database designer.

Examples

alter database Sample.Basic enable cache_pinning;

Locks database cache pages in physical memory so that the operating system will not page them out while the database is still using them.

alter database Sample.Basic disable two_pass_calc;

Prevents recalculation (after a default calculation) of members tagged as Two Pass.

alter database Sample.Basic set disk volume sample.basic.c file_type index;

Changes the storage settings for Sample Basic so that the alternate disk volume specified as the C: drive stores only index files.

alter database Sample.Basic set lock_timeout after 120;

Changes the number of seconds to wait for blocks to be unlocked. If a transaction request is made which cannot be granted in 120 seconds, the transaction is rolled back until a lock can be granted.

DISK VOLUME

Add a disk volume definition if you want to allocate storage across multiple volumes, or restrict space used on a volume. You can allocate storage for index files, data files, or both. If no disk volume is defined, data and index files are stored in the database directory (for example, $ARBORPATH/app/sample/basic).

File_size is the maximum size an index or data file may attain. Default = 2G; minimum = 8192K (8M).
Partition_size is the maximum amount of disk space allocated to the volume. Default = unlimited.

ALTER GROUP

Rename a group or change the comment that describes the group. Permission required: create_user.

Examples

alter group NewGroup rename to group Recruit;

alter group Recruit comment 'This group is for the newly hired';

ALTER SYSTEM

Change the state of the Hyperion Essbase server. Start and stop applications, delete application log files, manipulate system-wide variables, manage password and login activity, disconnect users, and shut down the server.

Notes

Specifying 0 for any set clause turns that login management parameter off.
Setting either or both session idle parameters to 0 turns off automatic logging out of users.

Examples

alter system unload application Sample;

Stops the Sample application, if it is currently running.

alter system logout user Fiona;

Disconnects Fiona from any databases to which she is connected.

alter system set password_reset_days 10;

Specifies that all users will be prompted after 10 days to change their passwords. The day count for any user is reset when the user changes the password or is edited or re-activated by a supervisor.

ALTER USER

Add or remove a user to or from a group. Rename a user. Change the comment that describes a user. Enable or disable a user account. Change a user's password, or specify whether it should expire. Permission required: create_user.

Examples

alter user Fiona add to group Newhires;

Assigns Fiona to a group called Newhires. This gives Fiona the same minimum privileges as those defined for the group.

alter user Fiona enable;

Enables user Fiona to log in again.

alter user Fiona set password_reset_days immediate;

Requires the user Fiona to change her password at the next login.

CREATE APPLICATION

Create or re-create an application, either from scratch or as a copy of another application on the same system. Permission required: create_app. APP-NAME must consist of 8 or fewer characters. Avoid spaces and special characters when naming applications and databases.

Examples

create application Sample comment 'This is a test application.';

Creates a new application called Sample with an associated comment.

create application Newsamp as Sample;

Creates an application called Newsamp which is a copy of the application Sample.

create or replace application Sample;

Creates an application called Sample. If an application named Sample already exists, it is overwritten.

CREATE CALCULATION

Create, replace, or copy a stored calculation.

Examples

create or replace calculation sample.basic.Accts
'SET UPDATECALC ON;
CALC DIM(Accounts);'
;

Creates a calculation named Accts that is associated with sample.basic.

create calculation sample.basic.Accts2 as app.db.Accts

Creates a calculation named Accts2 on sample.basic that is a copy of another database's calculation named Accts.

CREATE DATABASE

Create or re-create a regular or currency database. Optionally create the database as a copy of another database on the same system. DBS-NAME must consist of 8 or fewer characters. Avoid spaces and special characters when naming applications and databases.

Privilege required: Application designer.

Examples

create or replace database Sample.Basic comment 'This is a test.';

Creates a database called Basic within the Sample application. If a database named Basic within the Sample application already exists, it is overwritten.

create database Sample.New as Sample.Basic;

Creates a database called New within the Sample application that is a copy of the database Basic within the Sample application.

create currency database Sample.Interntl;

Creates a currency database called Interntl within the Sample application.

CREATE FILTER

Create or re-create a database security filter, either from scratch or as a copy of another filter on the same system. Filters control security for database objects. Use grant to assign filters to users and groups. Privilege required: Database designer.

MEMBER-EXPRESSION must be enclosed in single quotation marks. It can be a comma-separated list.

Examples

create filter sample.basic.filt1 read on 'Jan, sales', no_access on '@CHILDREN(Qtr2)';

Creates a filter to restrict privileges to Sample Basic as follows: gives read-only access to the intersection of Jan and sales (sales data for January only); blocks access to children of Qtr2 (April, May, and June).

create or replace filter sample.basic.filt1 read on 'Sales, @ATTRIBUTE(Bottle)';

Creates a filter (or changes an existing filter) to restrict privileges to Sample Basic as follows: gives read-only access to sales data for products packaged in a bottle (product base dimension members associated with the Bottle attribute member).

CREATE FUNCTION

Create or re-create your own registered Hyperion Essbase function, using a Java method.
Minimum permission required: Database designer.
Process to follow:

Develop the functions in Java classes.
Use MaxL's create function to register them in the Hyperion Essbase calculator framework.
You can now use the functions in the same way that you use the standard Hyperion Essbase calculation functions.

To use this feature, you must have selected to install the Java Virtual Machine with Hyperion Essbase.

To create a global or system-level function, use a single name for FUNC-NAME. For example, '@COVARIANCE'.
To create a local or application-level function, use MaxL's double naming convention for FUNC-NAME. For example, Sample.'@COVARIANCE' The second token must be enclosed in single quotation marks because it contains a special character.

Example

CREATE FUNCTION '@COVARIANCE' AS 'com.hyperion.essbase.calculator.Statistics.covariance' SPEC '@COVARIANCE (expList1, expList2)' COMMENT 'computes covariance of two sequences given as expression lists';

CREATE GROUP

Create or re-create a group, either from scratch or as a copy of another group.

Examples

create group Level_1 as Newhires comment 'Copy of Newhires';

Creates a group called Level_1 that is a copy of the existing group Newhires.

CREATE LOCATION ALIAS

Create on the database a location alias identifying a host name, database, user name, and password. Location aliases provide a shorthand way of referencing login information for other Hyperion Essbase databases. Permission required: Database designer.

Examples

create location alias EasternDB from Sample.Basic to East.Sales at Easthost as Fiona identified by sunflower;

Creates a location alias called EasternDB on Sample.Basic which represents the following login information:

server = Easthost
application = East
database = Sales
user name = Fiona
password = sunflower
Location aliases are used by the @XREF function for cross-database calculations.

CREATE MACRO

Create or re-create your own Hyperion Essbase macro using a Java method.
Minimum permission required: Database designer.

You create a macro as your chosen combination of existing calculation functions or macros. To use this feature, you must have selected to install the Java Virtual Machine with Hyperion Essbase.

To create a global (system-level) macro, use a single name for MACRO-NAME. For example, '@COVARIANCE'.
To create a local (application-level) macro, use MaxL's double naming convention for MACRO-NAME. For example, Sample.'@COVARIANCE'.

Example

create macro Sample.'@COVARIANCE'(single, single) as '@COUNT(SKIPMISSING,@RANGE(@@S))' spec '@COVARIANCE (expList1, expList2)' comment 'Computes covariance of two sequences given as expression lists';

CREATE PARTITION

Create a partition definition between two databases. Permission required: Database designer at both sites. The first DBS-NAME is the local database, and the second DBS-NAME is the remote database. Creating a partition to the remote site means the current database is the source. Creating a partition from the remote site means the current database is the target.

Examples

create or replace replicated partition sampeast.east
	area '@IDESC(East), @IDESC(Qtr1)'
to samppart.company at localhost
as partitionuser identified by 'password'
	area '@idesc(East) @idesc(Qtr1)';

CREATE USER

Create or re-create a user, either from scratch or as a copy of another user. Optionally create the user as a member of a group.

Examples

create user Fiona identified by sunflower;

Creates a user called Fiona with the password sunflower.

create user Guest identified by 'password' member of group Visitors;

Creates a user called Guest with the password password, and adds Guest to the group called Visitors. Quotation marks are required because password is a MaxL keyword.

create or replace user Guest identified by 'password' as RecycleMe;

Creates a user called Guest as a copy of an existing user called RecycleMe. If Guest already exists, it is overwritten.

DISPLAY APPLICATION

View information about current application-wide settings.

Examples

display application;

Displays information about all applications on the system.

display application Sample;

Displays information about the Sample application.

DISPLAY CALCULATION

View a list of stored calculations on the system.

Examples

display calculation;

DISPLAY DATABASE

View information about current database-wide settings.

Examples

display database;

Displays information about all databases on the system.

display database Sample.Basic;

Displays information about the Sample.Basic database.

DISPLAY DISK VOLUME

View a list of currently defined disk volume definitions.

Examples

display disk volume;

Displays all (if any) disk volumes defined on the system.

display disk volume sample.basic.vol3/hyperion/essbase;

Displays information about a particular disk volume definition on Sample.Basic.

DISPLAY FILTER

View a specific filter or a list of all filters on the system.

Examples

display filter;

Displays the names of all filters on the system.

DISPLAY FILTER ROW

View the filter rows which define database access within a specific filter or all filters.

Examples

display filter row sample.basic.filt2;

Displays the row-by-row definition of a filter named filt2 which is associated with Sample.Basic.

DISPLAY FUNCTION

View a list of custom-defined functions available to an application. You must specify an application name. If MaxL shows no application name next to a function in the display output, then that function is global (system-wide).
Minimum permission required: read.

Examples

display function sample;

Displays all custom-defined functions associated with the application Sample.

DISPLAY GROUP

View a specific group or a list of all groups on the system. To view group membership information, use display user.

DISPLAY LOCATION ALIAS

View a specific location alias or a list of all location aliases defined on the system.

Examples

display location alias all;

Displays a list of location aliases defined on the system.

DISPLAY MACRO

View a list of custom-defined macros available to an application. You must specify an application name.
Minimum permission required: read.
If MaxL shows no application name next to a macro in the display output, then that macro is global (system-wide).

Examples

display macro sample;

Displays all custom-defined macros associated with the application Sample.

DISPLAY PARTITION

View information about a specific partitioned database or all partitioned databases on the system.

Examples

display partition all;

Displays information about all partitioned databases defined on the system.

DISPLAY PRIVILEGE

View a list of privileges, calculations, or filters held by users or groups.

display privilege user Fiona;

Displays the privileges user Fiona has on each database object, including any calculations or filters granted to Fiona.

display privilege group;

Displays privileges held by all groups on the system to all applications and databases on the system.

DISPLAY SYSTEM

View information about current system-wide settings.

Examples

display system;

Displays current password and session management settings.

DISPLAY USER

View a specific user or a list of all users defined on the system. View group membership information.

Examples

display user;

Displays all users on the system and shows whether they are logged in, whether their accounts are enabled, and whether their passwords are set to expire.

display user in group;

Displays the membership information of all groups on the system.

display user in group big_group;

Displays the membership information for a group called big_group.

DISPLAY VARIABLE

View a list of substitution variables defined on the system.

Examples

display variable;

Displays a list of susbstitution variables on the Hyperion Essbase server.

DROP APPLICATION

Delete an empty application from the system. To remove an application with databases, use cascade. To remove an application that has locked objects in a constituent database, you can use force. Minimum permission required: designer.

DROP CALCULATION

Delete a stored calculation from a database. Minimum permission required: designer.

Examples

drop calculation Sample.basic.calcname;

Deletes a calculation from Sample.basic.

DROP DATABASE

Delete a database from the sytsem. Minimum permission required: Database designer. If the database has outstanding locks, clear them first, or use force to drop with locks.

Examples

drop database Sample.Basic force;

Deletes the database Sample.Basic, even if client users have outstanding locks on Sample.Basic.

DROP FILTER

Delete a security filter from the database. Minimum permission required: Database designer.

Examples

drop filter sample.basic.filter1;

Deletes the filter called filter1 from the sample.basic database.

DROP FUNCTION

Delete a custom-defined function from the application. Minimum permission required: Database designer.

To drop a local function, Essbase requires the application to be restarted. To drop a global function, Essbase requires all loaded applications to be restarted. Otherwise, if you try to re-create the function, an error message states that the function already exists: you will have to unload and load the application yourself using alter system.

To let MaxL restart the application, use immediate when dropping a function. For a local function, this will restart the application. For a global function, all loaded applications will be restarted.

Examples

drop function sample.'@COVARIANCE' immediate;

Deletes the function called @COVARIANCE from the Sample application.

DROP GROUP

Delete a user group from the system. Users belonging to the group are not deleted. Minimum permission required: create_user.

Examples

drop group big_group;

Deletes the group called big_group from the system.

DROP LOCATION ALIAS

Delete from the database a location alias identifying a host name, application, database, user name, and password. Minimum permission required: database designer.

Examples

drop location alias Main.Sales.EasternDB;

Drops the location alias called EasternDB in the Main.Sales database.

DROP MACRO

Delete a custom-defined macro from the application. Minimum permission required: Database designer.

To drop a local macro, Essbase requires the application to be restarted. To drop a global macro, Essbase requires all loaded applications to be restarted. Otherwise, if you try to re-create the macro, an error message states that the macro already exists: you will have to unload and load the application yourself using alter system.

To let MaxL restart the application, use immediate when dropping a macro. For a local macro, this will restart the application. For a global macro, all loaded applications will be restarted.

Examples

drop macro sample.'@COVARIANCE' immediate;

Deletes the macro called @COVARIANCE from the Sample application.

DROP PARTITION

Delete from the system a partition definition between two databases. Database designer privilege for each database is required.

Examples

drop replicated partition Samppart.Company from Sampeast.East at EastHost;

DROP USER

Delete a user account from the system. Minimum permission required: create_user.

Examples

drop user Fiona;

Deletes the user Fiona from the system.

EXECUTE CALCULATION

Execute a stored calculation, the stored default calculation (determined by alter database), or an anonymous (non-stored) calculation string.

Minimum permissions required:

For stored calculations (CALC-NAME): Granted access to the calculation.
For anonymous calculations (CALC-STRING): Database designer privilege.
For default calculation: execute privilege.

Examples

execute calculation Sample.basic.calcname;

Calculates Sample.Basic using a stored calculation file assocatied with that database.

execute calculation 
  'SET MSG ERROR;
   CALC ALL;'
on Sample.basic;

Calculates Sample.Basic using an anonymous (unstored) calculation string.

EXPORT

Export all data, level-0 data, or input-level data, which does not include calculated values. Export files are stored in the $ARBORPATH/app directory on the server. To use Report Writer, export the data using a report file.

To export data in parallel, specify a comma-separated list of export files. The number of threads Hyperion Essbase uses depends on the number of file names you specify.

To export data in column format, use the optional "in columns" grammar.

Note: You can use an export statement in MaxL scripts and the MaxL Command Shell, but you cannot embed it in Perl.

Example

export database sample.basic data to data_file 'D:\fileout','D:\fileout2','D:\fileout3';

Exports data concurrently to a list of file names.

export database sample.basic input data
to data_file 'exp_input.exp';

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

Note:In the path to the report file in the above example, double quotation marks are used to allow variable expansion, and single quotation marks are required because there are special characters in the file name.

GRANT

Grant a permission, a filter or a stored calculation to a user or a group.

Granting permissions:
At each level (system, application or database) existing roles are replaced. However, the built-in privileges create_user and create_application are not replaced.

Granting filters:
There may be only one filter per user per database. Therefore, granting a filter replaces any filters the user may already have on that database.

Granting calculations:
A user or group may have any number of calculations per database. Therefore, granting a calculation adds it to the user or group�s list of calculations. Grant execute any gives the user or group permission to execute all calculations, including the default calculation.

Examples

grant no_access to NewGroup;

grant supervisor to Fiona;

grant designer on application Sample to Fiona;

grant read on database Sample.basic to Fiona;

IMPORT

Import data or dimensions from text data files, with or without a rules file. To import from a relational source, you must connect as the relational user name, and use a rules file. Note: in some cases, import will generate an error log file, essmsh.err, in the current directory.

Note: You can use an import statement in MaxL scripts and the MaxL Command Shell, but you cannot embed it in Perl.

Example

import database sample.basic dimensions
from data_file '/data/calcdat.txt'
using rules_file '/data/rulesfile.rul';

Windows example

REFRESH REPLICATED PARTITION

Refresh the current replicated-partition database target from the remote (second DBS-NAME) source partition. Database designer privilege for each database is required.