VGF Create Utility:

The VGF_CREATE_CMD.EXE utility is a command-line application that allows you to build different types of vgfs without the need for a GUI.

2 or 3 things are needed:
a)      The executable:  VGF_CREATE_CMD.EXE.  This can be located anywhere on your network.  Only one copy needs to be maintained.
b)      An XML file that contains all the parameters for a particular build. Note that all parameters (left of the = sign) are case sensitive.  Examples of each type are provided.
c)      A spatial file representing the polygons that are being built.  This is not needed for all of the vgf types.  See below for further clarification.

 There is a zip file containing all of the sample xmls and source files, located here.

There are three types of VGFs you can build:

POLYGON
ALIAS
RECORD LEVEL

Note that in the examples, not all of the possible parameters that are documented below are represented.  Instead, the examples represent some common cases.

POLYGON VGFS:

Polygons VGFS are one of the really neat things about Allocate:  Given a custom polygon(s), Allocate can retrieve data from “built-in” levels, and weight an aggregate to the custom polygon(s).  It uses Block Centroid retrieval to do this.  Whether or not the polygons are added as a custom polygon on the geography tab, or they are built as a vgf, the results are the same, however, the vgf will be quicker, due to pre-aggregation.

This vgf type can be built via the Allocate desktop GUI as well.  Using the command line utility, you have a bit more flexibility, and of course don’t need spend time going through the GUI every time a rebuild is needed.

The sample provided is: POLYGONLEVEL_ZIPS.XML.

Sort requirement:  None, but doesn’t hurt to sort on the keyField.

For a polygon-type build, there are 3 general sections in the XML:

<InputFile> parameters:
path= path to the source file.  File must be sorted on the fixed-length Key field.
nameField= the field in the source file containing the Name of the geography.
keyField=The fixed-length Key field for the geography. NOTE:  If this geography has a parent (see below), the Key needs to start with the parent key. 

  For example, if you are building Zips by State, and the Zip is 80301, and the parent is Colorado, which has a FIPS code of 08, the KEY would be 0880301.  Note if the Key already begins with the parent, you don’t need to modify.  For example, If you are building ZIPs by Sectional Center, the Sectional center is already 803, so the ZIP code doesn’t need to be modified.

altKeyField=A third column in the source data that represents the “display” key.  Basically, if the Key starts with a parent, but you don’t want to user to see that, make this the base key.  So if this is Zips by State, the Key is 0880301 and the AltKey is 80301.

<OutputFile> parameters:
path=the path to the output.  Think about naming conventions that make sense.  Must end with the .vgf suffix.

