Skip to main content
Sign In |
  Help (new window)
/_layouts/images/titlegraphic.gif

Public

Go SearchAdvanced Search
Public
  
Public > Documentation > Allocate API  

Allocate API

View All Site Content

Recent Changes

Allocate API 

up.gif (166 bytes) Introduction

This documentation provides information for developers who wish to create customized applications using the Allocate Application Programming Interface (API).  The Allocate engine is used to add internal functionality for any Windows or ISAPI application development.  The Allocate engine is packaged as a 32-bit Dynamic Link Library.  Included are the concepts, functions, programming notes and sample code to assist you.

The Allocate code is written in C++ but wrapped in "ANSI C" style functions.  Therefore, any language using C calling conventions can use this engine.

  Back to Top

 

up.gif (166 bytes) Changes Since Version 6.0

  • OutputLongFieldNames got added in 6.0.03.
  • Output now accepts a default file type or -1 for auto (6.0.03)
  • Output now does ExportRPTX (6.0.52.0)
  • IgnoreInvalidGeographyKeys boolean added to the workspace.(6.0.52.0)
  • AllRunGetGeoFieldInfo added to API (6.0.52.0)
  • Batch reports run from the dll now produce an error stating the name of the index file.
  • AllGetInfo now returns FieldInfoLongName to match the addition of OutputLongFieldNames.
  • Variable Searching supported through the dll (6.0.68).
  • Geography Searching supported through the workspape (6.0.68).
  • Import Customer Data now supports polygons (6.0.68).
  • SearchGeography support Regular Expressions (6.1.0.1)
  • RestrictLicensedGeographies added in 6.1.50.4
  • AllRestrictLicensedGeographies added in 6.1.50.4
  • The following APIs have a unicode version in 6.3.75: AllOpenW, AllRunW, AllRunReportW, AllGetLastErrorW, AllFastOpenW, AllGetNumInfoW, AllGetInfoW, AllRunInitW, AllRunGetGeoFieldW, AllGetGeoInfoInitW, AllGetGeoInfoFieldW, AllGUI_CreateFormulaW, AllOpenVariableSearchW, AllGetVariableSearchResultW, AllCreateVgfW
  • Note:  AllGetReportW still returns a char * because the report will be UTF8 coded if need be.
  • Added ALLINFO_ISUNICODE to AllGetInfo added in 6.3.75
  • Added optional 3rd param to RegisterDemoFile API in 6.3.75
  • Added FieldInfoFormula option to AllGetInfo in 6.3.77

up.gif (166 bytes) Changes Since Version 5.6

  • The FilterGeography command now takes a boolean (Internal Use Only!) which subtly changes the way the filter command works. The new version uses less memory but will have different characteristics if used in conjunction with the SelectWithin command than the older filter. As such, one shouldn't use both of them together for now.
  • There is now a SelectWithinAndFilterGeography API command that takes a geography and a formula and runs the select within and filtering inline. This uses much less memory and runs much faster than a select within statement followed by a filter statement in a workspace.
  • The group API now supports an additional parameter (true/false) specifying whether to select and filter per group (true) or select and filter after the groups are all made (false) (Group documentation) (changed in 5.6.09.0).
  • In AllRunGetGeoField you can now get field # -1 which is the RawKey (changed in 5.6.15.0)
  • added GroupBegin, GroupEnd, IndexBaseGroupBegin and IndexBaseGroupEnd APIs
  • reports AllGetInfo API no longer lists the complete filename as files could have either an .rpt or .rptx extension.  The API now just returns the set of files stems sorted.

up.gif (166 bytes) Changes Since Version 5.5

up.gif (166 bytes) Changes Since Version 5.0

up.gif (166 bytes) Changes Since Version 4.0

  Back to Top

up.gif (166 bytes)  Process

The basic process for using Allocate™ in your application is:

  1. Required Files 
  2. Workspace Command Set
  3. Engine C++ Wrapper
  4. Engine 'C' Functions 
  5. Sample Code

Back to Top

up.gif (166 bytes) Required Files

Integrating the Allocate DLLl into your project.

  • AllocateDLL.h
  • Allocate45.LIB
  • Allocate45.DLL 

Back to Top

up.gif (166 bytes) Workspace Command Set

  • Create a Workspace File (.aws)

A "workspace" is the principal way of controlling the Allocate engine.  To create a string containing a valid Allocate workspace for your application you can run the Allocate37 GUI and save the workspace.  At this point, all engine functions are available within licensed areas ( a Wyoming license is included with demonstration versions).   SEE Workspace Samples

  • Reports

For reports, the workspace references an external report file (.rpt).  The location of these files is set in the registry for the database set you're using.  This is set up during the Allocate install.

Running the Workspace

Run a workspace in Allocate by passing the workspace to the engine.  This can be done in two ways:

  1. Use the AllRun Command, (the most generalized way of passing a workspace to the engine).  This creates an .htm file.  This applies to a Windows application that will then open the user's default browser to display the .htm file.
  2. Use the AllRunReport Command.  This returns the html output reflecting your workspace request as a string.  This applies to an ISAPI or Windows application where you want to edit the report before passing it to the user.

  • Output Files

From the .dll, you are limited to .csv, .mid/.mif, .dbf, and .htm for output files.  These files are created by running a workspace with the AllRun command.

  • Initialization

Before any function calls in the API can be used, the Allocate Engine needs to be initialized.  Initialization involves using the AllOpen() or AllFastOpen() command(s).  

  • Errors

See  AllGetLastError

