Symmwin

Power and Cache Calculator Tool

Application Program Interface
(API)

** Rough Draft **

** Company Confidential **

Written by
Mark Silvestri and Nirit Lvovsky
SymmWin Group
Date Printed: 15-Jan-2004
Last Modified: 15-Jan-2004

EMC Corporation
171 South Street
Hopkinton, MA 01748-9103
Corporate Headquarters: (508) 435-1000, (800) 424-EMC2
Fax: (508) 435-5374 Service: (800) SVC-4EMC

TABLE OF CONTENTS
1.

EXECUTIVE SUMMARY....................................................................................................................................... 5

1.1
DESCRIPTION........................................................................................................................................................5
1.2
GOAL ......................................................................................................................................................................5
1.3
A UDIENCE .............................................................................................................................................................5
1.4
RELATED DOCUMENTATION ............................................................................................................................5
1.5
RELEASE NOTES...................................................................................................................................................6
1.6
DESCRIPTION OF TERMS USED ..........................................................................................................................6
1.7
HOW TO READ THIS DOCUMENT .....................................................................................................................6
1.8
BACKUS-NAUR FORM (BNF) ..............................................................................................................................7
1.8.1
Standard Syntactic Categories .............................................................................................................. 7
2.

EXISTING SYSTEM............................................................................................................................................... 8

2.1
EXISTING PROBLEMS...........................................................................................................................................8
2.2
DLL INTERFACE ...................................................................................................................................................8
2.3
EXAMPLE OF W EB BASED INTERFACE ............................................................................................................9
2.3.1
Web Input Page........................................................................................................................................10
2.3.2
Web Report Page.....................................................................................................................................11
2.4
BASIC OVERVIEW OF DATA M OVEMENT ......................................................................................................11
2.5
EXPECTATION ....................................................................................................................................................11
2.5.1
Look and Feel ..........................................................................................................................................12
2.5.2
Data Flow.................................................................................................................................................12
2.5.3
Working With Symmwin .........................................................................................................................12
3.

WORK TO BE DONE..........................................................................................................................................13

3.1
PHASE I - DESIGN ................................................................................................................................................13
3.1.1
Overview/Presentation...........................................................................................................................13
3.1.2
API Primitives Design.............................................................................................................................13
3.1.3
API One-Shot Solution Design .............................................................................................................13
3.1.4
Internal Data Structure Design............................................................................................................13
3.1.5
GUI.............................................................................................................................................................13
3.2
PHASE II - IMPLEMENTATION /CODING .........................................................................................................13
3.2.1
API Library(s) ..........................................................................................................................................13
3.2.2
Symmwin DLL...........................................................................................................................................13
3.3
PHASE III - DEBUG/TESTING.............................................................................................................................13
3.3.1
Standalone Test Application ................................................................................................................13
3.3.2
Automated Test Application..................................................................................................................13
3.3.3
Symmwin ...................................................................................................................................................14
3.4
PHASE IV - RELEASE ..........................................................................................................................................14
3.5
PHASE V - IMPROVE SYSTEM ...........................................................................................................................14
4.

POWER AND CACHE CALCULATOR - VERSION 6.5 ..............................................................................15

4.1
OVERVIEW...........................................................................................................................................................15
4.2
CHANGES FROM 6.0............................................................................................................................................15
4.3
API .......................................................................................................................................................................15
4.3.1
CalcCacheXml()......................................................................................................................................15
4.3.2
XML Specific Syntactical Categories..................................................................................................16
4.3.3
Tag Listing (DLL Input).........................................................................................................................17
4.3.4
Tag Listing (DLL Output)......................................................................................................................18
4.3.5
XML Examples .........................................................................................................................................18

-i-

4.3.6
Restrictions...............................................................................................................................................19
4.4
REMAINING ISSUES.............................................................................................................................................19
4.4.1
Illegal XML Returned in Error XML....................................................................................................19
4.5
EXAMPLE SCENARIOS.......................................................................................................................................19
5.
5.1
5.2
5.3
5.4
5.5
6.

POWER AND CACHE CALCULATOR - VERSION 7+...............................................................................20

OVERVIEW...........................................................................................................................................................20
CHANGES FROM 6.5............................................................................................................................................20
API .......................................................................................................................................................................20
REMAINING ISSUES.............................................................................................................................................20
EXAMPLE SCENARIOS.......................................................................................................................................20
KNOWN SYSTEM ISSUES ................................................................................................................................21

