Chapter 8 [ 295 ] EssCmd commands and categories There are over 120 distinct EssCmd commands that do everything from running report scripts and calculation scripts to database outline maintenance and security. The following screenshot shows a complete listing of available EssCmd commands: The command list can be rather intimidating to look at but we assure you that all of the EssCmd commands are easily understandable and simple to use. To help you become familiar with the commands and their function, Essbase also groups them by category. The basic categories of the EssCmd commands are as follows: • Using EssCmd: These commands are used to log in and out of EssCmd, view command lists, pause EssCmd execution, and direct command script output. • Application and database administration: These commands are used to perform database creations and routine administration, and to get information about existing applications and databases. • User/Group security: Use these commands to perform user ID and access group maintenance and administration. • Security lters and locks: These commands can list, copy, and rename database security access lters, and also remove database locks. This material is copyright and is licensed for the sole use by Paul Corcorran on 5th July 2009 8601 ave. p #1, , lubbock, , 79423 Download at Boykma.Com Automating your Essbase Cube [ 296 ] • Database objects: These commands are used to list database objects and their lock statuses, if any. Also, you can copy and rename database objects, and view or remove URLs, cell notes, or database partitions linked to the database. • Outline/Attribute information: Use these commands to view outline member information, member attribute information, current attribute naming specications, and to view the outline paging information. • Dimension building: This group of commands can be used to build one or more dimensions from data les or SQL sources. You can build multiple dimensions incrementally and decide how you want the database restructured after the dimension build is complete. • Data loading, clearing, and exporting: Use these commands to load your data from les or from individual records or to clear all data from a database or to export and import data to and from text les. • Calculating: These commands can be used to run calc scripts, execute one or more calc strings, run or change the default database calculation, and view information about calcs associated with outline members. • Reporting: Use these commands to execute report scripts or to run one or more report strings individually. • Partitioning: This group of commands can be used to load or unload data from a database partition or even produce a text le version of a partition mapping. • Outline synchronization: These commands are actually used in conjunction with partitioned databases to keep the target database outline synchronized with changes made to the source database outline. • Error and log handling: Use these commands to set conditional or unconditional error branching from EssCmd scripts, redirection of process information output, specifying what level of detail messages are displayed in, and clearing the application log le when necessary. • Currency conversion information: These commands are used to get information about currency databases linked to the currently selected database. • Location aliases: These commands manage location aliases used in a distributed analytic services environment. Location aliases are names that are used in place of server addresses, applications, databases, user IDs, and passwords. This material is copyright and is licensed for the sole use by Paul Corcorran on 5th July 2009 8601 ave. p #1, , lubbock, , 79423 Download at Boykma.Com Chapter 8 [ 297 ] • Substitution variables: Use these commands to manage any substitution variables. Substitution variables are placeholders for information that changes regularly. Use them in calc scripts, report scripts, and the spreadsheet add-in to avoid hard coding. • Aliases: These commands manage and, display the values of alias tables for database outlines. Alias tables contain a listing of member names and their alternate names, or aliases. • Integrity and performance: These commands are used to check database statistics and validate databases against possible corruption. • Backing up: Use these commands to place one or more Application|Databases into Read Only mode in preparation for archiving or backup. Well, there you have it! In a nutshell you have all of the Essbase command script categories. For complete details on how to code each function and what task it performs please refer to the Essbase Administration Services Information Map that you access from the EAS Help menu pick. There you will nd a complete command list with specic details on how to code each function. Coding a basic EssCmd Even though you should no longer be writing new Essbase command scripts we would remiss if we did not at least go over the basics. The following instructions will guide you through writing a basic Essbase command script so you will have at least a working knowledge level in case you need it. Always remember EssCmd logging First and foremost, in any EssCmd script is the inclusion of script logging. A good output log is invaluable for helping to debug any problems. The rst line in any EssCmd script should be the OUTPUT command. This command toggles on or off the script logging and also allows you to specify where to put the log as shown here: OUTPUT 1 "c:\EssCmd.log"; /* The 1 specifies turning job log output on and then you code the log's location */ This material is copyright and is licensed for the sole use by Paul Corcorran on 5th July 2009 8601 ave. p #1, , lubbock, , 79423 Download at Boykma.Com Automating your Essbase Cube [ 298 ] Connecting to an Essbase server Obviously, you will need to be connected to an Essbase server to perform any tasks or functions. In EssCmd there are two ways to login to the server. If your script will only be accessing one specic Essbase database you can code your login command as follows: LOGIN ServerName userID Password appName dbName; This command will log you into a specic Essbase Application|Database, and you will need to log out before you can connect to another Application|Database. The appName and dbName parameters are optional however, and if you plan on performing tasks against several Application|Databases you would login like this: LOGIN hostNode userName password; SELECT appName dbName; The term hostNode refers to the specic server name or IP address of the Essbase server you wish to connect to. Using the LOGIN then SELECT method to login allows you to change the Application|Database at any time in your script by using another occurrence of the SELECT command. Your EssCmd script should now look like this: OUTPUT 1 "c:\EssCmd.log"; /* The 1 specifies turning job log output on and then you code the logs location */ LOGIN hostNode userName password; /* Connect to Essbase server */ SELECT appName dbName; /* Connect to specific application/database */ What about error checking Before we go too much further, we should stress the importance of error checking. Lucky for us the EssCmd library includes an IFERROR command that acts as a GOTO for errors. This can be very important if the next command in a script is dependent on the successful completion of the previous command. Having your script halt execution on an error can prevent all kinds of grief. It is a good idea to follow all commands in the script with the IFERROR command and you can add your error checking as shown: IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ :ERROR /* Script skips to here and resumes execution */ EXIT; /* In this case we exit the script */ This material is copyright and is licensed for the sole use by Paul Corcorran on 5th July 2009 8601 ave. p #1, , lubbock, , 79423 Download at Boykma.Com Chapter 8 [ 299 ] Once you have added your error checking, your edgling script should look like the script below: OUTPUT 1 "c:\EssCmd.log"; /* The 1 specifies turning job log output on and then you code the log's location */ IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ LOGIN hostNode userName password; /* Connect to Essbase server */ IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ SELECT appName dbName; /* Connect to specific application|database */ IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ *** Add functional commands here *** OUTPUT 3; /* Turns off script logging */ LOGOUT; /* Logs out the script and exits */ :ERROR /* On an error the script branches to here and resumes execution */ EXIT; /* In this case we exit the script */ Adding some functional commands So now you have an EssCmd script that when executed, will turn on logging, log in to a specied Essbase server, select a specied Essbase Application|Database, turn off logging, and log out, all the while checking for errors in the command execution. You now need to add some commands to the script which will actually do some work! How about if we load a specic Essbase application and database into memory? We will then run the default calculation script against that database. Next, we will unload the database and the application from server memory to conserve system resources. And nally, we will log out and the script will terminate. To the example script above, we want to add the following commands: LOADAPP appName; /* Loads the specified application into memory */ IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ LOADDB appName dbName; /* Loads the specified database into memory */ IFERROR "ERROR"; /* On an error the script will branch to the "ERROR" line */ This material is copyright and is licensed for the sole use by Paul Corcorran on 5th July 2009 8601 ave. p #1, , lubbock, , 79423 Download at Boykma.Com . July 20 09 8601 ave. p #1, , lubbock, , 794 23 Download at Boykma.Com Automating your Essbase Cube [ 298 ] Connecting to an Essbase server Obviously, you will need to be connected to an Essbase. for the sole use by Paul Corcorran on 5th July 20 09 8601 ave. p #1, , lubbock, , 794 23 Download at Boykma.Com Automating your Essbase Cube [ 296 ] • Database objects: These commands are used. licensed for the sole use by Paul Corcorran on 5th July 20 09 8601 ave. p #1, , lubbock, , 794 23 Download at Boykma.Com Chapter 8 [ 299 ] Once you have added your error checking, your edgling