DB_MAP(1) The Burlington Northern Santa Fe RR DB_MAP(1)
The purpose of DB_map is to provide a graphical user interface to an on-line map of Burlington Northern right- of-ways and sites, and provide database storage of personnel and equipment, including but not limited to Microwave basestations, Dispatcher and MRAS radios, and telephone equipment. A link from any site to any entity in the database is possible for graphically denoting territory assignment for maintenance and support. For example, when an NMM is linked to a headquarters site or group of sites, colored circles will highlight the specific sites on DB_map's display. DB_map also provides graphical windows with textfields and buttons to help maintain the database more easily.
The database's capacity is NOT limited to just personnel; the application is also capable of keeping detailed descriptions of hardware(Microwave, radio, or electronic equipment), geographic regions, etc., and making the same type of associations with sites as with personnel. Within the application, these categorizations are called entity-types, while the people and equipment that it handles are called entities.
There is also the capability to create user-defined "entity-types". For example, if a new type of equipment becomes commonplace in Burlington Northern's environment, and it requires a different set of database fields to adequately describe, there is a mechanism to add this description of the entity-type to the application, and begin entering "entities" of this type. It will give the user more flexibility by using generic templates for describing an entity-type, which can be used to initially enter an entity into the database; entities of this new type can immediately be entered into the system, and assigned or linked to the sites. This feature will be best illustrated by use of the program.
The noteworthy advantage achieved with DB_map is that the "territories" field in comm_pers need no longer exist. The association between an entity and many sites(territories) is now graphically represented on DB_map's display, and is physically stored in binary format in the Ingres Database.
28 November 1994 1
DB_MAP(1) DB_MAP(1)
DB_map's environment and starting up DB_map
The DB_map executable is located on bnu002 in /home/netmon2/bin. It utilizes a set of AUTO-CAD drawings to display a map of the U.S., and the Burlington Northern rights-of-ways and sites are super-imposed on top of this map. Currently there are close to 4,000 sites, which are kept in the Ingres database named somethingerother. Diagnostic run-time messages and errors are sent to stderr (standard error). Following are the associated environmentals used by DB_map on start-up:
$HOME - user's home directory
$DBMAP_HELPDIR - directory where help files are
located
Note that the $HOME environmental is REQUIRED for execution of DB_map; this is used to facilitate communication between OTIS and DB_map. $DBMAP_HELPDIR is not required, although with this environmental set properly, and the help files present in that directory, some minimal run- time help will be available for DB_map. Your home directory is used as a working directory. Any questions or problems regarding these environmentals or the start-up of DB_map should be directed to your System administrator, or "sysadm" user ID if email is used.
DB_map reads a configuration file, .db_connect , from the current working directory(your home directory), which tells DB_map what host to go to for connecting to the Ingres database. This file will ordinarily contain a single string, such as "bnu002", which is where production data is located. If you execute DB_map from the pulldown root menu(or a shell if you prefer), you will see these messages in the console(or parent shell):
$ ./DB_map & <CR>
Launching DB_map.
Host bnu005, attempting to connect to Ingres DB ->
bnu003::somethingerother...
rc from DBconn_somethingerother is 0
Loading entity_type table...
there are 15 intrinsic entity_types.
Loading somethingerother database...
Loading DataViews Site information...
If there is a problem connecting with the Ingres database for some reason, it will retry the connection a few times, display messages that it is trying to do this, and if still unsuccessful, DB_map will exit with an error status code. If this happens, see your system administrator. Otherwise, you'll see a large window start, with eleven large buttons across the top and a map of the U.S. below the buttons. On the lower left hand corner of the window you'll notice a footer message area, that is supposed to
28 November 1994 2
DB_MAP(1) DB_MAP(1)
display what is happening in the program at all times. Admittedly, there will be times when this message area is not functioning properly(it doesn't keep up with the exe- cution of the program), but for the most part, it does display a message describing what the program is currently doing. On startup, it will tell you what drawings it is loading into memory, what Ingres database tables it is reading in, and for the most part when the program is busy with I/O, it will substitute a "watch cursor" for the mouse pointer. Be aware of this when moving through events rapidly with the mouse. You will see this watch cursor until all of the startup-process is complete; it then gets replaced with the normal mouse pointer, at which time the user can use any of the eleven buttons across the top of the display. During start-up you'll also notice that only the map of the U.S. appears, at least initially. The right-of-ways and sites will not appear on the display until the very last step of the start-up process.
Using DB_map: a tutorialThe following buttons appear across the top of DB_map's display:
(Zoom In) (Zoom Out) (Left) (Right) (Up) (Down) (Reset)
(Quit) (Action) (View) (Edit)
The exact layout of these buttons is likely to change, in order to make usage easier and more intuitive, and although DB_map's function buttons are mostly intuitive, some parts of DB_map's operation may initially seem complicated to a new user. The Zoom buttons, left, right, up, and down, all work as you would expect them to. "Reset" will always Zoom Out back to the original Zoom factor(the original perspective when DB_map starts), and Pan center. Note that the Zoom factor of the view on initial start-up(called Zoom factor 1) will NOT allow you to see the location of specific sites. You'll have to (Zoom In) a couple times to see them. The control key(hereafter referred to as "<CTRL>") works with the left, right, up, down, Zoom In, and Zoom Out buttons as a fine-tune mechanism for Panning, so if the view is ever slightly off from where you want it, hold the <CTRL> key down and press the appropriate Pan button(left, right, up, or down) or Zoom button. Try this a couple times to get the feel for it.
The three buttons on the far right - action, view, and edit - are the locations of the high-level functions, and are menu-buttons, which means you should press the MENU button(right-most button) on the mouse to get the menus to pull-down. If you press SELECT(left-most button) on any of these menubuttons, it will default to the first item under that menubutton, and this may or may not be what you want.
28 November 1994 3
DB_MAP(1) DB_MAP(1)
The Action menubutton currently has the following buttons under it:
(Query Sites)
(Select)
(Assign)
(Unassign)
(Clear Sites)
(Calc. Dist)
(Clear Desktop)
Query Sites
The "Query Sites" button provides a way to search the database for sites whose names match a pattern of charac- ters. Pressing the Query Sites button will bring up a small window in the upper left hand corner of the map that allows the user to key in any string of characters:
+----------------------------------------+
| Query Sites |
+----------------------------------------+
| |
| site name ^__________________________ |
| |
| (Help) (Query) (Exit) |
| |
+----------------------------------------+
Enter a series of characters on the site name field, to be used as the search string. This search string is then used to select sites from the database(case insensitive) whose names match the entered substring. To initiate the search, first enter the substring on the provided text field, and then press the "Query" button just below it. A scrolling list of matching sites is displayed in another window just below the Query Sites window.
Once the scrolling list of sites is up, the user can press SELECT on any of the sites and DB_map will automatically Zoom In and Pan directly to the site. Once you've Panned to a site, you can press the "View" button on the lower lefthand corner of the scrolling list window, and it will pop-up another scrolling list of entities that are Assigned to the current site. This is a powerful feature designed to reduce the time and effort required to find out who and/or what is Assigned to a particular site.
Finally, SELECTing on any one of the entities in the afor- mentioned scrolling list will do two things: (1) high- light(using colored circles around the sites) all sites that the entity is Assigned to, and (2) pop-up a "view" window that displays the information pertaining to the entity, having been read-in from the database. It is a
28 November 1994 4
DB_MAP(1) DB_MAP(1)
read-only display; no information on the entity can be changed from here. The graphical circles around the sites are colored according to the color field for the entity being viewed, which is how you can see what sites a particular person or thing is Assigned to; the display of the circles is directly tied to the scrolling list of entities, so if you pull out the pushpin on the entity scrolling list window, it will erase all of the circles around the sites. The view window containing the text- based information in the upper righthand corner will remain until its' pushpin is pulled out.
Special features for using with OTISThere is a special Panning and Zooming feature available which allows OTIS to tell DB_map what specific site to Zoom In on. It is initiated from the OTIS application, during a session where the user is editing a trouble ticket. For the user to access the DB_map command, pressing F26(shift F10) while editing or creating a ticket will bring up a search window. In this window, the user should type in a search string(something that will easily be found). After entering the string, pressing the F10 key will begin the search(Note: this assumes the DB_map program is currently running on the local Sun workstation, and DB_map has completely finished its' initialization. If DB_map is not running, it should be started prior to pressing the F10 key.) It is desirable to be as specific as possible when keying in the name of the site, because if the search returns with multiple site names, a scrolling list will appear from which the user must SELECT a site in order to Pan and Zoom In on the site. If the site name is specific and the search returns with one site name, the Pan and Zoom to the singular site is automatic.
There is also a feature allowing the following fields to be sent via a button press from DB_map to OTIS:
1. Segment #
2. NMM code
3. Location(sitename)
In order for this feature to work properly, you must (a) be running DB_map and OTIS on the same host machine, (b) be editing a trouble ticket in OTIS, and (c) have a site- name selected from DB_map's Query Sites' Scrolling List. Following is an example sequence of events:
28 November 1994 5
DB_MAP(1) DB_MAP(1)
(at this point, a site is "selected" from the Scrolling List)
Pressing (Assign) will pop-up an "Assign Entity" window, with a list of all entities in the database on the right- hand side of the window and on the lefthand side there will be three more buttons:
+---------------------------------------------+
| Assign Enitities |
+---------------------------------------------+
| (Assign) +-------------------+|
| (Reset) |<person's name> ||
| (Help) |<equipment's name> ||
| |<...> ||
| |<...> ||
| |<...> ||
| +-------------------+|
+---------------------------------------------+
The Assign button is used to make a direct association between a set of selected sites and 1 or many entities (this association is saved in the somethingerother database, in the "glue" table). The entities to be Assigned are indicated by using the mouse pointer to touch the entities you wish to Assign, using the SELECT button on the mouse. You can SELECT just one, or many entities for the assignment. For large numbers of sites, it is recommended that you Assign one entity at a time, for clarity and safety's sake. Once you've made the entity selections, you can try pressing the Assign button, although nothing will happen yet because no sites have been selected for the Assign. We'll discuss how to make site selections at this time.
(Select): Selecting SitesAny time after the start-up process has completed, the mouse pointer can be used to SELECT sites for Assignment. It is strongly recommended that the user Zoom In to a reasonable Zoom factor before using the mouse to do this. If you don't, and select the entire drawport, you'll be waiting a few seconds while(nearly) 4,000 sites are being prepared to be Assigned to one or more entities... so be careful when SELECTing sites.
28 November 1994 6
DB_MAP(1) DB_MAP(1)
In order to make site selections, DB_map must be taken out of Zoom-To mode and put into Select mode. To do this:
This will allow you to select sites for Assignment, using the following instructions:
There are two ways to make actual site selections: (1) Zoom In to a Zoom factor where you can accurately click directly on the site's coordinates(circle), and press the mouse's SELECT button. You should see the site's name and circle on the map turn green, to indicate that it has been selected. If you have not accurately clicked on the site(it doesn't change color within a second or so), don't worry, you can use the second method, described here, to SELECT it: (2) press SELECT very near the site, at an angle opposite of the direction you are going to drag and drop the rectangular selection box. This selection box will select all sites within the box for the purpose of Assignment. The first time you press the SELECT button, do NOT hold it down while you drag the mouse pointer. Press it and release it. This will give the program a chance to set the anchor point, and then at that point, you can drag to the opposite point of the desired rectan- gle, and "drop"; press and release the SELECT button a second time to drop. You should see all sites within the rectangle highlight(change color to green).
DB_map will not go back into Zoom To mode then until you've completed the Assignment, or cleared all the site selections yourself with the (Clear Sites) button under (Action).
Assign/UnAssign SummaryHere's a list of steps to follow when making "site-to- entity" Assignments:
28 November 1994 7
DB_MAP(1) DB_MAP(1)
Make selections on large groups of sites by using long rectangular boxes, as much as possible(this will be difficult for right- of-ways that run diagonally - southwest to northeast or southeast to northwest).
The above list of steps can be used to UnAssign sites from entities, in exactly the same fashion. Simply use the SELECT button to press the "UnAssign" button under action's menubutton, and an UnAssign version of the window will pop-up.
The (Zap!) ButtonUnAssign's window also has a (Zap!) button that will allow you to delete all site assignments for any entity. This is for someone whose territory has suddenly changed. To use (Zap!):
28 November 1994 8
DB_MAP(1) DB_MAP(1)
any glue records in the database for the
selected entities are deleted, and the
entity is free to be reassigned to other
sites again.
If there are specific sites within the selection area that you didn't want SELECTed, you can click directly on them and they'll toggle off. They will return back to their original color, and they won't be used in the current Assignment or UnAssignment. If you suddenly decide to abandon all of the currently SELECTed sites, they can be "cleared" by pressing the "Clear Sites" button under the action menubutton. You'll see all the previously SELECTed sites return back to their original color.
Segment #Analagous to how entities are associated with sets of sites, segment numbers can now be Assigned to sites. Under the Action menubutton, there is a (SEGMENT) button which will popup a window specifically for doing this; it works in exactly the same fashion as the "Assign" window for entities. First select sites using the SELECT button on the map, second, touch the segment you want the selected sites Assigned to, and third, press the (Assign) button.
Similarly, segments can be viewed graphically on the map by invoking the View Segment window, by using the Segment View window, and the segments themselves can be edited using the Segment Edit window(under EDIT's menubutton).
NMM codeNMM(Network Maintenance Manager) codes can also be Assigned to sites. It works exactly like Segment numbers.
Calc. Dist.(Calculate Distance)This button brings up a window that can be used to calcu- late distances between _m_o_s_t BN sites on the map. To use, follow these steps:
28 November 1994 9
DB_MAP(1) DB_MAP(1)
The distance between the two sites will be instantly cal- culated and displayed in the "Distance:" field in the win- dow. ***Note: the coordinate system which is used in the calculations is based on CCMI's LATA codes database, which is not the same as BN's sites. Therefore, when searching for BN-specific sitenames, consider using other nearby cities or towns which do appear in CCMI's database, and non-BN maps.
2. The View MenubuttonThis menubutton pops-up a menu of entity-types from which the user can select any one of the entity-types. Following is a model of what you might see for entity-types appearing under View's, (Telecomm, Signal, etc.) menubuttons:
(Person)
(Equipment)
(Geography)
(Miscellaneous)
(Manager)
(Technician)
(Operator)
(Electrical)
(Electronic)
(Mechanical)
(Microwave)
(Telephone)
(Headquarters)
(Territory)
(Region)
At this time, a discussion of the first 15 entity-types is in order. These first 15 entity-types are called the "intrinsic" entity-types, as they are not kept in the Ingres database; they are stored statically in DB_map's program. This is to prevent them from accidentally get- ting deleted or otherwise modified. There is an implied structure to these intrinsic entity types, which the fol- lowing illustrates:
"root" entity-type
. . . .
. . . .
. . . .
. . . .
28 November 1994 10
DB_MAP(1) DB_MAP(1)
person equipment geography miscella-
neous
. . .
. . .
manager, electrical, headqtrs,
technician, electronic, territory,
operator mechanical, region
microwave,
telephone
This model is a rubber stamp and may not be exactly the same, depending upon department. Excluding the root entity type(the "root" type isn't actually used), there are currently 15 intrinsic entity types. This classifica- tion system was implemented to make things easier for searches and viewing information pertaining to entities. Currently, any entity of type Person, or any one of Per- son's sub-types, can be found in the comm_pers(Telecomm) or sig_pers(Signal) database tables, and will possess all the fields of that department's Personnel record type. A manager is said to have a parent-type of person, as are technician and operator as well. From the Edit window, searches are allowed on a "Person" type record only, so any search for a manager named "Smith" may turn up techni- cians and operators named "Smith" also.
This typing scheme is also implemented for equipment and geography parent-types, so if you do a search for an entity of type "equipment", you won't get any matching entities of type "geography" or "miscellaneous". All 'entities' in DB_map's database tables possess a "type" field, which is always kept in entity's record. This means that Views, which will be discussed now, will indeed selectively pick out entities of person type, or any type, according to the typing scheme.
A View is defined as the collection of sites that belong to a certain entity, which is represented graphically on DB_map's display as a site with a colored circle around it. The color of the circles is configurable on a per- entity basis, that is, you set it up so John Doe's sites all have pink(or whatever color) circles around them. This information is also kept in the database, in binary graphics format. So if you press the button for person, under the View menubutton, all entities of type person, or whose parent-type is person will be selected from the database, and will appear in a pop-up scrolling list for you to choose from. When an entity is SELECTed from the scrolling list, all sites Assigned to that entity will appear on the map window with the appropriately colored circles around them.
It is possible for a site to have many entities Assigned to it, and when you View two entities Assigned to the same
28 November 1994 11
DB_MAP(1) DB_MAP(1)
site, the last one Viewed will appear on the site; the colored circles overlay themselves. If an entity has no sites Assigned to it, you won't see any sites with circles.
3. The Edit MenubuttonThis button gives the user read/write access to all the entities in the "somethingerother" database, depending on the settings of the "grants"(permissions) in the Ingres database, of course, and the user ID of the person logged into the workstation. The buttons under the Edit menubutton are currently:
(Telecommunications)
(Signal)
(Sites)
(Entity Types)
(Lata)
(Segment)
(Nmm)
Under the (Telecommunications) and (Signal) menubuttons you'll see a list of entity types similar to that under the View menubutton, but shorter. Edit only has (Person), (Equipment), (Geography), and (Misc.) for any department, as this simplifies the search for an unknown entity-type. SELECTing any of the types under a department's menubutton will bring up an "edit window" specific to that type of entity, which is uniquely defined. For example, pulling down the (Edit) menubutton followed by pulling down the (Telecomm) menubutton followed by SELECTing the person button, will pop-up a window allowing you to edit any entity of type Person, which would inherently include other entity-types such as Manager, Technician, Supervisor, or Foreman. Put another way, Editing a Telecomm or Signal "Person" will allow lookups on entity-types of any "Person" type; so if you do a lookup in the Edit Person window for a Technician by last name, you might get several other Managers and/or Technicians by the same last name returned from the lookup.
The (SITES) button will bring up an edit window for sites, where the internal DB_map record for any site can be looked up and edited. If you need to change the name of a site for differentiating it from a duplicately named site, this is where you would do it. Note that the coordinate system used is specific to DB_map, and the origin of the coordinate system is located approximately in northeastern Colorado, near East Brush. With this knowledge, you can identify where a site is in order to make accurate updates to a site's name in the site table. For now, however, the task of correcting sites' names or locations should be left to one of the system administrators. If you do find
28 November 1994 12
DB_MAP(1) DB_MAP(1)
duplicately named sites for which you wish to have the sites' state-codes appended on for clarity, let one of the administrators know, and we can get it fixed.
where:
There are no other command line options at present for DB_map, excepting, of course, the inherent OpenLook options that control the application's appearance under the window manager.
FILES
/home/netmon2/bin/DB_map - executable
/usr/local/lib/help_text/db_map.enh - latest enhancements
/usr/local/man/man1/DB_map.1 - this man page
~/.db_connect - user's database "connect" file
~/.to_otis - ASCII file to send things to OTIS
~/.to_vu - ASCII file to send things to DB_map
~/.vu.pid - DB_map's current PID
~/.otis_pid - OTIS' current PID
SEE ALSO
otis, netmon, cncc
DIAGNOSTICS
When DB_map is first started, you might notice this mes- sage in the console:
<severe>: Can't open the file.
subview/B_*X0.v: "subview/B_*X0.v"; trying to
open "B_*X0.v."
For the moment, please ignore it.
BUGS
28 November 1994 13
DB_MAP(1) DB_MAP(1)
of the system administrators know when you find one
of these misplaced sites, so it can be corrected.
In the event that DB_map crashes and attempts to "core dump", it will try to write a core file to the user's home directory. This will require a considerable amount of disk space(~13 meg). Given enough core dumps, this will quickly fill up the disk, so the system administrators would ask that when possible, let one of us know when DB_map core dumps, so the core file can immediately be removed for debugging purposes; this file is a very valu- able debugging tool. If DB_map core dumps and does indeed fill up the disk, and none of the system administrators are available, please feel free to go ahead and remove the core file.
Please make a note of what you were doing when DB_map crashed; this information will be very useful in debugging and fixing what caused the crash in the first place.
28 November 1994 14