6.1
SEVERITY ONE ISSUES.......................................................................................................................................21
6.1.1
<Issue Name>..........................................................................................................................................21
6.2
SEVERITY TWO ISSUES......................................................................................................................................21
6.2.1
<Issue Name>..........................................................................................................................................21
6.3
SEVERITY THREE ISSUES ..................................................................................................................................21
6.3.1
<Issue Name>..........................................................................................................................................21

- ii -

TABLE OF FIGURES
Figure 1 - Existing DLL Interface.................................................................................................................................. 8
Figure 2 - Example VB Call to DLL Interface............................................................................................................... 9
Figure 3 - Example of Web Based Interface.............................................................................................................. 10
Figure 4 - Example of Web Based Output................................................................................................................. 11
Figure 5 - Data Flow..................................................................................................................................................... 11
Figure 6 - Design Data Flow Expectation.................................................................................................................. 12
Figure 7 - Implementation with Symmwin ................................................................................................................. 12
Figure 8 - Version 6.5 DLL Interface.......................................................................................................................... 15
Figure 9 - Version 7 DLL Interface............................................................................................................................. 20

- iii -

TABLE OF TABLES
Table 1 - Release Notes ................................................................................................................................................. 6
Table 2 - Description of Terms ..................................................................................................................................... 6
Table 3 - XML Syntactical Categories ...................................................................................................................... 16
Table 4 - XML Tag Listing of DLL Input.................................................................................................................. 17
Table 5 - XML Tag Listing of DLL Output............................................................................................................... 18

- iv -

1. Executive Summary
1.1 Description
This document describes the Power and Cache Calculator tool. It describes how the system works today, how it will
work in the near future, as well as how it will work upon completion of its next major release.
As of November 2003, the Symmwin group has taken control of the Power and Cache Calculator tool. The existing
problems include:

Different formulas are used across different platforms

Getting new data out to user is slow
Need to "hide" certain data from partners

1.2 Goal
The goal of this project is to provide a reasonably simp le tool to be used throughout EMC to calculate cache and
power requirements for a Symmetrix. It is expected that upon completion, all users (Sales, Symmwin, Engineering,
etc.) will switch to use this new single format.

1.3 Audience
The primary audience of this document includes:

Users of the Power and Cache Calculator

It is understood that the reader of this document has a solid working knowledge of:

Basic Symmetrix Systems

Specific Expertise in Symmetrix:
Data Protection
Drives
SRDFA
Virtual Devices
Cache Boards
Basic Windows 2000
Basic Programming terminology (COM, DCOM, Threads, process, etc.)

1.4 Related Documentation

CacheCalculator IDL, EMC

\\starfleet\eng\symmwin_group\projects\cache_calculator
(Requires Microsoft Visual C++)

Mark Silvestri

Page 5

1/15/2004

1.5 Release Notes

Date
?? ??? ??

Revision
?.?

Author

Description

MWS

Original Document.

Table 1 - Release Notes

1.6 Description of Terms Used

Term/Expression
COM
DCOM
GUI

Definition/Usage
Common Object Model
Distributed Common Object Model
Graphical User Interface (e.g., a Window)
Table 2 - Description of Terms

1.7 How to Read This Document

Items you enter or example code will be in this font:

ShowMessage 'Completed First Calculation'

Keys that should be pressed on the keyboard will be shown this way:
<Enter>, <Ctrl>, <F8>

Buttons on the screen which should be pressed with the mouse will be displayed this way:
[Next], [OK], [Calculate]

Shaded sections are items that have not been implemented.

This applies to the explicit API calls only.

Sections that look like this are comments from the author(s). These comments generally raise issues that need to be
addressed by someone other than the author(s).

Mark Silvestri

Page 6

1/15/2004

1.8 Backus-Naur Form (BNF)

The standard technique for defining the syntax of a language is to use Backus-Naur Form (BNF). The variant used
here is as follows:

Words inside double-quotes ("word") represent literal words themselves (these are called terminals). The phrase
"double-quote" is used to represent the double -quote character itself. For example: "if".
Words outside double-quotes (possibly with underscores) represent syntactic categories (i.e., nonterminals).
For example: if_statement.
Syntactic categories are defined using the form:
syntactic_category ::= definition
Square brackets ([]) surround optional items.
Curly brackets ({}) surround items that can repeat zero or more times.
A vertical line (|) separates alternatives.

