APPENDIX 22: GeoX Programming Guide

This document assumes that the developer is using the 64-bit verion of GeoX which is based on EntireX 8.2.2.

GeoX Overview

GeoX classes allow developers to write applications that can make Geosupport calls via an EntireX Broker running on the DoITT mainframe or to a locally running Geosupport Desktop Edition (GDE).
Most Geosupport calls consist of what we call “two work area calls”. A work area is a data structure. These two work areas are Work Area 1 which is used for all calls and a Work Area 2 (which varies depending on the Geosupport function call and options you are using).
Work Area 1 (Wa1) consists of input fields for the various function parameters and output fields which return standardized versions of the input parameters as well as return codes and return messages.
Work Area 2 corresponds to the type of Geosupport function you are calling and the options you are using. For example, if to make a Function 1E (geographic information for an input address) with the "extended mode switch" set to "X", then along with Wa1 you would pass in Wa2f1ex.

Setup

Install the 64-bit Geosupport Desktop Edition on your PC.
Navigate to C:\Program Files\Geosupport Desktop Edition\GeoX\Dotnet\misc Run entirexminiruntime_64.exe (This will install the needed EntireX components)

The supporting files that are needed are:

Supporting Files
DCP Components GeoX.dll (This is the primary component.)
GeoXClientStub.dll
GeoConns.xml (This is a list of Brokers that GeoX will call)
EntireX Components SoftwareAG.EntireX.NETWrapper.Runtime.dll
broker.dll
erx.dll
EntireX Configuration Files SoftwareAG.EntireX.NETWrapper.Runtime.xml (This tells the Runtime.dll the location for erx.dll.)

Using GeoX in a .NET Program

Create your application project.

Add a reference to GeoX.dll to your project. This should bring in the following:
GeoX.dll
 GeoXClientStub.dll
SoftwareAG.EntireX.NETWrapper.Runtime.dll
 SoftwareAG.EntireX.NETWrapper.Runtime.xml

To use the GeoX.Net classes without using fully qualified names include the following:

    Imports DCP.Geosupport.DotNet.GeoX          'for Visual Basic .Net
    using DCP.Geosupport.DotNet.GeoX            //for C#

You are now ready to use the GeoX .Net classes in your application.

Important Note on Installing EntireX

When you are ready to distribute your application, you must make sure that GeoX.dll and its supporting components are copied along with your application. Additionally, the underlying components for EntireX (broker.dll and erx.dll) must be in the application PATH. You have two options for the underlying EntireX components:

  1. This is the preferred method. Run entirexminiruntime_64.exe on each computer that you are going to deploy the application to. If this is going to be run from a server, then the server is the only computer you need to run this on; you do not need to run this on clients’ computers that access the server. If you are to run as a stand-alone application on individual computers, then you must run this on each computer your application is installed on.

  2. This method is primarily used when the application is accessed from a file server and there are too many users to easily run entirexminiruntime_64.exe on each computer. Manually copy the EntireX Components (broker.dll and erx.dll) to your application directory. Then modify SoftwareAG.EntireX.NETWrapper.Runtime.xml to indicate the location of these components. To do this:

a. Edit SoftwareAG.EntireX.NETWrapper.Runtime.xml
b. Search for “Runtime.ERX.Location”
c. Replace the existing location, likely "C:\Program Files\Common Files…" With “.\” [Do Not Include the Quotes]

Sample Code for Function 1E

****************************************************************************************************
VB.Net Code Snippet for Extended Work Area 2 Function 1E Call
****************************************************************************************************
Imports DCP.Geosupport.DotNet.GeoX

Module Module1

'--create a list of connections to use
Dim myGeoConns as New GeoConnsCollection("GeoConns.xml")
'---------------------------------------------------------------------------
'ASP.Net applications will instead need to add a line similar to this:
'     Dim myGeoConns as GeoConnCollection
'     myGeoConns = New GeoConnCollection(Server.MapPath("GeoConns.xml"))
'---------------------------------------------------------------------------

'--create your geo object (makes calls to Geosupport
'--create your Wa1 object (input to Geosupport)
'--create your Wa2 object (output from Geosupport)
Dim myGeo As New geo(myGeoConns)
Dim myWa1 As New Wa1
Dim myWa2f1ex As New Wa2F1ex

