Professional Documents
Culture Documents
Product Version: 5.0 SP2 and 4.2 SP5(?) Document Version: 2.0 Last update: March 14, 2007
Reference documentation
Introduction
EvDRE (Data Range Expansion) is a powerful and flexible WebExcel function that can be used to generate different kinds of OutlookSoft-based reports and schedules in Excel, all with one easy to use interface. EvDRE combines and extends the functionality of several other EV functions like EvGet, EvSnd, EvExp, EvNex, etc. While these older functions are still supported for backwards-compatibility of workbooks that some users may not want to re-design, we expect EvDRE to replace them in the greatest majority of situations. The main benefits of EvDRE are:
It is a do-it-all function, i.e. it can be used in many different situations, allowing the user to only learn one function to build all his reports and data entry schedules. In fact:
It can be used for both data retrieve as well as data send operations It permits to build static workbooks (without expansions) as well as dynamic workbooks (with expansions), or mixed-type workbooks, where some dimensions are defined statically (using hard coded members) and some others are dynamically expanded The expansions can be assigned to rows, columns, or both rows and columns simultaneously and it can also handle expansions across sheets It supports any number of nesting in the expansion of both rows and columns
It permits to build light workbooks that are faster to download and upload, because it does not require embedding a function in each sent or retrieved cell. It achieves this result by making an extensive use of cell ranges. A custom-built query optimization engine automatically decides the most efficient way to access the database to retrieve the requested data. In most cases this greatly improves the performance and scalability of reports and schedules, because, whenever possible, EvDRE reads base-level data directly from the SQL database, reducing the workload on the OLAP engine, and, when the use of SQL queries is not possible, it interrogates the OLAP cube using very efficient, dynamicallyoptimized MDX queries. It automatically builds in the worksheet a control panel that allows to easily identify all the parameters used by the function and their meaning It returns easy-to-understand error messages that allow the user to immediately isolate the source of a problem
Reference documentation
Quick start
Quick start
You do not need to have a deep knowledge of the features of EVDRE, to start using it. All you have to do, to build your first EVDRE report, is the following: In a clean WebExcel worksheet enter this instruction in the top leftmost cell: =EVDRE( ) Then hit the REFRESH button. You will be prompted a dialog box that asks you what dimensions you want in columns, what dimensions you want in rows and a few more details about your report. You may just take what is proposed by default (or make some simple adjustment), then hit Ok. Your first report will be automatically built in front of you, nicely formatted and populated with real data.
The syntax
Heres the syntax of the EVDRE function: = EVDRE ( ApplicationName, KeysRange [, ExpansionsRange]) The function uses two required and one optional parameter, as here below described: ApplicationName This is the name of the application from which to retrieve or where to send data. KeysRange This parameter points to a range of cells that in turn must contain the definitions of the key ranges of the report. The key ranges are other ranges that ultimately control the content of the individual cells of data. The keys range must have two columns and at least 6 rows, as later described. ExpansionsRange (optional) This is an optional range containing the definitions of the expansions (as many as desired) that must be performed by the function. This range, if existing, must have 7 rows and two (or more) columns, as later described. In the following example the ranges corresponding to the three EvDRE parameters are highlighted in yellow.
Reference documentation
The EvDRE function and its associated parameter ranges do not need to be in the same sheet; they could all be scattered across different sheets of the current workbook, if desired. This may allow sharing the same page key range with multiple instances of EvDRE within the same workbook, or simply hide in some other sheet the most technical parts of the function.
The first column (the RANGE column) contains the name of the ranges. The names are reserved keywords and must be spelled as shown here. Using a reserved name for each range allows EvDRE to make the content of this grid non-position-sensitive, and the ranges can be ordered in any sequence. The second column (the VALUE column) contains the definition of the range, i.e. it is a string defining a range of cells. Currently all 6 ranges must be included in the KeysRange. However, not all of them must have a value: only the ColKeyRange and the RowKeyRange are mandatory. All the others may be left blank, when not needed. All the ranges specified in the KeysRange, combined with some other WebExcel settings, contribute to define the content of each data cell, as later described.
Reference documentation
The keys range can also contain two additional, optional rows: one is an Options (or OptionsRange) field, where some options can be set, and another one is a SortRange field, defining a range of sorting parameters, as later described.
These definitions, if in conflict, take precedence from the lowest to the highest in the above list (The cell key, if existing, wins on the row key, that wins on the column key, that wins on the page key, etc.). The following example may help understand the mechanism. Here the EvDRE function placed in cell A1 populates the data range F7:G9 (in yellow) using these definitions:
The ENTITY, the CATEGORY and the VIEW (MEASURES) dimensions are controlled by the system current view. The RPTCURRENCY, the INTCO and the DATASRC are controlled by the PageKeyRange B4:B6 (in green) The TIME is set by column by the ColKeyRange F5:G5 (in magenta) The ACCOUNT is set by row by the RowKeyRange D7:D9 (in blue)
Following is a more detailed explanation of each key range as used by the function.
Reference documentation
ACTUAL BUDGET ACTUAL BUDGET 2004.OCT 2004.OCT 2004.OCT 2004.OCT PERIODIC PERIODIC YTD YTD
The above range (H2:K4) defines the category, time and view that should apply to the cells belonging to columns H, I, J and K respectively. The number of rows in the range must correspond to the number of dimensions for which the current view is column-specific.
Reference documentation
CASH EUR ACCREC EUR INVENTORY EUR CASH USD ACCREC USD INVENTORY USD
The above range (B10:C15) defines the account and currency that should apply to the cells belonging to rows from 10 to 15 respectively. The number of columns in the range must correspond to the number of dimensions for which the current view is row-specific.
where the Column and Row Key Ranges are in light green, the data range is show in red. The additional portions contained within the column and row key ranges (shown here in yellow) are the heading ranges for both the rows and the columns. These sections of the worksheet can be filled with Excel formulas or other EV functions that can come handy to retrieve the headings of the appropriate members or other relevant information. The heading ranges are not populated by data but are included in the expansion process, allowing for the replication of the content of these cells in the expanded columns or rows.
Reference documentation
Here is a visualization of all described ranges. Sometimes the headings ranges may be missing or may be placed to the right of the data range or even embedded in the body of the data range.
The definitions in the CellKeyRange work by an offset relative to the top-left corner of the data range. For this reason, in static reports, the CellKeyRange must be equal or smaller that the data range for which it redefines the current view for some cell. The overriding cells are the cells in the CellkeyRange with a value different from blank. The overridden cells are the corresponding cells in the Data range. In the above example they are:
Cell F8, that reads account CASH instead of account ACCREC Cell G7, that reads account INVENTORY of period 2005.JAN, instead of account CASH of period 2005.FEB Cell G9, that reads period 2005.JAN instead of period 2005.FEB
Reference documentation
For obvious reasons, in the majority of cases the cell key range is hidden to the users (together with the definitions of the other ranges), as it is just part of the report parameters. In presence of expansions, the CellKeyRange can still be used, but its meaning and behavior change, as later described.
Sending data
EVDRE will only try to send the cells of the send range which have changed value since the last refresh action. This also includes values calculated by Excel formulas, allowing the users to define Excel-based logic calculations. The values are sent up to the last decimal place, even if a rounding format is applied. Text values are not sent. Values deleted using the Delete key will be sent as zeros. Changing the current view and trying to send the data on the screen without first performing a refresh is currently not allowed (a No data to send message will appear). This possibility will probably be considered for an upcoming release.
Reference documentation
In the static input schedule shown above, a GetOnlyRange spanning all cells marked in blue in the data range will make so that any value entered in those cells will be ignored during a SEND action. Note that, in the above case, the get-only cells only include calculated members; as such, they would be rejected by the posting engine anyway, if sent. A different (probably more meaningful) case would be represented by a set of input cells that for some reason should only be read, and not modified from the current schedule. When the workbook is defined as a report, the GetOnlyRange parameter is redundant and, as such, ignored.
When the FormatRange cell is left blank, the format of the data range is automatically derived from the format of the left-most and top-most cell of the data range to be expanded.
10
Reference documentation
To make the job easier, we have devised a simple function called EvRNG( ) that comes to the rescue. What it does is to take one or more ranges as parameters, and returns the entered range definitions as text. All that the user has to do, wherever a cell requires a range as value, is to enter an EvRNG function in that cell, mark the appropriate range with the mouse and hit enter. Also, in order to visualize the position of the range in the sheet, the user can put the cursor on the cell containing the EvRNG function then hit F2 and Excel will make the range clearly identifiable. In the following example the user hit F2 on cell E2 to highlight the range B4:B11
A very important side benefit of the EVRNG function is the following: during an expansion the parameters of the EVRNG function adjust themselves automatically, when the body of the report redefines the number of rows and columns of the report. This self-adjustment, which comes for free as a native behavior of Excel functions, allows EVDRE to retain the consistency of its parameters with the content of the report, basically permitting the user to expand multiple times the same report, without ever breaking the definitions of its design. In other words, using EVRNG in these cells is not just a nice option but a requirement, whenever the function uses expansions.
11
Reference documentation
There is no theoretical limit to the number of dimensions that can be defined in these ranges. The only (obvious) constraint is that no dimension can be specified in BOTH ranges (a dimension may only be defined in rows or in columns). Remark: the dimensions must be assigned a consistent position in the ranges. In the above example, all columns of the first row of the ColKeyRange must define a category. It is not possible, for example, to swap the position of 2005.FEB with BUDGET (unless ACTUAL and 2005.JAN are also swapped accordingly).
12
Reference documentation
leave at least one blank cell in the column or row keys and the corresponding column or row will be left untouched by the function, when the data are retrieved. In the following example the RowKeyRange has been defined as one single range (D5:D18). However, the keys in D9, D10 and D18 have been left blank. In this way the refresh operation has not tried to retrieve a value for the corresponding rows in the data range. In particular, the excel formulas existing in row 9 and row 18 have not been overwritten, while row 10 has been left blank.
13
Reference documentation
This feature is disabled by default, but can be turned on by the option ShowComments (see the list of valid options detailed later in this document).
2005.jun
Note that this feature can be activated assigning multiple ranges to the same EVRNG function. In the above example the content of the ColKeyRange cell is: =EVRNG(H13:J13,H19:J19) The maximum number of parameters that can be assigned to any Excel functions and EVRNG is no exception - is 30 (it will be bigger in Excel 2007, but thats a different story).
14
Reference documentation
A first column defining the name of the expansion parameter. As many columns as the number of desired expansions. For example if the user wants 2 expansions in columns and 3 expansions in rows, these columns will be 5. 7 rows, each one defining one parameter for each expansion
Here below is an example of a report containing one expansion in rows and one expansion in columns.
As it can be easily seen here, the expansion range is made up of 7 rows, each one defining a specific parameter for each expansion. The supported parameters are:
ExpandIn
This parameter can have the value COL, ROW or SHEET, indicating whether the expansion is to be performed on the columns or on the rows, or across sheets of the workbook.
Dimension
The name of the dimension for which a dynamic set of members should be generated.
MemberSet
Here the user can define the set of members to expand for the selected dimension. This field supports three different syntaxes: 1. A list of comma-delimited members, basically hard coded in the field Example:
15
Reference documentation
CASH, ACCREC, INVENTORY 2. A keyword indicating what members in the hierarchy to retrieve. The valid keywords are: o o o o o o o o o o o o o o MEMBERS [, PARENTAFTER] BASMEMBERS BAS DEP ALL [, PARENTAFTER] SELF LDEP(n) LALL(n) LBAS(n) LMEMBERS(n) LBASMEMBERS(n) NOEXPAND SKIP {blank} All members in the dimension All leaves in the dimension All leaves below current member(*) All children of current member(*) All descendants of current member(*) The current member(*) All descendants down n levels All descendants down n levels All leaves down n levels All members with level n or less All leaves with level n or less Make the current dimension static Make all dimensions in the axis static Expand a set of no members (suppress axis)
(*) By current member we here mean the member selected in the page key range or in the current view. These keywords can be combined in a comma-delimited list (example: DEP, SELF). The list can also include hard-coded members (example: CASH, ACCREC, BAS, SELF). The keywords MEMBERS and ALL can be combined with a PARENTAFTER option, which will place the parent members after their children instead of before (the default behavior). Defining the MemberSet as SELF corresponds in doing an expansion on the current member. Leaving the MemberSet blank is the equivalent of suppressing the expansion altogether (yes, there is a difference). The keywords BAS, LBAS, DEP, LDEP, ALL and LALL can be assigned an explicit current member different from the one specified in the page key range (or the current view), using the following syntax: BAS(someparent) DEP(someparent) ALL(someparent) LBAS(n, someparent) LDEP(n, someparent) LALL(n, someparent) Examples: BAS(TotalAssets) DEP(2005.Q1) ALL(Worldwide2) LBAS(3,TotalAssets) LDEP(2,2005.TOTAL) LALL(3,Worldwide2)
16
Reference documentation
The Level-based keywords (LBAS, LDEP, LALL, LMEMBERS and LBASMEMBERS) also support a third parameter Y (or Yes) which will make them generate only the list of members of the selected level, skipping the members of all intermediate levels. Example: LDEP(2,2005.TOTAL) will give all quarters and all months of 2005 LDEP(2,2005.TOTAL, Y) will give only all months of 2005
3.
A filter criteria based on one or more properties in the dimension Examples (valid for the ACCOUNT dimension): ACCTYPE = INC GROUP=Balance Sheet AND CALC=Y ELIMACC<> A pop-up dialog can be activated to facilitate the construction of a filter for a given dimension, by just right clicking on the related cell.
Remarks:
The value of the property must be enclosed in double quotes The criteria can be equal (=) or different from (<>) Multiple criteria can be combined with the AND or the OR operator Parentheses are currently NOT supported when combining multiple criteria Filters based on properties CAN be combined with hard-coded members or other keywords like BAS, etc. The expressions are NOT case-sensitive
Following is a valid example of a member set definition for the ENTITY dimension:
17
Reference documentation
Wordwide1, SELF, BAS(Sales) AND CURRENCY<>EUR Note: Member sets can contain NULL fields, like in the following example: MemberSet: Cash, AccRec, , Banks, AccPay
Such set of members will generate a BLANK row (or column) between the AccRec and the Banks accounts, when expanded. The NOEXPAND keyword may be used to convert an expanded dimension into a static one. In this case the member keys may be typed directly in the key range. In the following example the account ACCREC has been typed in the first row of the rowkey range, then the expansion has been triggered.
Suppress (optional)
By setting this parameter to Y (Yes) for any ROW expansion, it will be possible to suppress all ROWS retrieving empty values in all columns. Similarly, by setting this parameter to Y (Yes) for any COL expansion, it will be possible to suppress all COLUMNS retrieving empty values in all rows. More options for this parameter are explained below
Insert (optional)
Setting this parameter to Y (Yes) for any ROW expansion will allow the user to perform a runtime insertion of a suppressed row, after the expansion. With this setting, all the user needs to do is to right-click on the KEY or HEADING of the row where the insertion should take place and select the EVDRE: Insert member option from this dialog:
18
Reference documentation
The following dialog will appear, and the user will be able to pick the keys for a new record to insert:
Important remark: the behavior of the pop-up screen is controlled by the position of the Y: only the dimensions where the Y was placed (in our example the INTCO dimension) will have the member selectable from a list box. Those of the other dimensions will be restricted to the value they have on the row from which the insert action was triggered (In our example the ACCOUNT will be the one of the current row (ICACCREC), and cannot be changed from the pop up dialog, while the INTCO can).
While very rarely used, the insert mechanism can also be activated on COLUMN keys, enabling the user to insert on the fly some new column into the sheet. The insert parameter Y may also be replaced with an explicit set of members that are valid for insertion. The set may be defined using the same syntax available in the MemberSet fields (comma-delimited list, BAS, DEP,etc.) Important remark: currently the user might define a (suppressed) expansion on one set of members (like Cash, AccRec, Inventory) but at the same time allow for the insertion of a different set of members (like Banks, AccPay, OtherLiabs). While such inconsistency is not prevented by the product, it is a strongly discouraged practice, as the user might end up sending values to cells he does not have on the screen, without knowing if some other value already exists in the database for these cells. Basically, it is important to keep the member set in synch with the list of insert-able members.
19
Reference documentation
When a formatted member set range has been defined, the insert action will automatically trigger the insertion of the entire set. In the following example the INSERT option has been activated only on the ACCOUNT members. When an account is selected (EXTSALES in the example), the entire block of intercompany members is automatically inserted.
Note that this behavior can be disabled if the INSERT option is also activated in the dimension using a formatted range (INTCO). In such case the user will be also allowed to select individual inter-company members, even if the INTCO range is defined using a formatted range. Note also that the automatically insertion of the entire set will NOT be activated if the member set is not formatted, i.e. if the set is defined with a one-column range (or, obviously, if it is directly defined in the MemberSet field).
20
Reference documentation
In the following example a BeforeRange and an AfterRange have been defined for the inner ROW expansion. The corresponding ranges have been inserted before and after each instance of such expansion.
21
Reference documentation
Important remarks:
The before and after ranges can be considered templates that the user designs, placing them anywhere in the sheet (possibly in a non-visible portion) that the expansion process will automatically insert into the body of the report. The ROW ranges (like those shown in the above example) will be placed horizontally starting from the FIRST column of the ROW HEADINGS range. Similarly, COLUMN ranges will be placed vertically starting from the FIRST row of the COLUMN HEADINGS range. The FORMAT and the FORMULAS, if defined, will be copied for the entire range. The VALUE will only be copied for the portion relating to the headings (the orange and red cells). In the keys where the range is inserted the function will automatically place the placeholder EV_AFTER (or EV_BEFORE). A ROW before- or after- range can also be composed of more than one ROW (like in the example above). Similarly, a COLUMN range can also be composed of more than one COLUMN. The above example only contained an expansion of ROWS. In case there is also an expansion of COLUMNS, the portion of the ROW ranges that falls inside the DATA RANGE only needs to be defined for ONE COLUMN. The column expansion will take care of duplicating that portion for all expanded columns. Here below is an example that shows how the blue and green portions of the before and after ranges have been expanded across the columns.
22
Reference documentation
The same rule applies in case the before and after ranges are defined for the COLUMN expansion: In case of a COLUMN before- or after- range coexisting with an expansion of ROWS, the portion of the COLUMN ranges that falls inside the DATA RANGE only needs to be defined for ONE ROW.
A special instruction EVSUM can be placed in the data range portion of a before- or after- range. When the expansion is performed, this keyword will be automatically turned into an Excel formula that calculates the sum of the members of the related expansion.
23
Reference documentation
The following example clarifies the mechanism. This sheet (captured with the formula view option turned on) shows how the EVSUMs in row 3 have been expanded into correct Excel SUM( ) formulas in rows 13 and 20.
EVSUMs can be nested together with their related before- or after- ranges. The following example shows a case of nested EVSUMs in row after ranges for two dimensions (account and entity).
24
Reference documentation
A newer variation of the EVSUM keyword is the EVSUB keyword. This keyword has a similar behavior as EVSUM, but it provides more flexibility to the mathematical operations being available for use in the expanded range. The EVSUB basically inserts the Excel function SUBTOTAL (instead of the SUM or SUMIF functions) in the appropriate cells, with the possibility to pass to it an identifier of the type of mathematical operation the user wants to be performed on the range of cells. For example, the instruction EVSUB(2) will insert the Excel function SUBTOTAL(2,{range}) in the sheet, and the function will return the number of elements in the {range} (using the COUNT operation, as triggered by the value 2 of the identifier). Passing no parameter to EVSUB will correspond to passing a 9, which represents the SUM operation. Here is an excerpt of the Excel documentation describing the SUBTOTAL function: Syntax = SUBTOTAL(function_num, ref1, ref2, ...) Function_num is the number 1 to 11 (includes hidden values) or 101 to 111 (ignores hidden values) that specifies which function to use in calculating subtotals within a list. Function_num Function_num Function (includes hidden values) (ignores hidden values) 1 101 AVERAGE 2 102 COUNT 3 103 COUNTA 4 104 MAX 5 105 MIN 6 106 PRODUCT 7 107 STDEV
25
Reference documentation
8 9 10 11
The expansion has basically replicated the sheet defining the expansion in several sheets (one sheet per expanded member), generating a book of reports for the desired set of members. The generated sheets will be named after the member being expanded in the sheet. The page key defining the page member of the sheet dimension will also contain the hard coded ID of the current member. Technically speaking, each of the resulting tabs contains a replica of the starting EVDRE function, where the ENTITY member specified in the PAGEKEY is the (hard-coded) member ID associated with the current sheet. It is important to remark that the starting sheet defining the expansion will become the first sheet of the expanded set. As a result, also the starting sheet will have the entity ID hard-coded in the page key, even if initially it contained a reference to the current view (by the use of EVCVW, for example) For the above reason, the member set defining the sheet expansion cannot be specified as relative to the content of the page key (because it will become hard-coded), otherwise the workbook will not be re-usable for further expansions on different current views (of the dimension expanded in SHEET). To overcome this limitation, the member set of the sheet expansion can be either self-defined (with something like BAS(Europe) or CURRENCY=EUR) or made relative to what defined in the current view bar by pointing to some other cell in the sheet.
26
Reference documentation
The following screen shot shows how the above example has been designed, in order to make it re-usable for other current views. The EVCVW function for the ENTITY has been entered in a separate cell, and the member set instructions point to such cells to define the expansion rule.
Here is a view of the formulas existing in the sheet: cell D10 contains the EVCVW function, and cell D16 point to cell D10 to define things like DEP(SalesEurope) and the like.
Note that the following restrictions apply, when the expansion is performed across sheets: There must be only one EVDRE function in the sheet defining the expansion Only one dimension can be expanded across sheets (no nested SHEET expansions) The beforeRange and the AfterRange parameters for the SHEET expansion are ignored The Insert parameter for the SHEET expansion is ignored
27
Reference documentation
Sorting
Sorting
The Keys range of an EVDRE function may contain an optional range called SortRange, pointing to a range of cells defining how the rows of the report should be sorted. This range must be made of 4 columns and 4 rows as shown in the example here below.
The first column of such range must contain the name of the sorting parameter and the remaining 3 columns will define up to 3 possible sorting methods (the limit of 3 is what Excel natively supports in its current version). The first parameter (column) may contain the following: A column identifier (for example J), indicating the column on which the sorting must be based A {dimension}.{property} identifier (for example ENTITY.CURRENCY) indicating that the rows must be sorted according to the alphabetical order of the value of some property of a given dimension
The second parameter (order) specified the order of the sorting and it can be any word beginning with D (for Descending) or A (for Ascending). A blank field will default to ascending. Here below we show the result of the simple sorting definitions used in the above sample (sort rows on column J in Descending order).
28
Reference documentation
Sorting
The third and fourth parameters (BeforeRange and AfterRange) can be used to define a range of cells that should be inserted in the report above (BeforeRange) or below (AfterRange) each change of value in the sorting criteria. In the following example we demonstrate the use of an AfterRange applied to a report sorted by the CURRENCY of the entities.
In the definition of the AfterRange the keyword %KEY% has been used. This keyword returns the value of the sorting element (the currency) for which a break total is being inserted. The EVSUB keyword has also been used in the data cell to create subtotals by currency.
29
Reference documentation
Sorting
It is important to remark that in the above example the sorting on the currency of the entities has been performed without the need to retrieve in the sheet the value of the currency property. Everything has been taken care of automatically by the function. It must also be noted that the sorting action is performed after the data have been refreshed, even if NO EXPANSION has been performed. If before- or After-ranges have been defined on the sorting criteria, these ranges will be automatically removed from the report and re-applied to its content after the data have been refreshed. This will also happen if no EXPANSION has been triggered.
30
Reference documentation
This wizard will initially propose to build a report containing one expansion for the columns using the TIME dimension and one expansion for the rows using the ACCOUNT dimension. These settings will be modifiable at will dragging-and-dropping around the desired dimensions or using the appropriate movement arrows. An appropriate member set for the selected expansions will be proposed. The wizard will also permit to optionally generate a FORMAT range and a SORT range. Hitting the Include FORMAT Range checkbox will offer the possibility to have a default formatting style generated automatically, or to import the style from some predefined workbook (either local or server based).
31
Reference documentation
(See below in the advanced formatting section for a complete explanation of the concept of styles) When a sort range is selected, the user may also ask for a break total to be automatically inserted in the worksheet.
The Expand checkbox, if set, will automatically trigger an expansion as soon as the report is built in the Excel sheet.
Lat but not least, the report can be generated with just ONE CELL of options (where all the options can be set using a comma delimited list of instructions) or with a RANGE listing all possible options, which can be individually turned on or off (See more details on this later in this document). In alternative to this new quick build screen, the older method of passing the number of expansions in the first parameter of the function is still supported, purely for compatibility with prior versions. Basically, if more than one expansion on either axis is desired, the user can type-in the EVDRE function using the following alternative syntax: =EVDRE({c} x {r}) where {c} is the number of expansions in columns, and {r) is the number of expansions in rows. For example, the following function call will generate a report template containing 2 expansions in columns and 3 expansions in rows, when the user hits the refresh button. =EVDRE(2 x 3)
32
Reference documentation
Note that the first cell of the original CellKeyRange (G2) contains a formula that has been copied into the expanded CellKeyRange to the right. The result is a key that varies row by row based on the PERIOD property of the corresponding row key, while the YEAR is controlled by the content of cell E2. The example here below shows how this technique can be used to build an inter-company matching report. In column H of the example the inter-company member selected in ROWS need to be swapped with the corresponding entity member, while the inter-company member must be the one corresponding to the entity selected in PAGE.
33
Reference documentation
Repeated Expansions
The result is obtained placing the correct formula in the second column (H) of the CellKeyRange G3:H3, and letting the expansion build the correct keys in column K. Note that CellKey ranges are not particularly efficient. A more efficient way to build an inter-company matching report is to use two EVDRE functions overlaid on the same data range.
Repeated Expansions
One single EvDRE function can be used to perform multiple times the same expansion on the same axis (rows or columns). This result can be achieved defining multiple expansion ranges in the RowKeyRange field, and delimiting them with a comma. Example:
34
Reference documentation
Repeated Expansions
While the above example may not seem very meaningful, certainly the following is. In this other example a repeated expansion is associated with different static keys for the entity dimension.
This result has been obtained with a RowKeyRange that is partly static and partly dynamic. The static portion is defined as an expansion with a blank MemberSet, and the member id has been entered directly in the first row of each row key range. PARAMETER ExpandIn Dimension MemberSet EXPANSION 1 EXPANSION 2 ROW ROW ENTITY ACCOUNT BAS
The main benefit of such technique is that the ranges can be separated by additional rows, each one customized freely by the user, and these rows will be preserved, because they are not part of any key range. This allows the user to design multiple sections of a report that are grouped in some sort of static layout. Yet, each individual section can be expanded using the definitions of one single EvDRE function.
35
Reference documentation
Multiple expansions
In the next example there is a different use of a repeated expansion. Here each repetition of the row expansion is associated with a different (static) ColKeyRange.
RANGE PageKeyRange ColKeyRange RowKeyRange CellKeyRange GetOnlyRange FormatRange PARAMETER ExpandIn Dimension MemberSet Sheet1!$G$15:$I$17,Sheet1!$G$22:$I$24 Sheet1!$E$13 EXPANSION 1 ROW ACCOUNT cash,accrec,inventory VALUE Sheet1!$F$2:$F$9 Sheet1!$G$13:$I$13,Sheet1!$G$20:$I$20 Sheet1!$E$15:$E$17,Sheet1!$E$22:$E$24
G 2005.JAN 15 16 17 cash accrec inventory Cash in Bank Accounts Receivable Inventory 412,297,236.68 103,074,309.17 41,229,723.67
2005.APR 22 23 24 cash accrec inventory Cash in Bank Accounts Receivable Inventory 448,821,618.13 112,205,404.53 44,882,161.81
Multiple expansions
A more generic case of repeated expansions is when the MemberSet changes for each one of the ranges defined in the corresponding row (or column) key range. To assign a different member set to each expansion, the user can specify multiple member sets in the MemberSet field, delimiting them with a pipe character (|). In the example shown here below, two sets of members for the TIME dimension have been expanded in two different RowKeyRanges.
36
Reference documentation
There is no theoretical limit to the number of ranges that can be specified, each one with its own set of members. Note that if the user specifies more ranges than sets of members, the last set will be applied to all extra ranges. In this respect repeated expansions are just a sub-case of multiple expansions, where all the ranges share the same (last) member set.
37
Reference documentation
Multiple members of the same dimension or different dimensions can be specified in the overriding expression. For example, you can write: SUPPRESS=[actual,budget],2005.total
38
Reference documentation
Formatted ranges may contain empty fields in the key range, similar to what can be done in a commadelimited list of members in a regular member set.
39
Reference documentation
Block suppressions
Block suppressions
An alternative suppression method is the block suppression. This feature allows you to activate the suppression but also to retain (not suppress) the entire set of members of the innermost expansion, if even only one row (or column) has values. This behavior is activated by the keyword B in the Suppress field (in place of Y) and ONLY works in combination with a formatted range of members assigned to the innermost expansion (See above). In the example shown here below, only the rows of entities Sales UK and Sales Europe Eliminations have been suppressed, because they were all empty. All rows of the other entities have been retained, as at least one row had values for each of them.
A block suppression may also be activated while defining an alternative region to drive the suppression. For example, you can write: SUPPRESS=B:[actual,budget],2005.total
This output has been obtained using the keyword RETAIN({member}) in the SUPPRESS field for the INTCO dimension. This has triggered a suppression of the ROW axis, but all accounts with no value have been assigned one row, intersecting them with the NON_INTERCO member of the INTCO dimension.
40
Reference documentation
In this other example the user has decided to retain a parent member, so that all accounts will also show a TOTAL row, whenever some details are found (here formatted with a white pattern for clarity).
The RETAIN keyword can also be used without a parameter. In this case the member to retain in the suppressed dimension will be taken from the current view, as set in the page key range.
Here the sum of two entities SalesItaly and SalesFrance has been generated on the fly by the report. An important side benefit of this feature is that, if the members in the page key are base level members, there will be better chances that EVDRE will go directly after the act tables to retrieve their values, reducing the load on the OLAP engine.
41
Reference documentation
This option can be used in large workbooks containing many sheets that might take some time to refresh all at once. If this option is set, whenever a refresh or expand action is invoked only the current sheet will be updated. Note that this behavior is maintained irrespective of the action that triggered the update, it be a workbook open or a current view change or a refresh after send or an explicit request from the user. All not-yet-refreshed sheets will be automatically updated as soon as the user tabs on them. Any alreadyrefreshed sheet will not be updated again, in case the focus is returned to it, unless the user or some other action explicitly requests a new refresh.
42
Reference documentation
EVDRE Options
EVDRE Options
EvDRE supports a few OPTIONS that can be activated entering the appropriate keywords in the Options cell of the KeyRange. The options, when entered in the Options cell, can be combined using comma as delimiter. In alternative, the Options cell (which can also be named OptionRange), may contain an EVRNG function pointing to a RANGE of cells listing any number of valid options. The range may look as in the following example:
The first column in the range must contain a valid option keyword. The second column will activate the corresponding option with a Y or Yes value, or with a numeric value, where appropriate. Here is the list of the currently supported options. A more detailed explanation of each option is included below. Their keywords are NOT case sensitive. : Option AutofitCol Description Automatically adjust the size of the columns containing the EvDRE ranges to fit the content after refreshing data Show only the n lowest values in the entire data range The content of the data cache is written in the log file
BOTTOM n DumpDataCache
43
Reference documentation
EVDRE Options
EvDre_log.txt ExpandOnly Disables the refresh action, and performs only an expansion, when requested. Data are not retrieved from the database (see the dynamic hierarchies section) These options will hide the corresponding key ranges
GroupExpansion HideColKeys and HideRowKeys NoRefresh NoSend PctInput QueryEngine QueryType QueryViewName ShowComments
This option prevents the system from refreshing data from the database This option prevents the system from sending data to the database Enforce a different percentage of input data to trigger SQL queries (default is 20%) Manual (or blank for Automatic) NEXJ,TUPLE (or blank for Automatic) Use a user-defined view for querying SQL data Add an Excel comment in any DataRange cell with a formula, if the value retrieved from the database is different from the one displayed by the formula All empty cells in the data range are filled with zeros Sort a given columns (old syntax see SortRange) Force the query engine to only issue SQL queries This option inserts new rows with subtotals These options will perform a suppression on the defined data range directly in Excel Prevent the suppression of zero values. Only missing (no data) values will be suppressed. Otherwise, both zeros and missing data will be suppressed. Show only the n highest values in the entire data range
TOP n
Option AutoFitCol
44
Reference documentation
EVDRE Options
The option AutoFitCol will automatically adjust the size of the columns containing the EvDRE ranges to fit with their content.
Combining this option with the appropriate suppression instruction, only the relevant rows or columns will remain in the sheet.
Remark: The filter is for now bluntly applied to the entire data range, and the user cannot define things like give me the top 5 rows with the largest amount in the first column or anything more sophisticated. This functionality will certainly be extended in future releases to cover those cases.
Option DumpDataCache
All EVDRE input schedules maintain a hidden cache of all data retrieved in the sheet, so that any modified cell can be easily identified and sent to the database. When the DumpDataCache option is activated, on every send action the content of the data cache is written in the client-based log file EvDre_log.txt, which is saved under the My Documents folder of the current user, and can be reviewed for debugging purposes.
Option ExpandOnly
45
Reference documentation
EVDRE Options
The option ExpandOnly can be used to disable the refresh action for a given EVDRE function. When this option is turned on, EvDRE will only perform an expansion, when requested, but no data will ever be retrieved from the DB to populate the data range. This feature can be useful when multiple EvDRE functions are used to build some complex reports, where one function is in charge of expanding the rows or columns, and another one is in charge of retrieving the values from the db on a shared data range.
Option NoRefresh
This option can be used in reports or input schedules to limit an EvDRE function to only perform expansions and / or sends, but never retrieve data from the database. Note that an exception to this behavior is an expansion with SUPPRESSIONS. If an expansion with suppression is performed, the data will still be retrieved, basically ignoring the option.
Option NoSend
This option can be used in input schedules to limit an EvDRE function to only perform expansion or refresh actions, but never send data. This feature can be useful when multiple EVDRE functions are used in an input schedule, to specialize their action.
Option PctInput
By default EVDRE decides to split the query in one SQL query and up to 2 MDX queries, if more than 20% of data can be read directly from the fact tables. This threshold can be adjusted to a higher or lover value using this option. (This option has been implemented mostly for debugging purposes, and, to our knowledge, has been very rarely used).
Option QueryViewName
46
Reference documentation
EVDRE Options
This option can be used to enforce the query engine to use a used-defined SQL view of the fact tables, when trying to read the values using SQL queries. This option is typically used in conjunction with the SQLOnly option (see below). It has been used in very rare situations, mostly for research purposes.
Option ShowComments
This option can be used to turn on the Excel comments used in the data range when this one contains formulas (see formulas embedded in the data range).
Option ShowNullAsZero
Some customers do not like to see ranges with no data as ranges of empty cells. This option will automatically fill all empty cells with zeros.
Option SQLOnly
In some special circumstance the customers wanted to enforce the query engine to only execute SQL queries, when reading data. This can be achieved using this option.
Option SumParent
This expansion option can be handy to generate input schedules where the user will see the values of the parents automatically populated with the sum of the children, as data are entered into the latter, without the need to perform a send action. The following example show how the cells of all parent members have been automatically populated with the appropriate SUM functions after the expansion (the sheet is shown with the view formula option turned on for clarity).
47
Reference documentation
EVDRE Options
The option also works on the account dimension, even if expenses/liabilities are to be added into income/asset parents (and vice versa) as the value of the ACCTYPE property will be correctly taken into account, in creating the formulas. It is important to note that the option only works if the member set contains the keyword ALL. This is in fact the only way by which the presence of all children for each parent can be enforced by the function. Another current limitation is that the schedule must have some base level member in both axes (rows and columns).
Suppression-Only options
An EVDRE function can be specialized to only perform a suppression of empty rows or columns. The options that can be used for this purpose are SuppressDataRow and/or SuppressDataCol. Obviously in this case the suppression will be performed directly on the data grid in Excel, after it has been populated with some value by (probably) some other EVDRE function. This feature can be useful when multiple EVDRE functions have contributed to the population of a shared grid of data. In these situations the individual functions might not have the required information to be able to identify what to suppress, and an extra function may be applied to the combined data just for this purpose. It must however be remembered that the un-suppressed data ranges generated by the initial functions might easily exceed the maximum size of an Excel sheet, making this technique hard to use.
Option SuppressNoData
By default EvDRE suppressions will indifferently suppress rows or columns where all data are zero or null. With the SuppressNoData option the user can ask the function to only suppress rows or columns containing no data (null values), while still displaying those containing stored zeros.
48
Reference documentation
Drill-Downs
Drill-downs are triggered by double-clicking on either a row or column key or a row or column heading, and may require one or more expansions to be defined in rows or columns. The double-clicking action will trigger either one of the two drill-down methods supported by EVDRE, according to the setting of the workbook option shown here:
The first method (expand by overwriting rows) will move into the current view the member where the double-clicking was performed and will invoke a new expansion of the function. With this method, for the drill-down to work, the member set of the expansion must be defined as DEP. The user will be able to back-step to the original view by hitting the back icon in the tool bar. The first method of drill-down can be applied indifferently to both rows and columns. The second method (expand by inserting new rows) will insert in the report a set of rows having as key the immediate dependants of the member where the double-clicking was performed, and will invoke a refresh of those rows. The keys and headings of the inserted rows will be indented to increase readability. This method of drill-down will always work, irrespective of the set of members defined in the expansion. The following example shows the result of a drill-down performed on entity SALES then on entity SALESUS, in a report which only started with one row (see the member set SELF in the expansion)
49
Reference documentation
Drill-Downs
In case of NESTED expansions, this type of expansion can be performed specifically and independently on each dimension expanded in rows. The user will be able to back-step to the original view by double-clicking again on the parent member that started the drill-down. With this method of drill-down the back icon is de-activated. Currently the second method can only be applied to rows (mostly because of the difficulty of indenting column headings in a visible fashion).
50
Reference documentation
Overall approach
EvDRE supports a formatting parameter, as shown here:
RANGE FormatRange
VALUE {range}
If the {range} value is left blank, the format of the data range is automatically derived, upon expansion, from the format of the left-most and top-most cell of the data range being expanded. If the {range} value is a pointer to ONE cell, the format properties of such cell are used to define the format to apply to all cells of the data range. This behavior is activated by an expansion and is ignored if only a refresh action is performed. This behavior is what EVDRE supported in its early days (and still does, for backwards compatibility). If the range is greater than just ONE cell, a full set of additional formatting features can be enabled, as describe in detail here below.
51
Reference documentation
Following is a more detailed explanation of the meaning of each column, and the keywords it supports.
52
Reference documentation
<>0 {dim.property}={value} Is only applied to the members of dimension {dim} with property {property} = {value} (*)(**) Is only applied if the row/column keys contain the passed {string}(***) Is only applied if the row/column headings contain the passed {string}(***) Is only applied to cells containing Excel formulas Is only applied to cells with a value matching the test expression Is only applied to cells being modified by a data entry action and the workbook has been set as an Input Schedule
KEY={string} HEADING={string} FORMULA VALUE = | <> | < | > | <= | >= {value} CHANGED
(*) It also supports different-from (<>) (**) It also supports a comma-delimited list of values (***)Wildcards, like * or ???, are not yet supported
The keywords supported by the EVALUATE IN column are the following: Notes Value {blank} or ALL PAGE COL ROW CELL ROWCOL Meaning Evaluate the criteria in PAGE or COLUMN or ROW or CELL(*) Evaluate the criteria in PAGE Evaluate the criteria in COLUMN Evaluate the criteria in ROW Evaluate the criteria in CELL Evaluate the criteria in ROW and COLUMN (**)
FUTURE
FUTURE FUTURE
(*) Leaving this column blank (or entering ALL) means that the criteria is true if the condition it defines is met by what defined in the PAGE key OR in the COLUMN key OR in the ROW key OR (if existing) in the CELL key. (**) The ROWCOL keyword means that that the criteria is true if the condition it defines is met by both the ROW key AND the COLUMN key simultaneously.
53
Reference documentation
CRITERIA CALC
EVALUATE IN ROW
Note that the definition of the format is directly driven by the Excel format of the FORMAT cell, as defined using the native Excel formatting tools. In this way the desired format is easier to define and visualize. Remark: it must be remembered that the format properties of a cell include the LOCK property. While this property is not quite visible without opening the Excel format cell dialog box, this is the property that will be used by EvDREs formatting engine to prevent or allow a user to modify the content of the cells of a workbook.
This means that only the PATTERN and the FONT properties of the FORMAT cell must be used. All other formatting properties (border, etc.) will be ignored. If this field is left blank, ALL formatting properties, as set in the format column, will be applied. This fragmentation of formatting options in independent groups allows the user to overlay different settings that are not mutually exclusive, and combine them into the final result. The USE column can contain one (or a comma-delimited list of some) of the following values:
Affected Range Properties ColorIndex, LineStyle, Weight (of each segment: xlDiagonalDown, xlDiagonalUp, xlEdgeBottom, xlEdgeLeft, xlEdgeRight, xlEdgeTop) (ALL + the text in the cell) Font.Name, Font.Size, Font.Bold, Font.Color
CONTENT FONT FONTBOLD FONTCOLOR FONTNAME FONTSIZE FONTSTYLE FRAME HORIZONTALALIGNMENT INDENTLEVEL LOCK NUMBERFORMAT PATTERN PROTECTION STYLE VERTICALALIGNMENT {VBA property}
(see BORDER)
Locked ColorIndex, Pattern, PatternColorIndex Locked, FormulaHidden (the Excel style) (*)
54
Reference documentation
USE PATTERN
PARAMETERS FONTSIZE=12
The instruction in the above example defines in a textual format the font size to use. Note that the instructions entered in the PARAMETERS column are applied IN ADDITION to what specified in the USE column. The main purpose of this feature is not just to allow writing things in textual form. The objective is mainly to provide a means to dynamically derive the value of a formatting option from a property of a member, like in the following example:
CRITERIA EVALUATE IN FORMAT USE ROW CALC Use this format PATTERN
PARAMETERS FONTSIZE=ACCOUNT.SIZE
Here the size of the font is derived from the property SIZE of the ACCOUNT used in the individual cell key. The syntax is: {Format property} = value Or: {Format property} = {dimension}.{property} Example: NUMBERFORMAT=ACCOUNT.FORMAT ACCOUNT.SCALING=1 Here is the full list of the currently supported keywords for the parameters column.
PARAMETERS CONTENT FONTBOLD FONTCOLOR FONTNAME FONTSIZE FONTSTYLE HORIZONTALALIGNMENT INDENTLEVEL LOCK NUMBERFORMAT STYLE
Locked
55
Reference documentation
(*)
(*) Over and above the keywords listed above, the USE and the PARAMETERS columns will honor the name of any formatting property recognized by Excel VBA code. This allows the user to customize its formatting definitions to a very fine level of precision. Please refer to Excel documentation for a full list of the supported Formatting properties.
With the above instruction the defined format is only applied to the headings area of the row/column containing a calculated member. If this field is left blank, the current formatting instruction is applied to the data range only. (Correct?) The APPLY TO column can contain one (or a comma-delimited list of some) of the following values: Value {blank} or ALL KEY PAGEKEY HEADING DATA Meaning Apply to the Key Range, Headings Range and Data Range Apply to the row or column Key Range (or both) Apply to the Page Key range (only valid CRITERIA=DEFAULT) Apply to the row or column Headings Range (or both) Apply to the Data range
with
56
Reference documentation
This example defines three formatting instructions (one per row) that will be applied in sequence from the top to the bottom. This mechanism can be useful when the user wants to define what format should win on some other (here the LOCKED format will overwrite the CALC format which will in turn will overwrite the DEFAULT format). Re-arranging the rows of this range in a different order would re-define the order by which the various formats are applied. In addition, this mechanism also permits to overlay different formatting properties on the same cell. In the following example a calculated cell will be identified with a special font and, if such cell is also locked, it will show a yellow pattern. CRITERIA DEFAULT CALC LOCKED EVALUATE IN FORMAT Use this format USE THIS FONT Use this pattern USE FONT PATTERN PARAMETERS APPLY TO
Finally, another way to utilize this technique is to define one different format for different ranges of the sheet, like in the following example:
57
Reference documentation
EVALUATE IN
PARAMETERS
In this (rather silly) example, all income accounts will have the key range marked in green, the heading range marked in yellow and the data range marked in blue. One thing to note is that the example does not specify where to evaluate the criteria and that the APPLY TO keywords do not specify whether the key or the heading should belong to rows or columns. As a result, the instructions will automatically apply to row or columns according to the position of the account key (page, column or row, or even cell). while there is no limit in the number of formatting instruction that can be inserted into a formatting range, it is obvious that executing these instructions takes some time, and the more there are instructions to process the slower the refresh action will be. For large reports with complex formatting instructions the time to refresh may become unacceptably long, especially if some of the formatting instructions must be applied cell by cell (as opposed to an entire row or column at once). For the above reason it is advisable to try and keep the amount of formatting instructions to the required minimum. In some cases it may be appropriate to only apply the formatting instructions while the report is being designed, and then disable them altogether, once the report is put in production. Alternatively the user may replace the formatting instructions used at design-time with a smaller set of instructions that need to be dynamically re-applied at every refresh of the report.
Warning:
58
Reference documentation
The same report has this appearance, when the border is applied to the calculated ranges of the DATA section, using the FRAME instruction.
Here is another example of how to apply FRAMES to entire ranges of the report:
59
Reference documentation
60
Reference documentation
In the following example empty cells have been assigned a yellow pattern
61
Reference documentation
Scaling numbers
Scaling numbers
Using the appropriate formatting instructions it is possible to replicate the scaling feature supported by the very popular EVGTS function, and actually with a great deal of additional flexibility. The approach we suggest is the following. 1) You use a property of the accounts to trigger the desired formatting in the CRITERIA parameter of the format range. In the example show below the criteria is ACCOUNT.SCALING=1 2) You define the desired format for your numbers in the PARAMETERS field. This can be hard coded or dynamically derived from a property (the FORMAT property in the example) 3) You make sure that only the NUMBERFORMAT property is set (with the USE parameter) and only on your data cells (with the APPLY TO parameter)
The final touch, to scale your numbers (what you asked for, in the end!), is to include a trailing comma in the formatting string. For example this string "#,###," will divide your numbers by 1,000. (Note that in the above example the FORMAT and SCALING properties are being displayed in the row headings range. This is only done to clarify the example, as, obviously, there is no need to retrieve them in the sheet) See Excel cell format custom options to explore other possibilities.
62
Reference documentation
When you hit the Ok button, the new EVDRE function will import all formatting definitions from the selected style sheet.
Note that all the following Excel definitions will be imported automatically from the style workbook: The Format range of the EVDRE function All WebExcel workbook options All Excel-defined styles The workbook color palette The range of cells to the right of the page key range and above the column headings (which might contain some title for the report)
63
Reference documentation
Remarks
Currently an EVDRE style may only be imported when a new report is being built using the quick build wizard. This means that if the style workbook is later modified, the reports already built using the older version of the style will NOT be automatically updated to use the new style definitions (this might be implemented in a future release). A style workbook may contain formatting instructions defining what cells should be locked and what not. However the style workbook cannot be saved as protected. The protection, if desired, will need to be manually turned on in each one of the new schedules built using such style.
64
Reference documentation
This sequence has been carefully tuned in order to make sure that the formats of the before and after ranges as well as of the formatted sets are never overridden by the formatting instructions of the format range. In other words, if some portions of the report must contain some already-formatted data, the format instructions will not break such pre-defined formats.
65
Reference documentation
Customizing EVDRE
OLAP connection
The query engine used by EVDRE to access the database opens a connection to OLAP using a default connection string containing the following instructions: Client Cache Size=80; Cache Ratio=0.01;Cache Ratio2=0.01 While these settings have proven to be adequate in the majority of cases, it may happen that fine-tuning them might improve the overall performance of the engine in a particular installation. If a user wants to customize this connection string to his own preferences, he can do so by writing the new connection string in an XML file to be stored in OutlookSoft\WebSrvr\Bin, named ev4dataserver.xml. It is important to remember that the content of the file does not work by exception, but completely replaces the default connection string. In other words, even if only one instruction must be added or modified, all other default instructions must be written in the file, otherwise the corresponding settings will be lost. The format of the file content is: <root> <parameter id="CONNECTION_OPT" values="<connection string >"/> </root> Here are some examples: Example1 <root> <parameter id="CONNECTION_OPT" values=";"/> </root> Sets the OLAP connection to Microsoft defaults Example2 <root> <parameter id="CONNECTION_OPT" values="connect timeout=30; Client Cache Size=100"/> </root> Sets the connection timeout to 30 seconds and the client cache size to 100K Example3 <root> <parameter id="CONNECTION_OPT" values="connect timeout=30; Client Cache Size=80; Cache Ratio=0.01; Cache Ratio2=0.01 "/> </root> Sets the connection timeout to 30 seconds and the client cache size to 80% of physical memory It also preserves the default values for the Cache Ratios.
66
Reference documentation
Dynamic hierarchies
Dynamic hierarchies
The EVDRE function has been recently enabled to support dynamic hierarchies in the ENTITY dimension. Dynamic hierarchies are hierarchies that can be made specific to each CATEGORY and TIME combination and are defined in our product using a special tool called the Dynamic Hierarchy Editor, and stored in a separate cube, called an OWNRSHIP cube. In this document we do not explain how a dynamic hierarchy is defined and maintained, but only how EVDRE supports the navigation in a dynamic hierarchy. For a full description of dynamic hierarchies please refer to the related document.
Option GroupExpansion
This new option is only activated when one of the expanded axes contains the two dimensions GROUP(*) and ENTITY. (*) Technically, a GROUP dimension is a dimension containing the property GROUP_CURRENCY. In most cases this dimension is also a dimension of type R (Currency) and is very often used in legal consolidation applications to retain the contribution of each ENTITY into different consolidated GROUPS of entities. When an expansion is triggered with this option turned on, the two dimensions GROUP and ENTITY expand in a combined fashion, according to the keyword defined in the member set field of the GROUP dimension. This keyword basically controls how far down in the expansion we want to go, as below described. Assume you have the following members in the GROUP dimension, with the values in the properties PARENT_GROUP and ENTITY defined as follows: ID G1 G2 G3 G4 G5 PARENT_GROUP G1 G1 G2 G2 ENTITY E_G1 E_G2 E_G3 E_G4 E_G5
Also assume that this static hierarchy (defined here above using the PARENT_GROUP property and shown by the members in bold here below) extends down into some other ENTITIES (see the E(n) members here below), as set in the OWNERSHIP cube, for the current CATEGORY and TIME combination.
67
Reference documentation
Option GroupExpansion
(**) The sets of TIME periods and CATEGORIES on which to base the expansion are those associated with the current EVDRE function, either as defined in the PAGE KEY range or in the opposite axis (For example, if GROUP and ENTITY are in ROWS, the TIME and CATEGORY dimensions must be either in PAGE or in COLUMNS). Finally, assume that the current view has G1 as current member of the GROUP dimension. Here is what the various keywords will generate: SELF This keyword will generate all rows relative to the current group (SELF) that intersect with all valid entities for such group. In our example, the valid entities are E_G1, E1 and E2, as follows:
68
Reference documentation
Option GroupExpansion
DEP This keyword will generate the following rows for the following GROUP/ENTITY intersections:
where G2 and G3 are indeed the children (DEP) of the current group G1. These children are in turn associated with all their valid ENTITY members. ALL This keyword will generate the following rows for the following GROUP/ENTITY intersections:
where G2, G4, G5 and G3 are indeed all dependants (ALL) of the current group G1. These dependants are in turn associated with all their valid ENTITY members. BAS This keyword will generate the following rows for the following GROUP/ENTITY intersections:
69
Reference documentation
This basically corresponds to the list of all base level groups (BAS) below the current group G1 , intersected with all base level entities they are associated with. (Note that this is a slight inconsistency with what we display in the other cases, as here we do not include G2/E_G2, G4/E_G4, etc.) The group expansion feature supports the PARENTAFTER keyword. The other keywords available for regular expansions of member sets (MEMBERS, BASMEMBERS) and other property-based filtering criteria are currently not supported.
70
Reference documentation
71
Reference documentation
The EVDRE_LOG file and the EVDATASERVER_DEBUG file will contain the history of all actions performed by the function (on the client and on the server respectively), while the EVDATASERVER_TRACE file will keep track of all the queries issued by EvDREs query engine. To turn on the feature it is enough to create these files in their respective folders. To turn it off, they must be deleted or renamed. The feature can be turned on or off (files created or deleted) independently for each one of the three files. Here is a sample of the content of EVDRE_LOG.TXT (client)
<debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[started]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[Caller: Sheet1!$A$1 Calc mode: 4105]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[complete]]></debug> <debug time="2007 0111 11:54:10" module="clsMain" function="isWBOffline"><![CDATA[lock status= 0]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="doExpand"><![CDATA[started]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="doExpand"><![CDATA[before enable]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="doExpand"><![CDATA[Current Excel calculation mode: -4105]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="calculateWorkbook"><![CDATA[started]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[started]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[Caller: Sheet1!$A$1 Calc mode: 4105]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="EVDRE"><![CDATA[complete]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="calculateWorkbook"><![CDATA[Sheet: Sheet1]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="calculateWorkbook"><![CDATA[Sheet: Sheet2]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="calculateWorkbook"><![CDATA[Sheet: Sheet3]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="calculateWorkbook"><![CDATA[complete]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="doExpand"><![CDATA[after enable]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="expandSheets"><![CDATA[Started...]]></debug> <debug time="2007 0111 11:54:10" module="clsExcelFunction" function="expandSheets"><![CDATA[Complete.]]></debug> <debug time="2007 0111 11:54:10" module="clsExpand" function="Class_Initialize"><![CDATA[OK]]></debug> <debug time="2007 0111 11:54:10" module="clsExpand" function="runExpand"><![CDATA[unhiding rows, Current EVDRE: Sheet1!$A$1]]></debug> <debug time="2007 0111 11:54:10" module="clsExpand" function="runExpand"><![CDATA[unhiding cols, Current EVDRE: Sheet1!$A$1]]></debug> <debug time="2007 0111 11:54:10" module="clsExpand" function="Class_Terminate"><![CDATA[Started...]]></debug> <debug time="2007 0111 11:54:10" module="clsExpand" function="Class_Terminate"><![CDATA[Complete]]></debug> .
72
Reference documentation
73
Reference documentation
74
Reference documentation
75
Reference documentation
Table of Contents
About this version .................................................................................................2 Introduction ...........................................................................................................2 Quick start.............................................................................................................3 The syntax ............................................................................................................3 The keys range .....................................................................................................4 How the key of a cell is built..................................................................................5 The PageKeyRange (optional)..............................................................................6 The ColKeyRange (required) ................................................................................6 The RowKeyRange (required) ..............................................................................7 Intersecting the ColKeyRange with the RowKeyRange ........................................7 The CellKeyRange (optional) ................................................................................8 The GetOnlyRange (optional) ...............................................................................9 The FormatRange (optional) ...............................................................................10 The SortRange (optional)....................................................................................10 The EvRNG( ) function........................................................................................10 Static reports and schedules...............................................................................11 Multi-dimensional key ranges .............................................................................12 Blank cells in the RowKeyRange or in the ColKeyRange ...................................12 Formulas embedded in the data range ...............................................................13 Multiple key ranges .............................................................................................14 Dynamic reports and schedules (expansions) ....................................................14 ExpandIn .........................................................................................................15 Dimension .......................................................................................................15 MemberSet......................................................................................................15 BeforeRange and AfterRange (optional) .........................................................18 Suppress (optional) .........................................................................................18 Insert (optional) ...............................................................................................18 The ColKeyRange and RowKeyRange in expansions ........................................21 The BeforeRange and the AfterRange in expansions.........................................21 Formulas inside the before- and after- ranges.................................................23 Expansions across sheets (3D expansions) .................................................26 Sorting ................................................................................................................28 The EvDRE quick-build wizard............................................................................31 EvDRE advanced features..................................................................................33 Expanded CelKeyRanges...................................................................................33 Repeated Expansions ......................................................................................34 Multiple expansions ..........................................................................................36 Suppressions based on a different region...........................................................37 Formatted member sets......................................................................................38 Unformatted member sets ..................................................................................39 Block suppressions .............................................................................................40 Retaining members in suppressions ...................................................................40 Multiple members in the PageKeyRange............................................................41
76
Reference documentation
Workbook option Refresh by sheet...................................................................41 EVDRE Options ..................................................................................................43 Option AutoFitCol ............................................................................................44 Options BOT and TOP ....................................................................................45 Option DumpDataCache .................................................................................45 Option ExpandOnly .........................................................................................45 Options HideColKeys and HideRowKeys........................................................46 Option NoRefresh............................................................................................46 Option NoSend................................................................................................46 Option PctInput................................................................................................46 Options QueryEngine and QueryType ............................................................46 Option QueryViewName..................................................................................46 Option ShowComments ..................................................................................47 Option ShowNullAsZero ..................................................................................47 Option SQLOnly ..............................................................................................47 Option SumParent...........................................................................................47 Suppression-Only options ...............................................................................48 Option SuppressNoData .................................................................................48 Using a special view ...........................................................................................49 Drill-Downs .........................................................................................................49 Advanced formatting: the FORMAT RANGE ......................................................51 Introduction .........................................................................................................51 Overall approach.................................................................................................51 RANGE ...........................................................................................................51 VALUE ............................................................................................................51 Extending the functionality of the FormatRange .................................................51 The columns of the formatting range ..................................................................52 The CRITERIA column....................................................................................52 The EVALUATE IN column ...........................................................................53 The FORMAT column .....................................................................................53 The USE column .............................................................................................54 USE.................................................................................................................54 Affected Range Properties ..............................................................................54 The PARAMETERS column ............................................................................55 PARAMETERS................................................................................................55 Affected Range Properties ..............................................................................55 The APPLY TO column ...................................................................................56 {blank} or ALL ..............................................................................................56 The ODDROWS parameter.............................................................................56 Applying multiple formatting instructions.............................................................57 BORDER vs. FRAME .........................................................................................58 Applying formats to values..................................................................................60 Using the CONTENT keyword ............................................................................61 Scaling numbers .................................................................................................62 Building and using your own style sheets.........................................................63 Remarks ..........................................................................................................64
77
Reference documentation
The sequence of events......................................................................................65 The event BEFORE_EVDRE_REFRESH...........................................................65 Expanding multiple EVDREs ..............................................................................65 Customizing EVDRE OLAP connection ..............................................................66 Dynamic hierarchies ...........................................................................................67 Option GroupExpansion......................................................................................67 The ENTITY expansion keywords GDEP, GBAS, GALL ....................................70 Appendix I - Debugging EvDRE..........................................................................72 Appendix II - Changes introduced after 4.2 SP3 and 5.0 SP1 ............................75
78