1.8.1 Standard Syntactic Categories

Digit
Sign
Space
Alpha
Integer
Variable
Number
String

Mark Silvestri

::=
::=
::=
::=
::=
::=
::=
::=

"0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
"+"|"-"
" "
"a"|"b"|..|"y"|"z"|"A"|"B"|..|"Y"|"Z"
Digit{Digit}
Alpha
[Sign]Integer[.Integer]
""{""|Alpha|Digit|Space|.}

Page 7

1/15/2004

2. Existing System
The existing system runs across three different system. All three are generated from separate source code. The three
different systems are:

<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

DLL

XML

I
N
P
U
T

Data
Crunch

O
U
T
P
U
T

XML

<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

Figure 1 - Existing DLL Interface

Windows COM DLL

Web Interface
Standalone Application

2.1 Existing Problems

Many of the existing problems are:

2.2 DLL Interface

Mark Silvestri

Page 8

1/15/2004

The following example is all of the test code we received from we agreed to take over the code.
Private Sub btnGetResults_Click()
Dim strXml As String
Dim objCache As New CacheComp.clsCache
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml
strXml

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

"<params>"
strXml & "<model>DMX3000</model>"
strXml & "<dae>0</dae>"
strXml & "<ficonfed>8</ficonfed>"
strXml & "<esconfed>0</esconfed>"
strXml & "<fige>0</fige>"
strXml & "<cacheboards>8</cacheboards>"
strXml & "<hypervols>Default</hypervols>"
strXml & "<containsvdevs>0</containsvdevs>"
strXml & "<host>"
strXml & "<type>OP</type>"
strXml & "<drive>146K</drive>"
strXml & "<raid>MIRRORED</raid>"
strXml & "<drives>576</drives>"
strXml & "<custlogvols>0</custlogvols>"
strXml & "</host>"
strXml & "</params>"

strResult = objCache.calculatecache(strXml)
MsgBox strResult
End Sub

Figure 2 - Example VB Call to DLL Interface

Though there is not much code here, it does provide a simple example of how the DLL works. In a nutshell, you pass it an
XML string with all your data and it passes back an XML string that contains all the necessary information pertaining to
cache boards and power supplies.
Issue: In running updating this program, we found a problems:
1) The XML code returned was illegal XML code because the tags started with a numeric value
instead of a character.
2) The drivers were passed as "K" drives when they should be GB drives.

2.3 Example of Web Based Interface

The web based tool provides

Mark Silvestri

Page 9

1/15/2004

2.3.1 Web Input Page

The web input page looks like the following:

Figure 3 - Example of Web Based Interface

The biggest problem with the web page is the fact the drives are bound to a specific host record and this is just not
the way it works in reality.

Question: Do we want to set up the system so that volumes requested looks similar to that of
Symmwin?

Mark Silvestri

Page 10

1/15/2004

2.3.2 Web Report Page

Below is an example of the web-based output.

Figure 4 - Example of Web Based Output

2.4 Basic Overview of Data Movement

The data will be stored via a standard API call interface. The figure below shows how the data will move.
Figure 5 - Data Flow

2.5 Expectation
This section will explain what the general expectations are of the new Power and Cache Calculator System.

Mark Silvestri

Page 11

1/15/2004

2.5.1 Look and Feel

It will also be required to be directly accessible from the Symmwin GUI.

2.5.2 Data Flow

It is expected the data in and out of the system will flow as follows.

Figure 6 - Design Data Flow Expectation

2.5.3 Working With Symmwin

Figure 7 - Implementation with Symmwin

Mark Silvestri

Page 12

1/15/2004

3. Work to be done
3.1 Phase I - Design
3.1.1 Overview/Presentation
How the system will work. This should be a document describing the project as whole. What
needs to be done and what will be the finished product.

3.1.2 API Primitives Design

3.1.3 API One-Shot Solution Design

3.1.4 Internal Data Structure Design

3.1.5 GUI
It is expected that there will be no GUI whatsoever in this system. All GUIs will need to be
generated by calling applications.

3.2 Phase II - Implementation/Coding

3.2.1 API Library(s)
3.2.2 Symmwin DLL

3.3 Phase III - Debug/Testing

This is effectively a continuation of the implementation. However, it is a landmark when the code is far
enough along that data can be retrieved from the system without getting any errors back.

3.3.1 Standalone Test Application

This testing will be the first major landmark of the entire project. It will show that the data can be
logged to the database.