Sub Main()

   '--initialize your input
   myWa1.Clear

   '--choose the Geosupport function to call (1 returns geographic info for an address)
   myWa1.in_func_code = "1E"

   '--tell Geosupport to use platform independent work areas
   myWa1.in_platform_ind = "C"

   '--set optional processing flags (if any)
   myWa1.in_mode_switch = "X"

   '--set the input data
   myWa1.in_B10sc1.boro = "1"
   myWa1.in_hnd = "22"
   myWa1.in_stname = "Reade Street"

   '--make a call to Geosupport passing in the correct Work Area 2 object
   myGeo.GeoCall(myWa1, myWa2f1ex)

   '--check the return codes from your Geosupport call
   If myWa1.out_grc = "00"
      Console.WriteLine("Successful Geosupport Call")
      Console.WriteLine(myWa2f1ex.Print)
   Else If myWa1.out_grc = "01"
      Console.WriteLine("Successful Geosupport Call with Warning")
      Console.WriteLine(myWa2f1ex.Print)
   Else If mywa1.out_grc = "XX"
      Console.WriteLine("Unable to find Broker or GDE")
      Console.WriteLine(myWa1.Print)
   Else
      Console.WriteLine("Unsuccessful Geosupport Call")
      Console.WriteLine(myWa1.Print)
   End If

End Sub

End Module

Sample Code for Function BL

    ****************************************************************************************************
    VB.Net Code Snippet for Extended Work Area 2 Function BL Call
    ****************************************************************************************************
    Imports DCP.Geosupport.DotNet.GeoX

    Module Module1

    '--create a list of connections to use
    Dim myGeoConns as New GeoConnsCollection("GeoConns.xml")
    '---------------------------------------------------------------------------
    'ASP.Net applications will instead need to add a line similar to this:
    '     Dim myGeoConns as GeoConnCollection
    '     myGeoConns = New GeoConnCollection(Server.MapPath("GeoConns.xml"))
    '---------------------------------------------------------------------------

    '--create your geo object (makes calls to Geosupport
    '--create your Wa1 object (input to Geosupport)
    '--create your Wa2 object (output from Geosupport)
    Dim myGeo As New geo(myGeoConns)
    Dim myWa1 As New Wa1
    Dim myWa2f1ax As New Wa2F1ax

    Sub Main()

       '--initialize your input
       myWa1.Clear

       '--choose the Geosupport function to call (BL returns tax lot info for an BBL)
       myWa1.in_func_code = "BL"

       '--tell Geosupport to use platform independent work areas
       myWa1.in_platform_ind = "C"

       '--set optional processing flags (if any)
       myWa1.in_mode_switch = "X"

       '--set the input data
       myWa1.in_bbl.boro = "1"
       myWa1.in_bbl.block = "00154"
       myWa1.in_bbl.lot = "0023"

       '--make a call to Geosupport passing in the correct Work Area 2 object
       myGeo.GeoCall(myWa1, myWa2f1ax)

       '--check the return codes from your Geosupport call
       If myWa1.out_grc = "00"
          Console.WriteLine("Successful Geosupport Call")
          Console.WriteLine(myWa2f1ax.Print)
       Else If myWa1.out_grc = "01"
          Console.WriteLine("Successful Geosupport Call with Warning")
          Console.WriteLine(myWa2f1ax.Print)
       Else If mywa1.out_grc = "XX"
          Console.WriteLine("Unable to find Broker or GDE")
          Console.WriteLine(myWa1.Print)
       Else
          Console.WriteLine("Unsuccessful Geosupport Call")
          Console.WriteLine(myWa1.Print)
       End If

    End Sub

    End Module

Selecting the Broker to Use

These classes allow developers to make calls to Geosupport running on the DoITT mainframe or a locally running Geosupport Desktop Edition. This is done by creating a GeoConnsCollection object that points to a list of Brokers. One of the benefits of using this collection is that if there is a problem with one of the Brokers, the classes will go to the next Broker in the list.

The best way create the GeoConnsCollection object is to point it to a GeoConns.xml file that is external to the application. Below is a sample GeoConns.xml: 

<?xml version="1.0"?>
<ArrayOfGeoConn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <GeoConn>
    <Broker>mvsp.nycnet:4036</Broker>
    <Server>P030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>
  <GeoConn>
    <Broker>mvsp.nycnet:4074</Broker>
    <Server>P030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>
  <GeoConn>
    <Broker>mvsp.nycnet:4055</Broker>
    <Server>T030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>
  <GeoConn>
    <Broker>GDE</Broker>
    <Server></Server>
  </GeoConn>
</ArrayOfGeoConn>

The first two GeoConn entries 

  <GeoConn>
    <Broker>mvsp.nycnet:4036</Broker>
    <Server>P030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>

and 

  <GeoConn>
    <Broker>mvsp.nycnet:4074</Broker>
    <Server>P030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>

point to the two production brokers (production Geosupport) on the DoITT mainframe.

The third entry 

  <GeoConn>
    <Broker>mvsp.nycnet:4055</Broker>
    <Server>T030A/GEOXSERVER/GEOSUPPORTSERVICE</Server>
  </GeoConn>