<Params> Parameters:
longName=The name that the user sees in the geography tree
shortName=The ‘internal name’ of the vgf.  Avoid Spaces and keep to all Uppercase, as a rule.
parentShortName=If there is a parent geography (in the geography tree, the geography you are building should fall under another for purposes of organization  (e.g. Zips by State), this is the shortname of the parent.
createPolygons=Always set to True for Polygons builds (and in general).
autoRegisterResult=When set to True, the vgf will be registered in the Allocate dataset to which it was built, so that next time the dataset is opened in the Allocate desktop, the vgf is available in the tree.
autoUnregisterPrevious=When set to True,will unregister a vgf with the same shortname, as long as the actual filenames differ.
logfile=Path to a log file that captures any errors in the build.  Note that is not path is specified, a log file will still be generated if errors occur, and it will default to the path containing the XML.  For this reason, most of the time, you don’t need to add this parameter
makeIntermediateVGF=Set to true if this is an intermediate level used for the hierarchy only, not to be selected by the user. An example of this would be Sectional Centers, which is not selectable, but part of the ZIP code hierarchy.  Most vgfs are NOT intermediate levels, so you can usually leave this out.
optimize=If True, it tries to roll up all the block groups into a tract or tracts into a county in order to minimize the data that is needed.  This will happen in the exact reverse of how the level is seen in the pick geography tree in the gui.  The default is set with by the data set. For record level builds, the default is false.  As a rule, leave this parameter out.

 

ALIAS VGFS

Alias VGFs are pretty simple:  If you have a geography level already in your Allocate Tree, Say Zip Codes, and you want to get to that same data but through a different Geographic hierarchy (ZIPs by State, ZIPS by County), you can build an Alias vgf to the “base” level (ZIPs).  The Alias VGF is nothing more than a map to the ‘base’ level.  There is no data associated with it in any way.  The data is pulled from the base level.

These can also be built via the Allocate desktop interface.

The sample provided is: ALIAS_ZIPs_by_DMA.xml.
Sort requirement:  On the keyField field.

For an Alias-type build, there are also 3 general sections in the XML:

<InputFile> parameters:
path= path to the source file.  table=If the source is an Access .mdb, this is the table name.
keyField=The fixed-length Key field for the geography. Because of the nature of an Alias vgf, this Key needs to start with the parent key.  (e.g. For Zips by State, this would be 0880301)
altkeyField=The Key of the Alias Level from which the data is being pulled (e.g. 80301)

 

<OutputFile> parameters:
path=the path to the output.  Think about naming conventions that make sense.  Must end with the .vgf suffix.

 

<Params> Parameters:
longName=The name that the user sees in the geography tree
shortName=The ‘internal name’ of the vgf.  Avoid Spaces and keep to all Uppercase, as a rule.
parentShortName=The shortname for the parent for the geography you are building (e.g. STATE for ZIPS by State).
aliasShortName=The shortname of the level from which the data will be pulled (e.g. ZIPS for a Zips by State alias).
autoRegisterResult=When set to True, the vgf will be registered in the Allocate dataset to which it was built, so that next time the dataset is opened in the Allocate desktop, the vgf is available in the tree.
autoUnregisterPrevious=When set to True,will unregister a vgf with the same shortname, as long as the actual filenames differ.
logfile=Path to a log file that captures any errors in the build.  Note that is not path is specified, a log file will still be generated if errors occur, and it will default to the path containing the XML.  For this reason, most of the time, you don’t need to add this parameter

 

RECORD LEVEL VGFS

Record level vgfs cannot be built from the Allocate desktop, only via the VGF CREATE utility.  These are “advanced” vgf builds that allow you to construct geographies that pull data from other levels of geography in the dataset.  Testing is critical to ensure the build is as expected. 

There are essentially two different types of record level geography builds:  In the first, a geography, say a trade area, consists of 3 ZIP Codes, such that every time you pull data for this trade area, the data represents an aggregation of those 3 ZIP Codes.  In the second, the geography might represent some proportion of the data for a lower level:  Say the Trade Area consists of 30% of the Households from ZIP Code 1, 40% of the Households from ZIP Code2, and 100% of the Households from ZIP Code 3.

Two samples are provided that represent either of the two approaches mentioned above.

RECORDLEVEL_Full_US.xml:  Rolls up all the states to the US level.
MakePointZipVGF.xml: A proportional build.  Source data is not provided for this example.

Sort requirement:  On the keyField, then demoKeysShortNameField, then the demoKeysKeyField  

There are four sections of a record level vgf:
<InputFile> parameters:
path= path to the source file.  File must be sorted on the fixed-length Key field.
table=If the source is an Access .mdb, this is the table name.
nameField= the field in the source file containing the Name of the geography.
keyField=The fixed-length Key field for the geography. NOTE:  If this geography has a parent, the Key needs to start with the parent key. 
altKeyField=A third column in the source data that represents the “display” key.  Basically, if the Key starts with a parent, but you don’t want to user to see that, make this the base key.  So if this is Zips by State, the Key is 0880301 and the AltKey is 80301.
demoKeysShortNameField=The fieldname in the source data that contains the shortname of the geography you are building from.  For example if this is a Full US vgf build, you might have a field called DEMOKEYS_SHORTNAME where the values for all rows would be the same:  The short name STATE.
demoKeysKeyField=The fieldname in the source data that contains the fixed length key that relates to the DemoKeysShortNameField.  In the Full US example, you would have one row with each State FIPS code.
percentHouseholdWeightField="PercentHH"
percentPopWeightField="PercentPop"
percentCountWeightField="PercentCount"

The above three parameters reference the relevant fieldnames when building a proportional vgf. These types of builds are rare and these fields should be used with clear knowledge of the outcome.  Say you are building a trade area where Trade Area 1 consists of  40% of ZIP Code A Households, 30% of ZIP Code A Population, and 100% of ZIP Code A square mileage.  The numbers in the HH, Pop, and Count fields would be .4, .3, and 1.

If you aren’t doing a proportional build, set these to “” or leave them out.

<OutputFile> parameters:
path=the path to the output.  Think about naming conventions that make sense.  Must end with the .vgf suffix.

  <Params> Parameters:
longName=The name that the user sees in the geography tree
shortName=The ‘internal name’ of the vgf.  Avoid Spaces and keep to all Uppercase, as a rule.
parentShortName=The shortname for the parent for the geography you are building (e.g. STATE for ZIPS by State).
makeIntermediateVGF=Set to true if this is an intermediate level used for the hierarchy only, not to be selected by the user. An example of this would be Sectional Centers, which is not selectable, but part of the ZIP code hierarchy.
createPolygons=Set this to False if you have a spatial file input.  As a rule, always have a spatial file input. 
aliasShortName=The shortname of the level from which the data will be pulled (e.g. ZIPS for a Zips by State alias).
autoRegisterResult=When set to True, the vgf will be registered in the Allocate dataset to which it was built, so that next time the dataset is opened in the Allocate desktop, the vgf is available in the tree.
autoUnregisterPrevious=When set to True,will unregister a vgf with the same shortname, as long as the actual filenames differ.
logfile=Path to a log file that captures any errors in the build.  Note that is not path is specified, a log file will still be generated if errors occur, and it will default to the path containing the XML.  For this reason, most of the time, you don’t need to add this parameter
optimize=If True, it tries to roll up all the block groups into a tract or tracts into a county in order to minimize the data that is needed.  This will happen in the exact reverse of how the level is seen in the pick geography tree in the gui.  The default is set with by the data set. For record level builds, the default is false.  As a rule, leave this parameter out.
autoGenerateKey=if this is set to True, the KeyField will not be used.  The AltKeyField can still be used, but as always, is optional.  HARDLY EVER USED.
largeLoad=Set this to True if your load is very large (greater that 1,000,000 records or so) and the loader is running out of memory.  This will cause the load to work in chunks small enough to fit in memory.  The records MUST be presorted and the key lengths must all be the same.  It is also incompatible with optimize="true" and autoAssignParent="true".  HARDLY EVER USED.

 Record Level Notes:
ParentShortName and AutoGenerateKey
If there is both a parent short name and AutoGenerateKey="True", the keys will be generated to fall within a parent when the centroid of the generated polygon falls within the parent.  This will be MUCH slower for most builds, especially when the VGF is for a small region, but the parent is national.  HARDLY EVER USED

 

<SpatialInputFile> parameters
If you use this section, it requires that createPolygons=false.  You can use this to specify the polygons for a record based load.  The input file must be sorted by key, as well as the main input file must be sorted by key.  It supports .tab, .mid/mif .shp, .geo and .sdf if you have the autodesk sdf toolkit installed.  You can load points, lines or polygons into a VGF.  AS A RULE, YOU WANT TO PROVIDE THE SPATIAL INPUT FILE AND set  createPolygons=false.

path=The path to the spatial file
keyField=The name of the key field.  NOTE: This must match the keyField parameter above in the Input section.

 

Once the XML file is complete, you need to identify the registry entry for the dataset to which you are building the vgf file.  To do this, goto Start…Run..regedit. Navigate the folder structure: HKEY_LOCAL MACHINE/SRC/PORTFOLIO/5.60.  The folders at this level are essentially the internal names of the dataset (e.g. SRC_US_AGS_04A).  This is the dataset name you need.

Once complete, you have everything you need to run this via command line as follows, assuming the VGF_CREATE_CMD.EXE utility is located in Z:\Temp.

Z:\Temp\VGF_CREATE_CMD.EXE  <<dataset>> <<xml file name>>
For e.g:
Z:\Temp\VGF_CREATE_CMD.EXE  SRC_US_AGS_04A RECORDLEVEL_Full_US.xml