3.3.2 Automated Test Application

Mark Silvestri

Page 13

1/15/2004

3.3.2.1 Failure Testing

This will test the ability of the system to correctly recognize invalid setups, configurations, etc. and
report back that an error has occurred. The automated system should be written so that it can
check numerous expected invalid configurations and trap them early on in the development
process.

3.3.3 Symmwin

3.4 Phase IV - Release

3.5 Phase V - Improve System
This phase will:

Mark Silvestri

Issues raised since the release of the system

Previously planned improvements

Page 14

1/15/2004

4. Power and Cache Calculator - Version 6.5

This chapter describes the exactly what and how the system will work for release 6.5. It will include specific API calls,

4.1 Overview
This code will still be a "one-shot" solution where all data is passed in a single function call and all the return data is
returned from the one function call. This is similar to the XML solution, except removes all the XML parsing that is
required.
<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

DLL

XM
L
I
N
P
U
T

API Function Call

API

function LoadData(record struct)

L
XM

Data
Crunch

O
U
T
P
U
T

API

<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

API Function Call

function LoadData(record struct)

Figure 8 - Version 6.5 DLL Interface

4.2 Changes from 6.0

4.3 API
4.3.1 CalcCacheXml()
Description
Syntax
Settings
Returns
Remarks
See Also
Example

Takes an XML configuration string and returns an XML configuration string

clsCache.CalcCacheXml(const inputStr: WideString): WideString;
inputStr : valid XML string meeting the requirements stated

Valid XML string

Mark Silvestri

Page 15

1/15/2004

4.3.2 XML Specific Syntactical Categories

DriveSize
Platform
Protection

::=
::=
::=

HostType
ModelPrefix
ModelType

::=
::=
::=

TagName
StartTag

::=
::=

"73" | "146" | "300"

"6.0" | "6.5"
"BCV" | "HLM" | "SPARE" | "SRDF" | "MIR" | "RAID 3+1" |
"RAID 7+1" | "RAID10" | "RAID5-3" | "RAID5-7"
"MF" | "OS"
"DMX"
ModelPrefix "800"|"801"|"1000"|"1000-P"|"2000"|"2000-P"|"20003"|"2000-P3"|"3000"
Alpha{Alpha|Digit}
"<" TagName ">"

EndTag

::=

"</" TagName ">"

Table 3 - XML Syntactical Categories

Mark Silvestri

Page 16

1/15/2004

4.3.3 Tag Listing (DLL Input)

Tag Description

Valid Values

Usage
Parameters Section [Required]
params
model ModelType
platform Platform
dae 1..8
fibrefed 1..8
ficonfed 1..4
esconfed 1..4
fige 0..8
cacheboards 0..8

Description

The model number of the system

The specific platform (6.0 = DMX, 6.5 = DMX Mach 2)
The number of DAEs in the system
The number of Fibre boards in the system
The number of FICON boards in the system
The number of ESCON boards in the system
The number of FIGE boards in the system
0 tells to calculate the best number of boards. (*Not working yet.)
1..8 implies that the specific number of boards passed should be the
count used in calculations.
Hyper volumes
0 is false, 1 is true

hypervols Integer
containsvdevs 0 | 1
Host Sub-Section [Required; Must be at least 1 host]
host
type HostType
The type of host

OS: Open Systems

MF: Mainframe
Size of Drives in GB
Protection Level
Number of drives used for the defined host
Number of customer log volumes

drivesize DriveSize
raid Protection
drivecount Integer
custlogvols Integer
Mainframe Virtual (MF) Devices Sub-Section [Optional; Supports Many]
mf_vdevs
mf_dataprotection Protection
Protection Level of Virtual Device
mf_vdevchange 0..100
Virtual Device Percentage Change
mf_savedevunitsize Integer
Virtual Device Unit Size in GB
Open Systems (OS) Virtual Devices Sub-Section [Optional; Supports Many]
os_vdevs
os_dataprotection Protection
Protection Level of Virtual Device
os_vdevchange 0..100
Virtual Device Percentage Change
os_savedevunitsize Integer
Virtual Device Unit Size in GB

Virtual Device Sub-Section [Minimum of 1 for each MF or OS Virtual Devices Section]

mf_vdev | os_vdev
numvdevs
vdevunitsize

Integer
Integer

Number of Virtual Devices

Virtual Device Size in GB
Table 4 - XML Tag Listing of DLL Input

Mark Silvestri