points to the test broker (which points to the test version of Geosupport).

The final entry 

  <GeoConn>
    <Broker>GDE</Broker>
    <Server></Server>
  </GeoConn>

means that a locally running Geosupport Desktop Edition (GDE) will be called instead of a broker. GDE must be installed or you will get an execption.

Which Functions to Use

Overview of What the Functions Do

Function Input Data Returned
1 address Geographic and City Service Information
1E address Geographic, City Service Information, and Political Districts
1A address Tax Property Level Information, Alternate Addresses for Property
1B address Combines 1E (Extended) with 1A (Extended) information
AP address Address Point ID and Address Point XY coordinates
1N street name Normalized Street Name and Street Code
2 intersection, node id Geographic Information
3, 3C street segment Geographic Information
3S street segment List of Intersecting Streets and their Node IDs
BL BBL Same as 1A
BIN BIN Same as 1A
D, DG, DN street code Normalized Street Name for input street code

Which Options to Use

Formatting Properties
in_hn_justificationWhen set to “L” House Numbers in Display Format are left-justified
When set to “R” House Numbers in Display Format are right-justified
in_snl
The input street names will be normalized to the indicated length
Valid values are minimum of 4 and a maximum of 32
Some streets may not be able to be normalized to the requested length
in_stname_normalization
When set to blank street names are normalized in sort format
When set to “C” street names are normalized in compact format
When set to “S” street names are normalized in sort format
Additional Information Properties (these usually require a different Work Area 2)
in_auxseg_switch
When set to “Y” the list of Segment IDs for a street segment are
Appended to the Work Area 2; for Functions 3 and 3C only
in_long_wa2_flag
When set to “Y” the long workarea for the function is returned
For Functions 1A and BL a list of BINs for the tax lot are returned instead of a list of alternative addresses; Wa2F1al must be used for these calls.
For Functions 1 and 1E additional information is returned; Wa2F1w and Wa2F1v must be used for these calls.
in_mode_switch
When set to “X” the extended work area 2 is used for the call
For Functions 1, 1E, 1A, BL, BN, 3, and 3C only; where possible, we recommend that you use this option
in_tpad_switch
When set to “Y” TPAD data is added to the work area 2; for Functions 1A, BL, and BN only
in_xstreet_names_flag
When set to “E” for Functions 1, 1E, 3, and 3C the first 5 elements in Wa1.out_stname_list contain the Street Names for the intersecting streets at the low address end of the segment and the last 5 elements in Wa1.out_stname_list contain the Street Names for the intersecting streets at the high address end of the segment
For Functions 1 and 1E only an additional Geosupport call to Function 1A is made. If successful the BBL and BIN obtained are returned in Wa1.out_bbl and Wa1.out_bin respectively.
For Function 2 the first 5 elements in Wa1.out_stname_list contain the Street Names for the intersecting streets at the intersection.
When set to space for Functions 1, 1E, 2, 3, and 3c if the Street Names of the list of intersecting streets are needed, then the user must take the street codes from Wa2 and make repeated Function D or DG calls.
Other
in_browse_flag
Sets how Geosupport should normalize your input street names when “blank” the output street name is the normalized version of the input street name
When “P” the output street name is the Primary Street Name for the input street
When “F” the output street name is the Principal Street Name for the input street
When “R” the output street name is the DCP Preferred Street Name for the input street
in_real_streets_only
When set to “R” Function 3S will return only intersections consisting of “real streets” and not changes in district boundaries or other items
in_roadbed_request_switch
When set to “R” Function 1 and 1E will return geographic data for the RoadBed street segments instead of for the Generic street segments which is the default

Selecting the Proper Work Area 2

  Function

Work Area 1 Options

  Work Area 2 to use
in_auxseg_switch in_long_wa2_flag in_mode_switch* in_tpad_switch
1E n/a n/a blank n/a WA2F1E
  n/a n/a X n/a WA2F1EX
 
2 n/a n/a n/a n/a WA2F2
 
2W n/a n/a n/a n/a WA2F2W
 
3 blank n/a blank n/a WA2F3
           
  blank n/a X n/a WA2F3X
  Y n/a X n/a WA2F3XAS
 
3C blank n/a blank n/a WA2F3C
  Y n/a blank n/a WA2F3CAS
           
  blank n/a X n/a WA2F3CX
  Y n/a X n/a WA2F3CXAS
 
3S n/a n/a n/a n/a WA2F3S
 
1B n/a n/a n/a blank WA2F1B
  n/a n/a n/a Y WA2F1B
 