The order of the workspace commands does not matter, except for the Group and IgnoreBadGeographyKeys commands.  String variables should be enclosed in either single or double quotes (' or ").  The goal is to create strings which contain workspace commands, and then pass those strings to the engine.  Commands must be separated by a newline character. ('\n' in 'C' or chr$(13) in Basic).

Formula Formula(String VariableName, String Expression, Bool IsIndexed, String Description=Default, String NumFormat=Default)

Allows the creation of custom variables for analysis.  Formulas are created using the variables in the available demographic files, and standard binary operators (+, -, *, /).

Parameters

 Parameter 1 String VariableName

  • VariableName: A name used to represent the new variable created by this formula.  
    For example, if you were to add variables for population aged 0-4 ("AGECY0004") and population aged 5-9 ("AGECY0509"), the new variable name might be "AGECY0009".

Parameter 2 String Expression

  • Expression:  The formula of variables to run.  
    Continuing the above example, this would be "AGECY0004+AGECY0509".

Parameter 3 Bool IsIndexed

  • IsIndexed: True if the result of this formula should be an indexed value.  If so, there must be an index base file specified in the workspace.  Variables that are aggregated by summing their values (ie Population) cannot be indexed.

 Parameter 4 String Description=Default

  • Description: [Optional]  A description of the variable that will be output in reports.
    For example, "Population aged 0-9"
  • It can be empty to accept the default and still pass a NumFormat

Parameter 5  String NumFormat=Default

  • NumFormat: [Optional] A format string consisting of a period (.) followed by a number representing precision, optionally followed by dollar sign ($) or percent sign (%).  
    For example ".2$" for $1,234.00.
  • or, it can be any of the standard unit types:
UnitType NumDecimalPlaces
Dollars 0
Dollars in (000's) 0
Households 0
Persons 2
Physical 3
Population 0
Years 1
Percent 2
Index 4
Integer 0
LatLong 6
Round 10 -1
Round 100 -2
Round 1 0
Round 10 0
Physical2 2
Dollars Round 1 0
Integer64 0
String 0
Dollars64 0
Fixed2_64 2
Fixed4_64 4
Fixed6_64 6
Dollars2_64 2

Back to Workspace Commands   Back to Top

Variable Variable(String VariableName, String Expression, Bool IsIndexed, String Description=Default)

Specifies a variable from the available demographic files for analysis.

Parameters

Parameter 1 String VariableName

  • VariableName: The name of the variable for output.  This can be any DBF valid field name and generally is the same as the expression.

Parameter 2 String Expression

  • Expression: this MUST be one of the variables in the available demographic files.

Parameter 3 Bool IsIndexed

  • IsIndexed: True if the result of this formula should be an indexed value.  If so, there must be an index base file specified in the workspace.  Variables that are aggregated by summing their values (ie Population) cannot be indexed.

 Parameter 4 String Description=Default

  • Description: [Optional]  A description of the variable that will be output in reports.
Note:  The Variable and Formula commands are very similar, however a single Variable command optimizes better and the default and format descriptions are superior.  It is required that you use at least one of these commands when creating a database, but it is not necessary for creating reports.

Back to Workspace Commands   Back to Top

Geography Geography(Type, Number GeoKey1, ..., GeoKeyN) 

Specifies a geography from the available geographic inventory for analysis.

Note: One or more Geography commands may be combined.  This command can be combined with the Group command.

Parameters

Parameter 1 Type

  • Type: The short name of a geography type from the standard geographic inventory, or any of the virtual layers in the dataset.  For example, in most US data sets, this could be one of "BG", "Tract", "County", "State", "Zip", "MSA", or "DMA", as well as any available virtual layer types.

Parameter 2  Number GeoKey1, ..., GeoKeyN

  • GeoKey1, ..., GeoKeyN:  One or more geography keys dependent on what the Type is.  For example, if Type is "State", the keys will be FIPS codes.  Geography("State", 01, 02) would select Alabama and Alaska.
Note:  This is used for running a Standard or Virtual Geography.

or...

Geography(Grid, Number TopLeftX, Number TopLeftY, Number BottomRightX, Number BottomRightY, Number Size, String Units, bool bGenerateEmpty)

 Parameters

Parameter 1  "Grid" 

  • "Grid":  This string notifies the Geography command that the selected geography will be a grid.

Parameter 2 Number TopLeftX 
Parameter 3 Number TopLeftY 
Parameter 4 Number BottomRightX 
Parameter 5 Number BottomRightY 

  • These specify the bounding rectangle to create a grid within in decimal degrees

 Parameter 6 Number Size

  • The grid size for both width and height.  Units secified by parameter 7.

 Parameter 7 Enum Units

  • Valid values are: Miles or Kilometers.

 Parameter 7 Bool bGenerateEmpty

  • if true, it will generate all grid cells.  If false, it will only generate grid cells for which there is data in the BlockCentroids file.  Use true if you are using point in polygon DemoX Files.

Back to Workspace Commands   Back to Top

or...

Geography(Radius, Number DecimalLat, Number DecimalLong, String Radii, String RootName=Default, Enum Units=Default)

 Parameters

Parameter 1  "Radius" 

  • "Radius":  This string notifies the Geography command that the selected geography will be a radius.

Parameter 2 Number DecimalLat 

  • DecimalLat:  The latitude of the central point.  For example 42.123456.

  Parameter 3 Number DecimalLong

  • DecimalLong:  The longitude of the central point.  For example 101.123456.

Parameter 4 String Radii

  • Radii: A comma separated list of distances from the central point.  A value of "1" represents all point inside 1 mile (or kilometer) from the central point.  A value of "1, 2-3" represents all points inside 1 mile from the central point, as well as all points between 2 miles from the central point and 3 miles from the central point.  This value must be in quotes.

 Parameter 5 String RootName=Default

  • RootName: [Optional]  A descriptive name of the specified geography.  Most likely this will be the name of the specified central point.  For example for analysis of demographic data within three miles of  business, the central point would be the lat/long of that business, and the RootName would be the name of the business. 

 Parameter 6 Enum Units=Default

  • Units: [Optional] Valid values are: Miles, Kilometers or Minutes.  If Minutes is specified the geography will be all points within the specified number of minutes drive time from the central point.  If this value is not specified, it will be Kilometers if the Metric Units checkbox is checked in the Allocate GUI settings dialog, otherwise it will be Miles.  This value does not need to be in quotes.

Back to Workspace Commands   Back to Top

or...

Geography(RadiusGeocode, String Address, String City, String StateProvince, String PostCode, String Radii, String RootName=Default, Enum Units=Default)

Note: This requires that a geocoder recognized by SRC's products for the particular country is properly installed in the system.

 Parameters

Parameter 1  "RadiusGeocode" 

  • "RadiusGeocode":  This string notifies the Geography command that the selected geography will be a radius.

Parameter 2 String Address 

  • The Address To be geocoded

Parameter 3 String City

  • The City of the Address

Parameter 4 String StateProvince

  • The State or Province of the Address

Parameter 5 String PostCode

  • The PostCode of the address

Parameter 6 String Radii

  • Radii: A comma separated list of distances from the central point.  A value of "1" represents all point inside 1 mile (or kilometer) from the central point.  A value of "1, 2-3" represents all points inside 1 mile from the central point, as well as all points between 2 miles from the central point and 3 miles from the central point.  This value must be in quotes.

 Parameter 7 String RootName=Default

  • RootName: [Optional]  A descriptive name of the specified geography.  Most likely this will be the name of the specified central point.  For example for analysis of demographic data within three miles of  business, the central point would be the lat/long of that business, and the RootName would be the name of the business.  If blank, the name will be the match code and 1st line of the geocode.

 Parameter 8 Enum Units=Default

  • Units: [Optional] Valid values are: Miles, Kilometers or Minutes.  If Minutes is specified the geography will be all points within the specified number of minutes drive time from the central point.  If this value is not specified, it will be Kilometers if the Metric Units checkbox is checked in the Allocate GUI settings dialog, otherwise it will be Miles.  This value does not need to be in quotes.

Back to Workspace Commands   Back to Top

or...

Geography("PolygonFile", String FileName, Number FileFormat, String or Number NameField, String or Number KeyField)

Parameters

Parameter 1  "PolygonFile" 

  • "PolygonFile":  This string notifies the Geography command that the selected geography will be coming from a polygon file.

Parameter 2  String FileName

  • FileName: The complete path to the polygon file.

 Parameter 3  Number FileFormat

  • FileFormat:  Only mid/mif (10) and SHP (12) are supported in the DLL.

 Parameter 4  String or Number NameField

  • NameField:  The name or field number of the the field containing the geography name in the polygon file.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 5  String or Number KeyField

  • KeyField:  The name or field number of the the field containing the geography key.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.
Note:  This is used for running a custom Polygon file.

Back to Workspace Commands   Back to Top

or...

Geography("Profileset", String FileName)

Parameters

Parameter 1  "Profileset"

  • "Profileset":  This string notifies the Geography command that the geography exists in a profile file.

Parameter 2  String FileName

  • FileName: The complete path to the profile set.
Note:  This is used for running a profile set.

Back to Workspace Commands   Back to Top

or...

Geography("PointFileEx", String FileName, String TableName,  FileFormat, String or Number NameField, String or Number KeyField, "PointLatLong", String or Number LatitudeField, String or Number LongitudeField, String Radii, String strUnits=Default, bool bNonOverlapping=false)

Geography("PointFileEx", String FileName, String TableName, Number FileFormat, String or Number NameField, String or Number KeyField, "PointAddress", String or Number AddressField, String or Number CityOrLLField, String or Number StateField, String or Number ZipField, String Radii, String strUnits=Default, bool bNonOverlapping=false)

Geography("PointFileEx", String FileName, String TableName, Number FileFormat, String or Number NameField, String or Number KeyField, "PointMapObj", String Radii, String strUnits=Default, bool bNonOverlapping=false)

Parameters

Parameter 1  "PointFile"

  • "PointFile":  This string notifies the Geography command that the geography exists in a point file.

Parameter 2  String FileName

  • FileName: The complete path to the polygon file.

Parameter 2  String TableName

  • TableName: The table name within the file.  Blank if this file format doesn't use tables

 Parameter 4  Number FileFormat

  • FileFormat:  Only mid/mif (10) and SHP (12) are supported in the DLL.

  Parameter 5  String or Number NameField

  • NameField:  The name or field number of the the field containing the geography name.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 6  String or Number KeyField

  • KeyField:  The name or field number of the the field containing the geography key.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 7  String PointType

  • PointType:  Must be "PointLatLong", "PointAddress" or "PointMapObj"

PointType="PointLatLong"

Parameter 8  String or Number LatitudeField

  • LatitudeField:  The name or field number of the the field containing the point's Latitude.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 9  String or Number LongitudeField

  • LongitudeField:  The name or field number of the the field containing the point's Longitude.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

PointType="PointLatLong"

Parameter 8  String or Number AddressField

  • AddressField:  The name or field number of the the field containing the Address.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 9  String or Number CityOrLLField

  • CityOrLLField:  The name or field number of the the field containing the point's City or LastLine.  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 10  String or Number StateField

  • StateField:  The name or field number of the the field containing the point's State.  Can be blank if the cityOrLLField contains a lastline  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

 Parameter 11  String or Number ZipField

  • ZipField:  The name or field number of the the field containing the point's Postal Code.  Can be blank if the cityOrLLField contains a lastline  Field number are 0 indexed, so the first field in the file is field 0, the second field is field 1, etc.

PointType="PointMapObj"

There are no further parameters for describing the point object.  This requires a spatial file format.

Parameter N-2 String Radii

  • Radii: A comma separated list of distances from the central point.  A value of "1" represents all point inside 1 mile (or kilometer) from the central point.  A value of "1, 2-3" represents all points inside 1 mile from the central point, as well as all points between 2 miles from the central point and 3 miles from the central point.  This value must be in quotes.

 Parameter N-1 String strUnits=Default

  • IsMetric: [Optional] True or Kilometer to use Kilometers, Mile to use Miles, Minute to use Drivetime minutes.  Defaults to Mile or Kilometer depending on the setting in the Allocate GUI settings dialog.

 Parameter N Bool bNonOverlapping=false

  • bNonOverlapping: [Optional] False to run regular radii, True to create non-overlapping (voronoi) polygons.
Note:  This is used for running a custom Point file.

Back to Workspace Commands   Back to Top

GroupBegin GroupBegin()

Signifies the start of a Group.  When using GroupBegin and GroupEnd, groups can be nested

Parameters

None

Back to Workspace Commands   Back to Top

GroupEnd GroupEnd( String GroupName, String, usually Number GroupKey=GroupName, Boolean SelectWithinGroup [defaults to false] )

Combines the previous Geography commands selection back to the previous GroupBegin command into one virtual Geography.  
Note: This command's results depend on what geographies have been referred to in the previous workspace calls; thus this command will have different results depending on what order it is called in.

Parameters

Parameter 1 String GroupName

  • GroupName: The name of the Group.

Parameter 2  String, usually Number GroupKey=GroupName

  • GroupKey: The key of the group (only used for file output).  This defaults to the group name.

Parameter 3  Boolean, optional bSelectWithinPerGroup (this was added in version 5.6.11).

  • If true, any filter or select withins are performed on a per-group basis.
  • If false, the select within (if any) is performed on the groups after all groups have been made.

Back to Workspace Commands   Back to Top

 

Group Group( String GroupName, String, usually Number GroupKey=GroupName, Boolean SelectWithinGroup [defaults to false] )

Combines the previous Geography commands selection back to the previous Group or GroupEnd command into one virtual Geography.  GroupBegin/GroupEnd should be used in place of this.
Note: This command's results depend on what geographies have been referred to in the previous workspace calls; thus this command will have different results depending on what order it is called in.

Parameters

Parameter 1 String GroupName

  • GroupName: The name of the Group.

Parameter 2  String, usually Number GroupKey=GroupName

  • GroupKey: The key of the group (only used for file output).  This defaults to the group name.

Parameter 3  Boolean, optional bSelectWithinPerGroup (this was added in version 5.6.11).

  • If true, any filter or select withins are performed on a per-group basis.
  • If false, the select within (if any) is performed on the groups after all groups have been made.

Back to Workspace Commands   Back to Top

SelectWithin SelectWithin( String GeographyTypeShortName)

Finds and selects all of the geographic areas of the specified type that exist within the geography selections specified in the workspace.  
Note:  Although the order of this command is not important, it requires that other Geography or Radius commands be in the workspace.  Any geography selection otherwise specified in the workspace will be replaced by this command.  It will return an error if no geographic areas were found or they were ALL unlicensed.  If some geographic areas found were licensed and others were unlicensed, it will ignore the unlicensed portion and continue with the licensed selection.

Parameters

Parameter 1 String GeographyTypeShortName

  • GeographyTypeShortName: The short name of the geography type to search for.  This must be one of the native built in types.  For example, if a workspace contains the command Geography("State", 01), Alabama will be selected.  If the workspace also contains the command SelectWithin("County"), the geography selection will be all licensed counties in Alabama.

Back to Workspace Commands   Back to Top

 

FilterGeography FilterGeography( String strFilterFormula)

Filters geographies by using a boolean expression. 
Note:  Although the order of this command is not important, it requires that other Geography or Radius commands be in the workspace.  Any geography selection otherwise specified in the workspace will be replaced by this command.  It will never return an error.  If 0 geographies remain selected, that may or may not be an error depending on the output mode.  If SelectWithin is used, this will be run AFTER the SelectWithin is completed

Parameters

Parameter 1 String strFilterFormula

  • strFilterFormula: The formula to filter the geographies.  Any non 0 result will be included, 0 results will be excluded.  Boolean operators return 0 or -1.  i.e.

    HHDCY>1000 && POPCY>3000 

Back to Workspace Commands   Back to Top

 

SearchGeography SearchGeography( String strGeoType, string strSearch, [bool bUseRegEx])

Find all geographies in a given type with a given name . 
Note: This adds the found geographies to the workspace.

Parameters

Parameter 1 String strGeoType

Parameter 2 String strSearch 

Parameter 3 bool bUseRegEx (Optional - Supported in 6.1.0.1)

 

Back to Workspace Commands   Back to Top

SelectWithinAndFilterGeography SelectWithinAndFilterGeography( String strGeoLeve, String strFilterFormula)

Performs a SelectWithin and a FilterGeography all at once, saving the memory required to save the entire result of the select within before running the filter. 
Note:  This command requires that other Geography or Radius commands be in the workspace after a previous group.  Any geography selection otherwise specified in the workspace will be replaced by this command.  It will never return an error.  If 0 geographies remain selected, that may or may not be an error depending on the output mode.

Parameters

Parameter 1 String strGeoLevel

  • strGeoLevel: The geography level to select within down to.  i.e. COUNTY

Parameter 1 String strFilterFormula

  • strFilterFormula: The formula to filter the geographies.  Any non 0 result will be included, 0 results will be excluded.  Boolean operators return 0 or -1.  i.e.

    HHDCY>1000 && POPCY>3000 

Back to Workspace Commands   Back to Top

 

Output Output("File", String FileName, Number FileFormat=-1, String tableName="")

Specifies an output file.

Note:  Only one Output command can be specified in a workspace.

Parameters

Parameter 1 File

  • File:  The enumeration type for file output.  There are three pre-defined enumerations: file, report, BASE.  The value of this parameter must be one of these values.

Parameter 2  String FileName

  • FileName: The full path to the output file.

Parameter 3  Number FileFormat [optional]

  • FileFormat:  The following format numbers are valid:
    -1: Auto (figures out type by ext) (Allocate 6.03 and above)
     0: Comma-Delineated Text Files (*.csv)
     1: Microsoft Access (*.mdb)
     2: dBASE (*.dbf)
     8: Excel (*.xls)
     9: HTML Export (*.htm)
    10: MapInfo Interchange (*.mid/*.mif)
    11: MapInfo Table (*.tab)
    12: SHP File (*.shp)
    13: SDF File (*.sdf) (Requires SDF toolkit be installed)
    14: MapInfo Table (*.tab)
    15: SRC Geography File (*.geo)
    16: SRC SpatialZip File (*.sz)
    17: Oracle Spatial Database (oci:)  (Requires Oracle Client be installed)
    18: OleDb Database (odb:)
    19: SRC Wrigley Database (*.wrdb)
    20: ESRI Personal Geodatabase (*.mdb)

Parameter 4  String TableName [Optional]

  • TableName: The table name for the output. Used for MDB, XLS, odb:, and oci:.  Can also be specified as part of the FileName with a |TableName.

or...

Output("Report", String FileName, String ReportTemplate, String Title, String Format=HTML)

Parameters

Parameter 1  Report

  • Report:  The enumeration type for report output.  There are three pre-defined enumerations: file, report, BASE.  The value of this parameter must be one of these values.

Parameter 2  String FileName

  • FileName: The full path to the output file.

Parameter 3  String ReportTemplate

  • ReportTemplate: The file name of the report template file.  If the path is not fully qualified  it will check the Reports folder for the current data set.

Parameter 4   String Title

  • Title: The title of the report for output.

Parameter 5   String Format=HTML

  • Format: HTML (default) or RTF.  This is supported in version 2.50.13 and later.

 or...

Output("Base", String FileName)

Parameters

Parameter 1  Base

  • Base:  The enumeration type for index base output.  There are three pre-defined enumerations: file, report, BASE.  The value of this parameter must be one of these values.

Parameter 2  String FileName

  • FileName: The output file name.

or...

Output("ExportRPTX", String FileName, string ReportType, string Graphic )

Parameters

Parameter 1  FileName

  • Name of result rptx file.

Parameter 2  String ReportType

  • Rank, Comparison, Summary.

Parameter 3  String graphic (Optional)

  • Filename of graphic to use in file.

 

Back to Workspace Commands   Back to Top

OutputLongFieldNames OutputLongFieldNames(Bool IsLongFieldNames)

Sets the file output mode to use long or short file names.  Only works with Output("File",...)

Parameters

Parameter 1  Bool IsLongFieldNames

  • IsLongFieldNames: If True to use long field names (if specified in the data load).  Defaults to True for XLS files,False for all other files.

Back to Workspace Commands   Back to Top

OutputSummary OutputSummary(Bool IsSummary)

Allows the values for all selected geographies to be summarized into one value, as if they were one geography.

Parameters

Parameter 1  Bool IsSummary

  • IsSummary: If True the output is summarized into one geography.  (This only applies if you have selected more than one geography).

Back to Workspace Commands   Back to Top

IndexBase IndexBase(String IndexBaseFileName)

Specifies an index base file for indexing variables.

Note:  This is required if one or more Variable or Formula commands specify IsIndexed=True.   

Parameters

Parameter 1  String IndexBaseFileName

  • IndexBaseFileName:  The name of the index base file to be used.  If the path is not fully qualified it will check the IndexBase folder for the current data set.

Back to Workspace Commands   Back to Top

IndexBaseGroupBegin()

Indentical to GroupBegin, except the geographies in this group become the index base.

Back to Workspace Commands   Back to Top

IndexBaseGroupEnd(...)

Indentical to GroupEnd, except the geographies in this group become the index base.

Back to Workspace Commands   Back to Top

IncludeIndexBaseValue IncludeIndexBaseValue(Bool IsIncluded)

Includes the raw value of the demographic variables from the Index Base in the value of the selected indexed variables.

Note:  This Requires that the IndexBase be specified.

Parameters

Parameter 1  Bool IsIncluded

  • IsIncluded: If True the index base values will be included as a separate geography.

Back to Workspace Commands   Back to Top

ReportParameter ReportParameter(String VariableName, String VariableValue)

This is used for dynamically substituting parameters into a report template.  Any parameter in any function in a report may be a substitution variable instead of the actual data.  This is useful if you wanted to include different images based on which user is currently using your product at run time or any other run time change.  

Note:  This requires Allocate 2.51 Service Pack 1 or better.  There is no counterpart to this in the GUI, as it is designed only for the API, however, you can create a workspace by hand with this command for the GUI and it will use it properly.  If there are any substitution parameters in the report that are not specified in the API with a ReportParameter command, the entire line will be ignored.  You may use as many ReportParameter commands as you wish.

Parameters

Parameter 1  String VariableName

  • VariableName: The name of the substitution variable that corresponds to a variable in a report template.  It must start with a #.

Parameter 1  String VariableValue

  • VariableValue: The value to be used for the report parameter at run time.

Back to Workspace Commands   Back to Top

UsingDataSet UsingDataSet(String DatasetName)

Allows a workspace to verify that the specified data set is being used.  If the specified data set is not being used, Allocate will throw an error when the workspace is run.

Note:  This command is optional.

Parameters

Parameter 1  String DatasetName

  • DatasetName: The name of the dataset.  This is a verification command, not a state-setting command.  SEE AllGetLastError

Back to Workspace Commands   Back to Top

RegisterDemoFile RegisterDemoFile(String DemoFilePath, Bool bOneTimeUse, [Bool bClearGetInfoCache])

Dynamically registers a new .Demo or .Demox file.  The variables are immediately available in the same workspace.  Any variables that come from this new Demo (or DemoX) file must be after this command in the workspace

Parameters

Parameter 1  String DemoFilePath

  • DemoFilePath: The full path to the .Demo (or .DemoX) file

Parameter 2  Bool bOneTimeUse

  • bOneTimeUse: If True, the new variables will only be available in this single workspace.  If False, they will be permanently register with Allocate

Parameter 3  [Optional] Bool bClearGetInfoCache (Added in 6.3.75)

  • bClearGetInfoCache : Set to true if you will be using the AllGetInfo API to get info about this demo file

Back to Workspace Commands   Back to Top

IgnoreInvalidGeographyKeys IgnoreInvalidGeographyKeys(bool bIgnore)

Allocate by default throws an error if it finds invalid geography keys in the workspace.  This flag changes that behavior, and must be placed before any geography commands that it needs to affect.

Back to Workspace Commands   Back to Top

RestrictLicensedGeographies RestrictLicensedGeographies(GeoKey1, ... , GeoKeyN)

A list of geokeys at the license level to restrict to as if the license files restricted to these geographies.   This is just a short cut to the AllRestrictLicensedGeographies  API and once set it will continue in force until AllClose or AllFastClose is called.  Added in 6.1.50.4

Back to Workspace Commands   Back to Top

up.gif (166 bytes) C interface (also used for MapBasic or VB)

AllSetGlobalOptions

AllOpen
AllClose

AllSetProgressCallback

AllRun
AllRunReport 
AllGetLastError

AllGetInfo
AllGetNumInfo

AllFastOpen
AllFastClose

AllRunInit
AllRunNextGeo
AllRunGetGeoField
AllRunGetGeoFieldValue
AllRunGetGeoFieldType
AllRunGetGeoFieldInfo
AllRunGetGeoFieldMaxStringLen

AllGetGeoInfoInit
AllGetGeoInfoField

AllCreateVGF

AllOpenVariableSearch
AllGetVariableSearchResult

AllGUI_CreateFormula

AllRestrictLicensedGeographies


AllSetGlobalOptions (long nOptions)

Purpose

This can (and should) be called before AllOpen or AllFastOpen ever gets called.  It sets a variety of flags that controlls the way Allocate is initialized.

Parameters

Parameter 1  long nOptions

  • nOptions: 1 or more of the following flags.  They can be added together.
    • ALL_OPTION_CacheSmall
    • ALL_OPTION_CacheMedium
    • ALL_OPTION_CacheLarge
    • ALL_OPTION_NoMemMapFile
    • ALL_OPTION_AllowDesktopAccess (5.00.52 and above)
      • When ALL_OPTION_AllowDesktopAccess is set, Allocate will occasionaly put message boxes or other dialogs on the desktop.  This should NEVER be set in a server environment.  It will also prompt the user to authenticate any license files that have not yet been authenticated while Allocate loads.

Return

void: There is no return

Back to C Engine   Back to Top

AllOpen int AllOpen(const char * pDBSetName, char * pError)

Purpose

Initiates a Allocate session. The session must be closed by AllClose.

Parameters

Parameter 1  const char * pDBSetName

  • pDBSetName: The name of a dataset.

Parameter 2  char * pError

  • pError:  A buffer to contain an error message. It MUST be a least 256 characters long. This will only be filled in if the return is 0.

Return

int: Zero if failure (check pError), a non-zero handle if success (use AllGetLastError for more information).  The returned handle will be used in all subsequent calls to the C API.

Back to C Engine   Back to Top

AllClose  int AllClose(int handle)

Purpose

Ends a Allocate session and immediately frees all resources associated with the session.

Parameters

Parameter 1  int handle

Return

int: Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

 

AllSetProgressCallback long AllSetProgressCallback(int handle, AllProgressCallback pProgressCallback)

Purpose

This is an advanced API function to allow programs to monitor the progress of a long operation and portentially to allow the user the cancel the operation.  This works with the AllRun... Commands as well as the AllCreateVgf command

Parameters

Parameter 1  int handle
Parameter 2  AllProgressCallback pProgressCallback
  • pProgressCallback:  A pointer to the callback function.  It must be declared to have the following for: 
typedef long  ( _stdcall * AllProgressCallback)(const char *pText, double dPercent);

The callback function should return 0 normally, or non-zero to cancel the Allocate operation

Return

int:  Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRun  int AllRun(int handle, const char * pParams)

Purpose

Equivalent to hitting the finish button in the GUI.  It produces a report or output file in similar fashion to the GUI.

Parameters

Parameter 1  int handle
Parameter 2  const char * pParams
  • pParams:  A pointer to the workspace buffer.

Return

int:  Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRunReport const char * AllRunReport(int handle, const char * pParams)

Note:  Since there is no output file or directory, images associated with the report are NOT copied anywhere.

Purpose

Note:  ("") means an empty string.

This function is exactly the same as AllRun except:

  • It can only be used for reports.
  • The report output file name specified in the workspace string should be blank ("").

Parameters

Parameter 1  int handle
Parameter 2  const char * pParams
  • pParams:  A pointer to the workspace buffer.

Return

const char *:  A pointer to the HTML source for the report.

Back to C Engine   Back to Top

AllGetLastError  const char * AllGetLastError(int handle)

Purpose

Gets the last error from the Allocate engine.

Parameters 

Parameter 1  int handle

Return

const char*: A pointer to the user-friendly error message.

Back to C Engine   Back to Top

AllGetInfo long AllGetInfo(int handle, const char *pWhichData, long nWhichValue, char *pReturnData)

Purpose

Provides a variety of information from the engine, like reports, index base files, data sets, etc.

Parameters

Parameter 1  int handle

Parameter 2  const char *pWhichData


Parameter 3  long nWhichValue

  • nWhichValue: For data requests with more than one data return, the 0 based
    index of the requested data. Use AllGetNumInfo(...) to find out how many items there are.


Parameter 4  char * pReturnData: A pointer to a string buffer to receive the data.  The buffer must be at least 256 characters.

Table 1 Valid Values

Valid Values for pWhichData

"Version"

/* A list of the report templates in the reports dir.*/

"Reports" 

/* A list of the report templates in the reports dir.*/

"IndexBaseFiles"

/* A list of the report templates in the reports dir.*/

"CurrentDBSet"

/* The current database set.*/

"DBSets"

/* A list of all available database sets.*/

"ShortGeoNames"

 

"LongGeoNames"

 

"AliasShortGeoNames"

/* this will return a list of the alias levels short name */ /* if one exists, otherwise it will return the same as ShortGeoNames */

"GeoIsIntermediate" True or False if the GeoLevel is intermediate
LicenseLevel The short name of the license level
   
The Follow are used for retrieving all the information about variables.  The are all used together and have the same # of results.  
"FieldInfoName"  
"FieldInfoDesc"  
"FieldInfoCat"  
"FieldInfoSubCat"  
"FieldInfoUnits"  
"FieldInfoVintage"  
"FieldInfoYear"  
"FieldInfoAction"  
"FieldInfoWeight"  
"FieldInfoIsLicensed"  

"FieldInfoDataTable"
"FieldInfoLongName"
"FieldInfoFormula"

Return

long: Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllGetNumInfo long AllGetNumInfo(int handle, const char *pWhichData)  

Purpose

Use this to get the number of items that will be returned by AllGetInfo.

Parameters

Parameter 1  int handle

Parameter 2  const char *pWhichData

Return

long: If there was an error this value is -1.  Otherwise, the number of data elements available.

Back to C Engine   Back to Top

AllFastOpen int AllFastOpen(const char * pDBSetName, char * pError)  

Note: The Allocate engine is thread safe between DIFFERENT instantiations, it is NOT thread safe within a single instantiation.

Purpose

Basically the same as AllOpen. Use this if you are creating and closing Allocate a number of times within a single process. You MUST pair this with a AllFastClose. This would typically be used in an internet, or other multi-threaded, environment. 

Parameters

Parameter 1  const char * pDBSetName

  • pDBSetName: The name of a dataset.

Parameter 2  char * pError

  • pError:  A buffer to contain an error message. It MUST be a least 256 characters long. This will only be filled in if the return is 0.

Return

int: Zero if failure (check pError), a non-zero handle if success (use AllGetLastError for more info).  The returned handle will be used in all subsequent calls to the C API.

Back to C Engine   Back to Top

AllFastClose  int AllFastClose(int handle)

Note: This will NOT free up any resources. It will only add this handle back into the pool that AllFastOpen can return. The resources will free up when the DLL terminates.

Purpose

Basically the same as AllClose. Use this if this handle was created by AllFastOpen.

Parameters

Parameter 1  int handle

Return

int: Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRunInit long AllRunInit(int handle, const char *pParams)

Purpose

Use this function to initialize the Allocate engine for getting data directly from the engine to code. This bypasses the report writer and database output. The Output command should not be used in the pParams. This returns the numbers of fields that will be available from AllRunGetGeoField.  AllRunNextGeo must be called before any data can be retrieved.

Parameters

Parameter 1  int handle
Parameter 2  const char * pParams
  • pParams:  A pointer to the workspace buffer.

Return

long: Zero if failure, otherwise the number of fields being returned.

Back to C Engine   Back to Top

AllRunNextGeo  long AllRunNextGeo(int handle)

Purpose

Use this for running the next geography when getting data out directly.  This should be called after AllRunInit

Parameters

Parameter 1  int handle

Return

long: Zero if failure, a non-zero handle if success (use AllGetLastError for more information). 

Back to C Engine   Back to Top

AllRunGetGeoField long AllRunGetGeoField(int handle, long nFieldNum, char * pReturnData)

Purpose

This gets one field of information from the current geographic area (AllRunNextGeo).  The name is always the first field (field 0), the key is always the second field (field 1).  The demographics values start with the third field and they appear in the same order as the Variable and Formula commands in the pParams in AllRunInit.  The numbers are all converted to strings using the correct number of digits and $'s and %'s as necessary.

Parameters

Parameter 1  int handle
Parameter 2  long nFieldNum
  • nFieldNum:  0=Name, 1=Key, 2 and above are the variables in the order that they were specified in the pParams to AllRunInit   (new in 5.6.15) There is a special field (-1) that returns the RawKey that is used for building the tree. This Key would not normally be outputted in a database output

 Parameter 3  char * pReturnData

  • pReturnData: A pointer to a string buffer to receive the data.  The buffer must be at least 256 characters.

Return

long:  Zero if failure, a non-zero handle if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRunGetGeoFieldValue  long AllRunGetGeoFieldValue(int handle, long nFieldNum, double * pReturnData)

Purpose

Same as AllRunGetGeoField except it returns the value as a double.  Fields start with the third field.  The first and seconds fields are the name and key, respectively, and cannot be returned by this function.  Make sure to check  AllRunGetGeoFieldType before using this function, because it is not valid for string fields.

Parameters

Parameter 1  int handle
Parameter 2  long nFieldNum
  • nFieldNum:  0=Name, 1=Key, 2 and above are the variables in the order that they were specified in the pParams to AllRunInit  

 Parameter 3  double * pReturnData

  • pReturnData: A pointer to a double precision floating point variable (8 bytes) to receive the return value. Trying to get the name and key fields as with this function will return 0.

Return

long:  Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRunGetGeoFieldType  long AllRunGetGeoFieldType(int handle, long nFieldNum)

Purpose

Related to AllRunGetGeoField and AllRunGetGeoFieldValue.  This function gives the actual type of the variable so you could decide which of the above functions to call.  Added in Allocate 5.00.10.

Parameters

Parameter 1  int handle
Parameter 2  long nFieldNum
  • nFieldNum:  0=Name, 1=Key, 2 and above are the variables in the order that they were specified in the pParams to AllRunInit  

Return

long:  1 for double, 2 for String, 0 for failure (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllRunGetGeoFieldInfo  long AllRunGetGeoFieldType(int handle, long nFieldNum, int infoType)

Purpose

Returns information about the variables specified in the workspace.

  • nWhichField: Which field to query information on.
  • infoType:  currently either:
    • 1 field type, then this method functions identically to AllRunGetGeoFieldType
    • 2 Number of decimal places used to display this variable
    • 3 Numeric length of this item in bits, currently either 32 or 64 depending on variable.

Back to C Engine   Back to Top

AllRunGetGeoFieldMaxStringLen  long AllRunGetGeoFieldMaxStringLen(int handle, long nFieldNum)

Purpose

Related to AllRunGetGeoField and AllRunGetGeoFieldValue.  This function returns the maximum string length of this field.  This is valid even for numeric fields, because it is always valid to get a string representation of the field. Added in Allocate 5.00.10.

Parameters

Parameter 1  int handle
Parameter 2  long nFieldNum
  • nFieldNum:  0=Name, 1=Key, 2 and above are the variables in the order that they were specified in the pParams to AllRunInit  

Return

long:  MaxStringLength, 0 for failure (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllGetGeoInfoInit  long AllGetGeoInfoInit(int handle, const char *pShortName, const char * pKey, const char * pRelation)

Purpose

This will request information that would allow a user to build the entire geography tree as seen in the GUI, including any virtual layers.  Use AllGetGeoInfoField  to get the information.

Parameters

Parameter 1  int handle
Parameter 2  const char *pShortName
  • pShortName:  The short name of the Geo type. These can be looked up using AllGetInfo with the "ShortGeoNames" option.

 Parameter 3  const char * pKey

  • pKey: The key of this geography. Use an empty string to begin.  

 .Parameter 4  const char * pRelation

Table 2 Valid Values

Valid Values for pRelation

"Parent"

/* gets information about the parent of this key.*/

"Node"

/* gets information about this key.*/

"Children"

/* gets information about the children of this key.*/

Return  

long: Returns the number of items in the result set, 0 if failure.

Back to C Engine   Back to Top

AllGetGeoInfoField  long AllGetGeoInfoField(int handle, long nWhichResult, const char *pWhichData, char * pReturnData)

Purpose

This will actually get the data that was requested by AllGetGeoInfoInit.

Parameters

Parameter 1  int handle
Parameter 2  long nWhichResult
  • nWhichResult:  The index of the geography to get data for.  This must be a valid index, >= 0 and < the return value from AllGetGeoInfoInit.

Parameter 3  const char *pWhichData

Parameter 4  char * pReturnData

  • pReturnData: A pointer to a string buffer to receive the data.  The buffer must be at least 256 characters.

Table 3 Valid Values

Valid Values for pWhichData

"Name" 

The display name of this geography.

"Key"

The key of this geography.

"DisplayKey" The display version of the key. (Otherwise known as "AltKey")
"LevelShortGeo" The short geography name of the display level in the tree.

"LevelLongGeo"

The long geography name of the display level in the tree.
"IsLicensed" True if licensed, False if not.

Return

long: Zero if failure, non-zero if success (use AllGetLastError for more information).

Back to C Engine   Back to Top

AllCreateVgf long AllCreateVgf(int handle, const char * pXml);

Purpose

Use this function to Create a VGF file

Parameters

Parameter 1  int handle
Parameter 2  const char * pXml
  • pXml:  A string of ZML representing the VGf build command. See VGF Loader API

Return

long: return is non-zero on success or 0 for failure

Back to C Engine   Back to Top

AllGUI_CreateFormula long AllGUI_CreateFormula(int handle, const char * pFormulaBuffer, long nFormulaBufferSize );

Purpose

Use this function to allow a user to create a formula.  This will pop up a dialog box prompting the user to create a formula. Obviously this should never be used in a server environment since the GUI will not be available.

Parameters

Parameter 1  int handle
Parameter 2  const char * pFormulaBuffer
  • pFormulaBuffer:  A pointer to the buffer to accept the user created formula
Parameter 3  long nFormulaBufferSize
  • nFormulaBufferSize: the size of the buffer. An error will be returned if it is not long enough.

Return

long: return is non-zero on success or 0 for failure

Back to C Engine   Back to Top

AllOpenVariableSearch
unsigned AllOpenVariableSearch( int handle, const char* strSearchFor, const char* strYear, int bSearchVarName, int bAddToSel, unsigned *r_nNumFound );

Purpose

Open a search on variables.  There can only be one open search per allocate handle.

Parameters

Parameter 1  int handle
Handle to allocate object returned by AllOpen or AllFastOpen.
Parameter 2  const char* strSearchFor
String to search for.  This can be a partial name if you are searching variable names.  Else it will only match the whole string.
Parameter 3  const char* strYear
The vintage.  If this is null, all vintages are searched.
Parameter 4  int bSearchVarName
True if you want to search in variable names.   False if you want to search in variable selections.
Parameter 5  int bAddToSel
True if you want to add to the current selection.
Parameter 6  unsigned* r_nNumFound
Pointer to return count of items found.  Error if NULL

Return

long: Count of unlicensed variables found.

Back to C Engine   Back to Top

AllGetVariableSearchResult
int AllGetVariableSearchResult( int handle, unsigned index, char* outBuffer );

Purpose

Open a search on variables.  There can only be one open search per allocate handle.

Parameters

Parameter 1  int handle
Handle to allocate object returned by AllOpen or AllFastOpen.
Parameter 2  unsigned index
Index of the desired result.
Parameter 3  char* outBuffer
Buffer to return result in.  Must be at least 512 bytes long

Return

long: Count of unlicensed variables found.

Back to C Engine   Back to Top

 

AllRestrictLicensedGeographies
int AllRestrictLicensedGeographies( int handle, const char* *pGeoList );

Purpose

This will add a additional license restriction to this set of geographies that will be identical to the license file with the same list Once set, to clear call it with an empty pGeoList.

Parameters

Parameter 1  int handle
Handle to allocate object returned by AllOpen or AllFastOpen.
Parameter 2  const char * pGeoList
A Comma separated list of licensed geographies. Empty String for all

Return

long: return is non-zero on success or 0 for failure

Back to C Engine   Back to Top

up.gif (166 bytes) C++  Wrapper

class FastAllocate
This is a wrapper for the "C" API.  It does not provide any different functionality, it helps manage the connections.   It uses the AllFastOpen and AllFastClose versions of Open and Close.

This class wraps all of the functions in the "C" API except those having to do with opening and closing the library.

These functions behave identical to their "C" counterparts, except they don't take a handle as the first parameter.

The constructor FastAllocate::FastAllocate only takes one parameter that is the database set.  It can throw an error AllException.  

Note:  This error is NOT derived from CException.

Back to Top

up.gif (166 bytes) Samples

Note:  A semicolon (;) represents an Allocate comment, Bold represents the workspace code

Sample 1

; When created from Allocate GUI it is an .aws file

; Name of your geography.  This command only validates that you are set to the named dataset.  The actual dataset chosen is determined by the ALLOPEN command.  [Optional] Use this command if you need to be absolutely certain that the report you are viewing is that of the dataset you've chosen.
UsingDataSet(USA)

; SEE RADIUS
Radius(40.038109, -105.250851, "3, 5", "Street: 3825 IRIS AVE")

; SEE OUTPUTREPORT
Output(Report,C:\Program Files\MapInfoData\Allocate\sample1.htm,Update Report.RPT,"Sample1 Update")

; SEE OUTPUTSUMMARY
OutputSummary(False) 

HTML SAMPLE1

Sample 2

; When created from Allocate GUI it is an .aws file

;Name of your geography.  This command only validates that you are set to the named dataset.  The actual dataset chosen is determined by the ALLOPEN command.  [Optional] Use this command if you need to be absolutely certain that the report you are viewing is that of the dataset you've chosen.
UsingDataSet(USA)

;  SEE GEOGRAPHY
Geography(State,56)

; SEE OUTPUTREPORT
Output(Report,C:\Program Files\MapInfoData\Allocate\sample2.htm,Update Report.RPT,"Sample2 Update")

; SEE OUTPUTSUMMARY
OutputSummary(False)

; SEE VARIABLE
Variable(DENSITY5Y,DENSITY5Y,False)
Variable(POP5Y,POP5Y,False)

HTML SAMPLE2

Back to Top

Allocate® is a registered trademark of SRC, LLC

Last Updated

 

Last modified at 7/28/2009 10:37 AM  by Ned Harding