Page 17

1/15/2004

4.3.4 Tag Listing (DLL Output)

Tag Description

Valid Values

Description

Usage
Output Section [Required]
output
c###gb Integer
mincache

Integer

power
Error Sub-Section
Error

Integer

The specific number of memory boards of the given type where the
### is the size of the memory board in GB.
The total amount of cache required by the system. It is the total of the
board sizes and counts.
The number of power supplies the system would require.

If this is returned, there are no sub-tags. The text surrounded by the

Error tags is the error message.
Table 5 - XML Tag Listing of DLL Output

4.3.5 XML Examples

4.3.5.1 Minimal Example
<params>
<platform>6.0</platform>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<fibrefed>0</fibrefed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>4</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>1</containsvdevs>
<host>
<type>OS</type>
<drivesize>146</drivesize>
<raid>MIRRORED</raid>
<drivecount>576</drivecount>
<custlogvols>0</custlogvols>
</host>
</params>

List 1 - Example XML with Basic 6.5 Syntactical Categories

4.3.5.2 Expected Output

<output>
<c16gb>2</c16gb>
<c32gb>2</c32gb>
<mincache>96</mincache>
<power>6</power>
</output>

List 2- Example Expected Output

Mark Silvestri

Page 18

1/15/2004

4.3.5.3 Example of error Output

<Error>Entered num of Cache Boards is 1, the minimum allowed num of Cache Boards is
4</Error>

List 3- Example Expected Output

4.3.6 Restrictions

The Host, Virtual Devices, and Virtual Device tag item sections must be given in the order listed in Table 4.
White Space

4.4 Remaining Issues

4.4.1 Illegal XML Returned in Error XML
4.4.1.1 Problem Description
It is possible to get an error message that is illegal XML.
Example string returned:
<Error>Cache Calculator: Document Parse Error: Code: -1072896749, Line: 2, LPos: 29,
Reason: Whitespace is not allowed at this location.
, Source:
<platform>6.0</platform> & , fPos: 38</Error>

4.4.1.2 Solution
Question:?

4.5 Example Scenarios

This section will describe how to use the tool by giving explicit examples using the system.

Mark Silvestri

Page 19

1/15/2004

5. Power and Cache Calculator - Version 7+

This chapter describes the exactly what and how the system will work for release 7+. It will include specific
API calls,

5.1 Overview
This code will still support both "one-shot" solutions, however, it will now also support option of building a
configuration one function at a time.

<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

API Function Call

function LoadData(record struct)
AddDisks()
AddBoards()
AddVolumes()
etc.

DLL

XM
L
I
N
P
U
T

L
XM

Data
Crunch

O
U
T
P
U
T

AP
I

API

<params>
<model>DMX3000</model>
<dae>0</dae>
<ficonfed>8</ficonfed>
<esconfed>0</esconfed>
<fige>0</fige>
<cacheboards>8</cacheboards>
<hypervols>Default</hypervols>
<containsvdevs>0</containsvdevs>
"<host>
<type>OP</type>
<drive>146K</drive>
<raid>MIRRORED</raid>
<drives>576</drives>
<custlogvols>0</custlogvols>
</host>
</params>"

API Function Call

function LoadData(record struct)
function GetCacheBoards()
function GetPowerSystems()

Figure 9 - Version 7 DLL Interface

5.2 Changes from 6.5

Add Primitive functions that allow for
Multiple calls to configure
Multiple calls to return values

5.3 API
5.4 Remaining Issues

5.5 Example Scenarios

This section will describe how to use the tool by giving explicit examples using the system.

Mark Silvestri

Page 20

1/15/2004

6. Known System Issues

This chapter lists issues that need to be addressed because they impact more than a single piece of the
system.

6.1 Severity One Issues

These are issues that must be addressed prior to release. They are considered catastrophic to the system or
generate output that could cost EMC money (in sales, replacements, etc.)

6.1.1 <Issue Name>

6.1.1.1 Problem Description
6.1.1.2 Solution

6.2 Severity Two Issues

These are issues that should be addressed prior to release, but will not be catastrophic to a user.

6.2.1 <Issue Name>

6.2.1.1 Problem Description
6.2.1.2 Solution

6.3 Severity Three Issues

These are issues that should be addressed as time permits. These are not critical issues.

6.3.1 <Issue Name>

6.3.1.1 Problem Description
6.3.1.2 Solution

Mark Silvestri

Page 21

1/15/2004