1A n/a blank blank blank WA2F1A
  n/a L blank blank WA2F1AL
           
  n/a blank X blank WA2F1AX
  n/a L X blank n/a
           
  n/a blank X Y WA2F1AX
  n/a L X Y n/a
           
  n/a blank blank Y WA2F1A
  n/a L blank Y WA2F1AL_TPAD
 
BL n/a blank blank blank WA2F1A
  n/a L blank blank WA2F1AL
           
  n/a blank X blank WA2F1AX
  n/a L X blank n/a
           
  n/a blank X Y WA2F1AX
  n/a L X Y n/a
           
  n/a blank blank Y WA2F1A
  n/a L blank Y WA2F1AL_TPAD
 
BN n/a n/a blank blank WA2F1A
  n/a n/a X blank WA2F1AX
           
  n/a n/a blank Y WA2F1A
  n/a n/a X Y WA2F1AX
 
AP n/a n/a blank n/a WA2FAP
  n/a n/a X n/a WA2FAPX

We highly recommend that you use the in_mode_switch = “X” option

List of Classes and Overview

The Work Area and their Supporting classes all have the following methods:

  • default constructor

  • constructor that takes a string as a parameter

  • Clear method that reinitializes the data in the class

  • ToString method that converts the data structure to a string

  • FromString method that converts a string into the data structure

  • Display method that creates a string consisting of the data items separated by a dash

  • Display(Char) method that creates a string consisting of the data items separate by “Char”

  • Print method that creates a string with the data field names and the data values of the class

  • Get/Set Properties for the data fields (with the exception of Work Area 1 input fields, these are usually limited to Get only) for the most part the names are self-explanatory

Classes

Main GeoX Classes Description
Geo Main GeoX object
GeoConn Contains information needed to connect to an EntireX Broker or a locally running Geosupport Desktop Edition (GDE)
GeoConnCollection Contains a list of GeoConn objects
GeoConnsException Information relating to an exception involving a GeoConn object
   
Work Area Classes Description
Wa1 Input Data, Normalized Input Data, Return Codes
   
Wa2F1 Geographic Information about a Street Segment
Wa2F1w Wa2F1 with additional data
Wa2F1e Wa2F1 with election district information
Wa2F1v Wa2f1e with additional information (same as Wa2f1w with election district information)
Wa2F1ex Wa2F1e with additional information and street names for all street codes
Wa2F1a Tax Lot Information about an input Address, BBL, or BIN along with a list of alternate addresses associated with the tax lot
Wa2F1al Same as Wa2F1a except with a list of BINs associated with the Tax Lot instead of a list of alternate addresses.
Wa2F1al_TPAD Same as Wa2F1al with the addition of the TPAD status for each of the BINs in the BIN List
Wa2F1ax Wa2F1a with additional information and street names for the alternate addresses for the Tax Lot
Wa2F1b Combination of Wa2F1ex and Wa2F1ax for input address
Wa2F2 Geographic Information about an Intersection
Wa2F2w Same as Wa2F3x with a list of additional Segment IDs for those street segments that have multiple Segment IDs associated with them
Wa2F3 Geographic information about an input street segment (consisting of an on-street and two succeeding cross streets for the on-street
Wa2F3as Same as Wa2F3 with a list of additional Segment IDs for those street segments that have multiple Segment IDs associated with them
Wa2F3x Same as Wa2F3 with additional information and street names for all street codes
Wa2F3xas Same as Wa2F3x with a list of additional Segment IDs for those street segments that have multiple Segment IDs associated with them
Wa2F3c Same information as Wa2F3 but for one side of the segment only
Wa2F3cas Same as Wa2F3c with a list of additional Segment IDs for those street segments that have multiple Segment IDs associated with them
Wa2F3cx Same as Wa2F3c with additional information and street names for all street codes
Wa2F3cxas Same as Wa2F3x with a list of additional Segment IDs for those street segments that have multiple Segment IDs associated with them
Wa2F3s List of Intersection for an input Street Stretch
Wa2F5 Returns a properly formatted Geosupport address key for an input address
Wa2Fhr Returns the version of Geosupport and the Release Number for the data files
Wa2Fap Address Point ID and XY Coordinates for input Address
Wa2Fapx Same as Wa2Fap with addition of street name in address list
   
Wa1Aimz Returns a list of Map IDs associated with the Input

Supporting Classes for Work Areas

  • AddrRange
  • AddrRangeX
  • AddrRange_ap
  • AddrRange_apx
  • B10sc
  • B5sc
  • B7sc
  • BBL
  • BIN
  • BusArea
  • ComDist
  • CrossStreetInfo
  • DofMap
  • FileInfo
  • LionKey
  • Sanborn
  • SegSide
  • TPADLongWa2Info
  • VsamKey1