The Vision Database Navigator Kit
Overview
Vision offers a general purpose information management engine that allows you to manage data relationships and programs in addition to raw data. The database is fully integrated with a complete programming environment.
The Vision Database Navigator provides a framework for presenting information about your Vision environment. This kit includes a number of Vision methods that are designed to help you explore your Vision environment from a programming, database, end user, and architectural perspective. These methods are defined to interact with the Schema and Interface ToolKits and produce reports containing Html tags, designed to be used with standard browsers. These reports can be executed as part of a "live" Vision environment or can be pre-generated and stored on a server for static access.
There are a number of different perspectives from which a Vision database can be viewed including:
| --- Navigation Views --- | |
|---|---|
| Programmer Tools | What classes and messages are available, how do they work, and where are they used? |
| Data Model Tools | What data is available, how is it accessed, and what inter-relationships exist? (i.e., what is the data model?) |
| Data Inspection Tools | What are the values for a specific entity as of a specific point in time? |
| Structure Analysis Tools | What physical structures are defined in the database and what potential performance tuning opportunities are implied? |
Although these reports can be viewed interactively using any of the Vision Editors, they are designed to be viewed via a standard browser capable of interpretting Html tags. The reports can be accessed as part of a "live" Vision environment or can be pre-generated and stored on a server for static access.
Programmer Tools
The Programmer Tools provide information about all the Classes and Messages in your Vision database. The following reports are available:
- Summary Class Cross Reference
Shows available classes, by type. For each type, top level classes defined for that type are displayed. Click on a type to see hierarchy of all classes defined for that type. Click on a class to see a summary for the class.
- Full Class Hierarchy
Shows all available classes as a hierarchy. Classes at the same level in the hierarchy are sorted alphabetically. Click on a class to see a class summary.
- Class Cross Reference {for type}
Shows class hierarchy for a class type such as BuiltIns or Application. Click on a class to see a summary for the class.
- Class Summary {for class}
Shows class summary for a specific class such as Number or Entity. Summary includes description, sample usage, class hierarchy, and class characteristics. Links to class' messages and other classes in hierarchy provided.
- Message Details {for class}
Shows index of all messages directly defined for a specific class followed by a detailed description of each message. Links to the actual message definition if run as a dynamic application.
- Message Cross Reference {for class}
Shows an index of all messages defined for all classes, alphabetically. Displayed messages can be limited using user-defined restrictions.
Summary Class Cross Reference Report
The Summary Class Cross Reference Report is one of the report views that allows you to navigate to an initial class. This report organizes the available classes by ClassType - BuiltIn, Application, DataFeed, ToolKit, Dictionary, ObjectSpace, and Other. For each type, the top level classes defined for that type are displayed. If the class you want is visible, you can click on it to display a summary report for the class (i.e., the Class Summary report). Alternatively, you can click on a type to see the hierarchy of all classes defined for that type (i.e., the Class Cross Reference for type report).
For example:
Summary Class Hierarchy: Vision Demonstration Database
|
In this report, you can click on BuiltIn, Application, or DataFeed, to display a list of classes available for that class type. You can click on Boolean, DateRange, Bridge, Entity, or Incorporator to display a summary of that class.
Full Class Hierarchy Report
The Full Class Hierarchy Report is one of the report views that allows you to navigate to an initial class. This report shows all the available classes in hierarchical form starting with Object as the top of the hierarchy. Classes at the same level in the hierarchy are sorted alphabetically. You can can click on a class to display its summary report (i.e., the Class Summary report).
For example:
|
Full Class Hierarchy for: Vision Demonstration Database
Object
|
+--- Boolean
| |
| +--- FALSE
| |
| +--- TRUE
|
+--- Bridge
|
+--- BuiltInWorkspace
| |
| +--- CoreWorkspace
|
+--- DataRecord
|
+--- DateRange
|
+--- Dictionary
. . .
|
In this report, you can click on any of the classes, to display a summary of that class.
Class Cross Reference {for type} Report
The Class Cross Reference {for type} Report is one of the report views that allows you to navigate to an initial class. This report shows a class hierarchy for a specific type such as BuiltIn or Application. All the classes defined for the selected type are displayed as a hierarchy. Classes at the same level in the hierarchy are sorted alphabetically. You can can click on a class to display its summary report (i.e., the Class Summary report).
For example, a sample report for the BuiltIn type is illustrated below:
Class Hierarchy for Category: BuiltIn
Object
|
+--- Boolean
| |
| +--- FALSE
| |
| +--- TRUE
|
+--- DateRange
|
+--- FixedProperty
| |
| +--- TimeSeriesProperty
. . .
|
This report displays a description of the class type, followed by a hierarchical display of the classes for this type. You can click on any of the classes to display a summary of that class.
Class Summary {for class} Report
The Class Summary {for class} Report summarizes a specific class such as Number or Entity. This summary includes the class description, sample usage, class hierarchy, and class characteristics. This report provides links to reports that display messages defined for this class. In addition, links to other classes in this class' hierarchy are defined from this report.
For example, the following report is a class summary for the Entity class:
Profile of Class Entity
Object
|
+--- Entity
+--- Classification ->
+--- Currency
+--- DataSource
+--- Support
+--- SystemTable ->
+--- Table
+--- Universe
| ||||||||||||||||
The top of this report displays an options bar that allows you to navigate to documents supplying information about the messages in this class. You can transfer to the Message Details or the Message Cross Reference report for the class by clicking the appropriate link at the top of the report.
Following a description of the class, an abbreviated class hierarchy for this class is displayed. The full super class hierarchy is shown, followed by the classes that are immediate subclasses of this one. You can click on any of the classes in the hierarchy to display a summary of that class. Class names followed by the right arrow indicate that there are additional subclasses defined under the indicated class.
The final section in this report displays some summary characteristics of the class, including the number of instances, the number of messages, a breakdown of message by message type, and a link to the web-site documentation for this class, if appropriate.
Message Details {for class} Report
The Message Details {for class} Report shows an index of all messages directly defined for a class, followed by a detailed description of each message. Links to the actual message definition are also defined if this is run as a dynamic application. Note that this report does not include messages defined at super classes of this class. The Message Cross Reference report includes these messages as well.
For example, the following report show the message details for the Entity class:
Messages for Class Entity
Message Index
. . .
Description:
Type: Constant Returns: XRef
Also Defined At: Description:
Type: Method Returns: String
Also Defined At: Description:
Type: Method Returns: Entity
Parameters:
|
XRefThe top of this report displays an options bar that allows you to navigate to the class summary report and the message cross reference report. This is followed by an index of all messages defined directly for this class. Each message links to a more detailed description further down in the report. Note that this report does not include messages defined at super classes of this class. Link to the Message Cross Reference report to see these messages.
Following the message index is a detailed description of each message. The description includes a synopsis which displays the message syntax in red. This is followed by a description of the message, its type, the type of object it returns, any parameters, and a list of other classes defining this message. This information is drawn from the MessageImplementationDescriptor for the message. If you click on one of these other classes, you will transfer to a document that displays the definition for the message for the selected class. If you are running the dynamic version of the Navigator, you can click on the message name to see the actual message implementation.
Message Cross Reference {for class} Report
The Message Cross Reference {for class} Report shows an index of all messages defined in the hierarchy of a specific class. This includes all messages defined directly for the class and any of its sub and super classes including Object. The messages are displayed alphabetically. If the same message is defined for more than one class in the hierarchy, each one is displayed as a separate entry. Each of these messages is linked to the appropriate spot in the corresponding Message Detail report.
For example, the following report shows the message cross reference for the Entity class which includes messages defined for Object, Currency, and Classification since these classes are all in Entity's hierarchy:
Index of all MessagesIn Hierarchy of the Class Entity
-- A --
accessBlock -- FixedProperty in class DataSource
baseCurrency -- FixedProperty in class Object
|
The top of this report displays an options bar that allows you to navigate to the class summary report. A message restriction form is presented at the bottom of this document which can be used to eliminate messages based on type, usage level, update date, and search strings. This form can only be used with the dynamic version of the Navigator.
An index of all the initial letters for messages appears at the top of the report. You can click on the first letter of the message to go directly to that section of the index. Each message defined for any class in the hierarchy is displayed, with an indication of the message type and the class for which the message was actually defined.
The restriction form at the bottom of the document can be used to restrict the messages to a specific class, category, message type, or usage level. You can explicitly exclude messages defined at the class Object. You can supply a cutoff date to indicate you only want to see messages that have been redefined since this date. You can also restrict messages using a search string which matches message name, description, or implementations. When you submit these criteria, the subset of messages meeting these restrictions for the selected class or category will be displayed in the Message Cross Reference report format.
To generate a cross reference of all messages defined in the database, enter the class Object and check the Include Object choice in the hierarchy section of the form.
Data Model Tools
The Data Model Tools describe the subset of classes and messages in your Vision database that organize the application components of your environment. All classes with class type of Application are considered to be part of the data model. All messages with function type of Data are considered to be part of the data model. Application classes are described in more detail in Vision Application Classes.
The following reports are available:
- Data Model Classes
Shows data model classes as a hierarchy with the Entity classes appearing first. The remaining classes -- DataRecord, LinkRecord, Bridge, DBEntity, and DataSet -- are sorted based on the number of subclasses present. Click on a class to see a summary view for the class.
-
Data Model Summary {for class}
Shows class summary for a specific class. This view displays the class's description as well as its parent class, subclasses, and sample usage.
- Class Links {for class}
Summarizes all messages defined for any class that link to this class (i.e., return an instance of this class) and all messages defined for this class that return an instance of another application class. The messages returning an instance of the selected class are displayed on the left; the messages in the selected class that link to another application class are displayed on the right. Each link shows the class, the message name, and a symbol indicating if the returned object is a collection.
-
Data Model Details {for class}
Shows detailed information about each message defined for this class that has been flagged for inclusion in the data model. This view includes the message name, the return object's class, the form of the returned object (i.e., Object, List, TimeSeries, IndexedList), the type of message (i.e., Fixed Property, TimeSeries Property, Method, TimeVarying Method, Constant), any parameters (for IndexedLists and parameterized methods), and additional comments. The default view includes all messages defined for this class or any of its superclasses. The view can be restricted to eliminate messages defined for parent classes and to include only messages that link to other application classes.
Data Model Classes Report
The Data Model Classes Report shows all the data model classes as a hierarchy A class is included in the data model if its classDescriptor type is Application. The Entity classes appear first. The remaining classes -- DataRecord, LinkRecord, Bridge, DBEntity, and DataSet -- are sorted based on the number of subclasses present.
For example:
Vision Data Model Classes For: Vision Demonstration Database
The Vision Demonstration Database features the Vision
object-oriented analytic database and highlights dynamic data
retrieval, data navigation, cross-sectional and time series
analysis, and dynamic modifications to the database.
|
In this report, you can click on any class to see its Data Model Summary report.
Data Model Summary {for class} Report
The Data Model Summary {for class} Report shows a class summary for a specific class. This view displays the class's description as well as its inheritance hierarchy, and displays sample access syntax if defined for the class.
For example, the following report shows a sample summary for the Entity class in an investment application:
Data Model Summary: Entity
| ||||||||||||||||||||||||||||||||||||||||
This report shows the parent and direct children classes for the selected subclass. you can click on any class to switch to the Data Model Summary report for that class. The options bar at the top allows you to change to the Class Links and Model Detail views for the current class.
Class Links {for class} Report
The Class Links {for class} Report summarizes all messages that link to this class (i.e., return an instance of this class) and all messages defined for this class that return an instance of another application class. The messages returning an instance of the selected class are displayed on the left; the messages in the selected class that link to another application class are displayed on the right. Each link shows the class, the message name, and a symbol indicating the form in which the object is returned. This form can be as a single scalar Object, or as a List, IndexedList, or TimeSeries.
For example, the following report shows a sample links report for the Company class in an investment application:
Data Model Link Summary for: Company
|
Company 
IndexedList 
TimeSeries This report shows the messages that navigate to or from the selected class. On the left side, the list of messages that return an instance of the selected class are displayed. The class defining the message and the message name are indicated. The list includes any message that explicitly returns this class or one of its subclasses. Messages followed by * return a super class of the selected class. Values can be returned as single objects or as collections. The symbol after the message indicates the container form.
The right side of the report shows messages defined for the selected class that return instances of other application classes.
Data Model Details {for class} Report
The Data Model Details {for class} Report shows detailed information about each message defined for this class that has been flagged for inclusion in the data model. This view includes the message name, the return object's class, the form of the returned object (i.e., Object, List, TimeSeries, IndexedList), the type of message (i.e., Fixed Property, TimeSeries Property, Method, TimeVarying Method, Constant), any parameters (for IndexedLists and parameterized methods), and additional comments. The default view includes all messages defined for this class or any of its superclasses. The view can be restricted to eliminate messages defined for parent classes and to include only links.
For example, the following report shows a sample detail report for the Industry class in an investment application:
Data Model Details for: Industry
Parent Class: Classification Siblings: | Country | RangeClassification | Sector | Children: | |||||||||||||||||||||||||||||||||||||||||||||
TimeSeries 
Method 
Unique Key 
Partial Key This report displays information about each message in the data model for the class. Options allow you to include or exclude messages defined for parent classes (Include/Exclude parents) and restrict the messages to those that return an instance of an application class (i.e., Links Only). For each message, the name of the message, the returned object's class, the form of the returned object (i.e., Object, List, TimeSeries, or IndexedList), and the type of message (i.e,. FixedProperty, TimeSeriesProperty, Method, TimeVaryingMethod, or Constant) are displayed. For IndexedList and parameterized messages, the class of the parameter(s) is (are) indicated.
Messages that are implemented as properties are indicated by a circle in the Type column. Messages that are implemented as methods are indicated as a square. Class constants contain the letter C in this column. Messages that vary of time contain an arrow inside the circle or square. A property is considered to be time varying if it can store different values as of different points in time. Time varying properties are created using the define: message. A method is considered to be time varying if it can evaluate to different values when executed as of different dates (i.e, it directly or indirectly references propeties with are time varying). To be considered time varying, a method's type must explicitly be flagged as Named MessageType MethodTV.
Messages that vary over time should not be confused with messages that return a TimeSeries of values. A time varying method will produce different results when evaluated within a date evaluate: block. A message that returns a TimeSeries object responds to TimeSeries messages. You must explicitly send the value or asOf: message to evaluate it as of a date. See TimeSeries and Properties for more information.
Any special comments about the message are supplied in the final column. A P in this column indicates that the message was defined at a parent class. If a message has been flagged as a 'key', the partial or full key symbol appear in this column. Note that Vision does not explicitly use this key information for anything.
For messages that return instances of other application classes, you can click on the return class to link to the Data Model Summary report for that class. In dynamic versions of the Navigator, you can click on the message name to see its actual implementation.
Additional information about the selected class is displayed after this table. Included here are the names of the parent class, sibling classes, and child classes. If you click on any of the classes in this section, you will switch to the data model detail view for that class.
Data Inspection Tools
The Data Inspection Tools display data values for a specific instance of an entity class. The data items displayed are based on the class of the instance. Any message flagged for inclusion in the data model for the class is included in the data inspection reports.
The following reports are available:
-
Show All Data Values {for instance}
For the supplied instance, displays the value of each data item that has been flagged for inclusion in its class' data model.
-
Show TimeSeries Summary {for instance}
For the supplied instance, displays a summary of each time series defined in its class' data model.
-
Show History For TimeSeries
{for instance, time series item}
Displays all dates and values defined for the specified time series for the specified instance.
-
Show Members In Collection
{for instance, collection item}
Displays all elements defined in the specified collection for the specified instance.
Show All Data Values {for instance}
The Show All Data Values Report is used to display the values of each data item defined for a specified instance. The name, value, and message type are displayed for each data item. The type column indicates if the item value is stored as a property or derived via a method. If the type is a TimeSeriesProperty, the effective date of the data is displayed in the next column. A final column indicates if the value can be updated via a DataFeed subclass.
If you are running the dynamic version of the Navigator, several links are defined as well. If the value is an instance of another application class (e.g., an Entity, DataRecord, or Bridge), it is displayed as a link to this instance. If the value returned is a TimeSeries, it is displayed as a link to the Show History For Time Series report. If the value returned is a List or IndexedList, it is displayed as a link to the Show Members In Collection report. If the value is stored as a TimeSeriesProperty, the type is displayed as a link to the Show History For Time Series report. If the type is a Method, it is displayed as a link to the Show Message Profile report.
For example, the following report shows a sample data value report for the Company IBM:
Data for Company INTL BUSINESS MACHINES CORP
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Show Time Series Summary {for instance}
The Show Time Series Summary Report displays a summary of each time series defined for the supplied instance. The name, number of points in the time series, first date, and last date are displayed for each data item defined as a TimeSeriesProperty or defined to return a TimeSeries object. A final column indicates if the value can be updated via a DataFeed subclass.
If you are running the dynamic version of the Navigator, the time series name is displayed as a link to the Show History For Time Series report.
For example, the following report shows a sample time series summary report for the Company IBM:
Time Series Data for Company INTL BUSINESS MACHINES CORP
| ||||||||||||||||||||||||||||||||||||||||
Show History For Time Series {for instance, time series item}
The Show History for Time Series Report displays all dates and values defined for the specified time series for the specified instance.
If you are running the dynamic version of the Navigator, the value is displayed as a link if it is an Entity, DataRecord, Bridge, or Collection.
For example, the following report shows a sample time series summary report for the Security IBM's adjustment factor:
Data History of: adjustmentFactor for Security INTERNATIONAL BUSINESS MACH COM
| ||||||||
Show Members In Collection {for instance, collection item}
The Show Members In Collection Report displays the elements in a collection returned by the specified data item for the specified instance.
If you are running the dynamic version of the Navigator, the value is displayed as a link if it is an Entity, DataRecord, or Bridge.
For example, the following report shows the elements in Industry 530's memberList:
Members in: memberListfor Industry Computers/Office Automation
|
Structure Analysis Tools
These reports are currently under development and are not included in this release.
Operation
Most of the Vision Navigator reports have been a standard component of all databases bootstrapped since July 1997. The Data Inspector reports were added in July 1998. If your database does not include these reports, please contact your Insyte consultant to determine which Vision scripts you may need and whether any additional modifications to your environment may be required.
Dynamic Execution via Web
If you are currently using the Vision run-time environment, you can access any of the Navigator reports. You should see the home page for accessing your Vision applications and a link to the navigator reports.
Interactive Execution via Editor
All the navigator reports are accessible via the Interface Application class. To interact with the Interface ApplicationWS class, you need to specify an application name and a list of parameter values. Two general formats are available:
Interface ApplicationWS runWith: "appName", p1, p2, ... pn ;and
Interface ApplicationWS reset
setApplicationTo: "appName" .
set: "param1" to: p1 .
set: "param2" to: p2 .
set: "paramn" to: pn .
run ;
In the first format, you supply a list of inputs to the runWith:
message where the first element in this list is the name of the application
to run and the remaining list elements are the input values.
In the second format, you explicitly set the application and
parameter values by name. In this example, three parameters are
explicitly named and assigned values.
The navigator applications and their parameters are summarized below:
| Application Name | List Position | Named Id | Description |
|---|---|---|---|
| Summary Class Cross Reference | |||
| ShowClassXRefSummary | 0 | (no parameters needed) | |
| Full Class Hierarchy | |||
| ShowFullHierarchy | 0 | (no parameters needed) | |
| Class Cross Reference {for type} | |||
| ShowClassXRefDetails | 1 | categoryId | BuiltIn, Application, ... |
| Class Summary {for class} | |||
| ShowClassSummary | 1 | classId | |
| Message Details {for class} | |||
| ShowMessageDetails | 1 | classId | |
| Message Cross Reference {for class} | |||
| ShowMessageXRef | 1 | classId | |
| Message Profile {for class,message} | |||
| ShowMessageProfile | 1 | classId | |
| 2 | messageId | ||
| Data Model Classes | |||
| ShowDataModelClasses | 0 | no parameters needed | |
| Data Model Summary {for class} | |||
| ShowDataModelClassSummary | 1 | class id | |
| Class Links {for class} | |||
| ShowDataModelLinks | 1 | class id | |
| Data Model Details {for class} | |||
| ShowDataModelDetails | 1 | class id | |
| 2 | links only ("TRUE"/"FALSE") | ||
| 3 | include parents ("TRUE"/"FALSE") | ||
| Show All Data Values {for instance} | |||
| ShowAllDataValues | 1 | entityType | class id |
| 2 | entityId | instance id | |
| 3 | path | optional access path to apply to instance | |
| 4 | element | optional element (via collection path) | |
| Show TimeSeries Summary {for instance} | |||
| ShowTimeSeriesSummary | 1 | entityType | class id |
| 2 | entityId | instance id | |
| 3 | path | optional access path to apply to instance | |
| Show History For TimeSeries {for instance, item} | |||
| ShowHistoryForTimeSeries | 1 | entityType | class id |
| 2 | entityId | instance id | |
| 3 | path | optional access path to apply to instance | |
| 4 | item | item that returns a time series | |
| Show Members In Collection {for instance, item} | |||
| ShowMembersInCollection | 1 | entityType | class id |
| 2 | entityId | instance id | |
| 3 | path | optional access path to apply to instance | |
| 4 | item | item that returns a collection | |
For example:
Interface ApplicationWS
runWith: "ShowDataModelClassSummary", "Company" ;
displays the data model summary for the class Company
and:
Interface ApplicationWS
reset
setApplicationTo: "ShowAllDataValues" .
set: "entityType" to: "Currency" .
set: "entityId" to: "CAD" .
run ;
displays the data values report for the Canadian currency.
Static Web Documents
You can create static versions of these reports with Html links embedded. Create a new working directory, start an interactive Vision session, and execute the following:
Interface HtmlAccess
setServerTo: "" .
setResourcePathTo: "" ;
FormatTools Html evaluate: [
!header <- "<<<Vision Database Navigator - Demo Database<<" ;
"index.html" substituteOutputOf: [
header printNL ;
Interface ApplicationWS runWith: "displayMainMenu" ;
] ;
#--------------------
# Programmer Tools
#--------------------
!app <- "ShowClassXRefSummary" ;
app concat: ".htm" . substituteOutputOf: [
header printNL ;
Interface ApplicationWS runWith: app ;
] ;
!app <- "ShowFullHierarchy" ;
app concat: ".htm" . substituteOutputOf: [
header printNL ;
Interface ApplicationWS runWith: app ;
] ;
ClassType masterList select: [ code != "Unused" ] .
iterate:
[
!app <- "ShowClassXRefDetails" ;
!file <- app concat: "-" . concat: code . concat: ".htm" ;
file substituteOutputOf:
[ ^my header printNL ;
^my Interface ApplicationWS runWith: app, name ;
] ;
] ;
Schema CD instanceList
select: [ type code != "Unused" ] .
iterate:
[ !ws <- ^my Interface ApplicationWS ;
!app <- "ShowMessageXRef" ;
!file <- app concat: "-" . concat: name . concat: ".htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name ;
] ;
!app <- "ShowClassSummary" ;
!file <- app concat: "-" . concat: name . concat: ".htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name ;
] ;
!app <- "ShowMessageDetails" ;
!file <- app concat: "-" . concat: name . concat: ".htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name ;
] ;
] ;
#--------------------
# Data Model
#--------------------
"ShowDataModelClasses.htm" substituteOutputOf: [
header printNL ;
Interface ApplicationWS runWith: "ShowDataModelClasses" ;
] ;
Schema CD instanceList
select: [ includeInDataModel ] .
iterate: [
!ws <- ^global Interface ApplicationWS ;
!app <- "ShowDataModelClassSummary" ;
!file <- app concat: "-" . concat: name . concat: ".htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name ;
] ;
!app <- "ShowDataModelLinks" ;
!file <- app concat: "-" . concat: name . concat: ".htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name ;
] ;
!app <- "ShowDataModelDetails" ;
!file <- app concat: "-" . concat: name . concat: "-FALSE-TRUE.htm" .
translate: " " to: "_" ;
file substituteOutputOf:
[ ^my header printNL ;
ws runWith: app, name, "FALSE", "TRUE" ;
] ;
] ;
] ;