Solocast API

Overview
'C' API
Workspace API Commands
NewProfile API Commands
Example
Solocast Xml API (Primarily for getting info about the dataset and profiles)

Change List

6.1.50.6
- In_ProfileSet_Summary and In_StandardGeography_Summary have added parameters for Name and FieldName
6.1.50.5
- In_Demographic_Input no longer requires the file format #. It is still optional.

Overview

This represents the most current version of the Solocast API. Consider this documentation in BETA form (at best), however the API itself is stable and is powering several products.

'C' API

int SC_Open(const char * pDBSetName, char * pError);

This initiates an SoloCast session. The session must be closed by SC_Close

Argument Description

Return (int) 0 if failure (check pError), a non-zero handle if success

const char * pDBSetName The name of the dataSet, usually "USA" or "CANADA"

char * 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

int SC_Close(int handle);

Ends an Solocast session and frees up all resources immediately.

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

const char * SC_GetLastError(int handle);

Gets the last error from the Solocast engine.

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

int SC_LoadWorkspace(int handle, const char *pWorkspace);

Loads a workspace into Solocast. USe Run...() to get actually return the output.

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

const char * pWorkspace A newline delimeted string with the workspace to be loaded. See NewProfile API Commands.

int SC_Run(int handle);

Runs the currently loaded Workspace. You must have previously called SC_LoadWorkspace.

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

const char * SC_RunReport(int handle);

Use this function to return a report directly without ever having written it to a file. This is useful for writing code that will sit on an internet server. If the output specified is not a report, it will still be written as a file (a file name is required) and the returned string will be empty (unless there was an error).

When running a report with this function, an output file name should not be specified.

Argument Description

return (const char *) The HTML text of the report or the text of any Errors that may have happened.

int handle A handle returned by SC_Open

int SC_CreateNewProfileSet(int handle, const char * pCommands);

Creates a new Profile Set

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

char char * pCommands A newline delimeted string with information to create the new profile set. See NewProfile API Commands

int SC_DeleteProfile(int handle, const char * pProfileSet, const char *pProfileName); (Added in 6.0.55)

Creates a new Profile Set

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

chonst char * pProfileSet The Profile Set

chonst char * pProfileName The Profile to delete from the profile set

int SC_SetHelpPath(int handle, const char * pHelpPath);

This is used primarily for web applications... It sets the root of the CA Help. Since reports link directly into the Solocast/TProCA help for cluster descriptions, it must know where to find it. On web applications this means a very different thing than on desktop applications, As the web path usually starts with "http://..."

Argument Description

Return (int) non zero if success, 0 if failure (use GetLastError for more info)

int handle A handle returned by SC_Open

char char * pHelpPath The path to the root of the help. This needs to refer to the CA folder.

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

The order of the workspace commands does not matter. 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)

Commands

Cluster_Select(Number Cluster, ...)

This selectes the clusters to be included for output/processing. If this command is not specified, all clusters will default to being selected for output/processing.

Argument Description

Number Cluster A single cluster number to be selected

... The previous parameter can be repeated as many times as necesary.

Cluster_SelectAll()

This is included just for completness. The default with no cluster selection will be to have all of them selected.

Compare_Demographic(Enum DemographicVar)

This sets the comparison demographic variable.

Argument Description

Enum DemographicVar Valid values in the US are (this may vary by country and language):
"Household"
"Person"
"Adult"
"Adult Female"
"Adult Male"

Compare_Methodology(Enum Methodology, ...)

This sets the comparison Methodology for all modes other than "Detail"

Argument Description

Enum Methodology Valid values are:
"Market Potential (Users)"
"Market Potential Index (Users)"
"Market Potential (Volumetric)"
"Market Potential Index (Volumetric)"
"Spearman Correlation (Users)"
"Pearson Correlation (Users)"
"Spearman Correlation (Penetration)"
"Pearson Correlation (Penetration)"
"Penetration"
"Multiple"

... If the first parameter is multiple, than 1 or more parameters follow with a list of methodologies to output. Like the GUI, when picking multiple methodologies for output, the using selection is forced to contain only 1 profile. If it contains more than 1, it will be summarized.
When used in multiple mode, any of the valid enums from Compare_Demographic may be included as well.

Compare_Mode(Enum ComparisonMode)

This sets the comparison or output mode. "Demographic" mode is not available in the .dll. This can easily be done by using the Allocate API.

Argument Description

Enum ComparisonMode Valid values are:
"Detail"
"Rank" (analyze rank report)
"Rank1XN" (using rank report)
"Database"

Output_FilePath(String FilePath [, Enum File Format])

This sets the output file name.

Argument Description

String FilePath The output file name

Enum FileFormat Added in 6.0.60: The file format parameter is the composer file format. defaults to webhtml
The file format parameter is ignored for database files at this point (6.0.60). The file format is detected from the filePath.

~~Required if the outputting a database. Ignored otherwise.~~

~~Valid Values are (only specify the #):~~

0: Comma-Delineated Text Files (*.csv)
1: Microsoft Access 97 (*.mdb)
2: dBASE III (*.dbf)
3: dBASE IV (*.dbf)
4: dBASE 5 (*.dbf) (Not recomended, use 3 or 4)
5: Paradox 5.x (*.db)
6: FoxPro 2.6 (*.dbf)
9: HTML Export (*.htm)
10: MapInfo Interchange (*.mid/*.mif)
11: MapInfo Table (*.tab)
12: SHP File (*.shp)

OutputDemographicTemplate(...)

"Demographic" mode is not available in the .dll. This can easily be done by using the Allocate API.

OutputDetail_Cols(Enum ColumnType, Enum Column, ...)

This sets the columns for a detail report. If this is not set, the selections will be read out of the report template. This will override and replace any selections made by the report template. This command would be typicly repeated for columns of different types.

Argument Description

Enum ColumnType Valid values are:
"SelectValue"
"SelectCumulative"
"SelectRank"

Enum Column Valid values are (only specify the #):
1: "Cluster Description"
2: "Major Group"
3: "Settlement Type"
4: "[Analyze] Users"
5: "[Analyze] Base Users"
6: "[Analyze] Average Volumetric"
7: "[Analyze] Users as Percent Total"
8: "[Analyze] Base Users as Percent Total"
9: "[Analyze] Users (Scaled to entire US)"
10: "[Analyze] Base Users (Scaled to entire US)"
11: "[Analyze] Penetration"
12: "[Analyze] Penetration Index (vs [Using] Same-Cluster)"
13: "[Analyze] Penetration Index (vs [Analyze] Total)"
14: "[Analyze] Penetration Index (vs [Using] Total)"
15: "[Using] Users"
16: "[Using] Base Users"
17: "[Using] Average Volumetric"
18: "[Using] Users as Percent Total"
19: "[Using] Base Users as Percent Total"
20: "[Using] Users (Scaled to entire US)"
21: "[Using] Base Users (Scaled to entire US)"
22: "[Using] Penetration"
23: "[Using] Penetration Index (vs [Analyze] Same-Cluster)"
24: "[Using] Penetration Index (vs [Using] Total)"
25: "[Using] Penetration Index (vs [Analyze] Total)"
26: "Cluster Performance Index ([Analyze] vs [Using])"
27: "Market Potential ([Analyze] vs [Using])"
28: "Market Potential as Percent of Total"
29: "Market Potential w/ Volumetric ([Analyze] vs [Using])"
30: "Market Potential w/ Volumetric as Percent of Total"

... 0 or more additional columns

OutputDetail_Sort(Enum Column)

This sets the comparison or output mode. "Demographic" mode is not available in the .dll. This can easily be done by using the Allocate API.

Argument Description

Enum Column 1 of the colunm #'s from OutputDetail_Cols.

OutputDetail_Template(String FilePath)

This sets the template to be used for report output.

Argument Description

String FilePath Either a fully qualified file path or a file name of a file within the reports directory as specified in the registry.

OutputRank_Sort(String ProfileSetFilePath, String ProfileSetName)

This sets the profile to sort rank reports by. If it was not selected in the appropriate catagory for the rank report, it will be forced to be selected.

Argument Description

String ProfileSetFilePath A fully qualified file path to a profile set.

String ProfileSetName The full name of a profile set within the specified profileSet.

OutputRank_Template(String FilePath)

This sets the template to be used for rank report output. If not specified it will used default.srpx. Added in 6.1.4.0.

Argument Description

String FilePath Either a fully qualified file path or a file name of a file within the reports directory as specified in the registry.

OutputReport_Title(String Title)

This sets a title to appear on reports

Argument Description

String Title The title as you want it to appear. It may include HTML codes.

ProfileSet_Add(String ProfileSetFilePath)

This adds a profile set to the workspace. It is not needed as ProfileSet_Select will add any profile sets it needs to.

Argument Description

String ProfileSetFilePath A fully qualified file path to a profile set.

ProfileSet_Select(String ProfileSetFilePath, Enum SelectionPage, String ProfileSetName, ...)

This selects individual profiles from a profile set. This command can be repeated as often as necessary to build up a selection.

Argument Description

String ProfileSetFilePath A fully qualified file path to a profile set.

Enum SelectionPage Valid values are:
"From" ([Analyze])
"To" ([Using])
"Base"

String ProfileSetName The full name of a profile set within the specified profileSet.

... 0 or more additional ProfileSetNames to select from this same file.

ProfileSet_SelectAll(String ProfileSetFilePath, Enum SelectionPage)

This selects all the profiles from a profile set. This command can be repeated as often as necessary to build up a selection.

Argument Description

String ProfileSetFilePath A fully qualified file path to a profile set.

Enum SelectionPage Valid values are:
"From" ([Analyze])
"To" ([Using])
"Base"

NewProfile API Commands

This is another String API much like the workspace API except that there is no exact representation of it in the GUI like there is in the workspace API. This API replicates the functionality of the NewProfile Wizard in the GUI.

You must pick from only 1 group of Input Commands per run. If you do not specify a Base command, it will default to none in all cases. It is always better to specify every command in a group and not trust the defaults except in the case where commands are documented below as being mutually exclusive.

An Out_File command must always be specified. There is no reasonable default for that one.

Input Commands
- Database Profiles - Added in 6.1.50.5
- Demographic
- Geography
- ProfileSet
- RawData
Base Commands
- Base("None")
- Base("Automatic")
- Base("Profile", ...)
Output Commands
- Output_FilePath
- Output_Append

Specifying Database fields

There are many placesin the NewProfile API that you must specify a database field. In order to specify a field you can either use the exact field name of a 0 based field number counting from the left.

In_DB_Profile_Input(String FileName [, Enum FileFormat])

6.1.50.5 and above

Argument Description

String FileName A fully qualified path to the input file. If specifying a table name, use a | after the file name.

Enum FileFormat (optional as of 6.1.50.5) Valid Values are (only specify the #):
0: Comma-Delineated Text Files (*.csv)
1: Microsoft Access 97 (*.mdb)
2: dBASE III (*.dbf)
3: dBASE IV (*.dbf)
4: dBASE 5 (*.dbf) (Not recomended, use 3 or 4)
5: Paradox 5.x (*.db)
6: FoxPro 2.6 (*.dbf)
7: Excel 95 (*.xls)
8: Excel 97/2000 (*.xls)
9: HTML Export (*.htm)
10: MapInfo Interchange (*.mid/*.mif)
11: MapInfo Table (*.tab)
12: SHP File (*.shp)

In_DB_Profile_Demographic(Enum Demographic)

6.1.50.5 and above

Argument Description

Enum Demographic See Compare_Demographic for valid values.

In_DB_Profile_Name(String Name[, String FieldName])

6.1.50.5 and above

Argument Description

String Name A name for the new profile that will be created

String FieldName The field name for this profile when writing database output. If blank then a default field name will be manufactured. (Added in 6.0.55)

In_DB_Profile_ClusterField(String clusterField)

6.1.50.5 and above

Argument Description

String clusterField The field name of the field containing the cluster number or name. If name, it can be a partial name.

In_DB_Profile_ClusterField(String clusterField)

6.1.50.5 and above

Argument Description

String clusterField The field name of the field containing the count of users for his cluster

In_DB_Profile_BaseCountField(String clusterField)

6.1.50.5 and above

Argument Description

String clusterField The field name of the field containing the count of base users

In_DB_Profile_VolumetricField(String clusterField)

6.1.50.5 and above

Argument Description

String clusterField The field name of the field containing the total volumetric

In_Demographic_Input(String FileName [, Enum FileFormat])

Argument Description

String FileName A fully qualified path to the input file. If specifying a table name, use a | after the file name.

Enum FileFormat (optional as of 6.1.50.5)
Valid Values are (only specify the #):

0: Comma-Delineated Text Files (*.csv)
1: Microsoft Access 97 (*.mdb)
2: dBASE III (*.dbf)
3: dBASE IV (*.dbf)
4: dBASE 5 (*.dbf) (Not recomended, use 3 or 4)
5: Paradox 5.x (*.db)
6: FoxPro 2.6 (*.dbf)
7: Excel 95 (*.xls)
8: Excel 97/2000 (*.xls)
9: HTML Export (*.htm)
10: MapInfo Interchange (*.mid/*.mif)
11: MapInfo Table (*.tab)
12: SHP File (*.shp)

In_Demographic_Name(String Name[, String FieldName])

Argument Description

String Name A name for the new profile that will be created

String FieldName The field name for this profile when writing database output. If blank then a default field name will be manufactured. (Added in 6.0.55)

In_Demographic_Demographic(Enum Demographic[, Number Multiplier=1])

Argument Description

Enum Demographic See Compare_Demographic for valid values.

Number Multiplier Optional. Default=1. A number other than 1 will count each record that many times in order to produce larger profiles. This might be used with sample data.

In_Demographic_AddressFI(DbField AddressField, DbField CityOrLLField, DbField StateField, [DbField PostalCodeField])

This cannot be used with In_Demographic_CensusClusterFI. You must use 1 or the other.

Argument Description

DbField AddressField The field containing the address.

DbField CityOrLLField The field containing the city or the field containing the lastline. If lastline, than the StateField and PostalCodeFieldshould be omitted.

DbField StateField The field containing the state.

DbField PostalCodeField Optional with most geocoders. The field containing the postal code.

In_Demographic_CensusClusterFI(DbField CensusField)

This cannot be used with In_Demographic_AddressFI. You must use 1 or the other.

Argument Description

DbField CensusField The field containing the Census ID. In US that is the BlockGroup.

In_Demographic_Filter(String filterFomula)

This is for specifying a filter. It may be ignored.

Argument Description

String filterFomula A formula that is true if the record is included, false if not

In_Demographic_OutputCodedFile(String FileName, Enum FileFormat)

Specify this if you want to output a copy of the input file with Census and Cluster coding

Argument Description

String FileName A fully qualified file name

Enum FileFormat See Output_FilePath for valid values.

In_Demographic_VolumetricFI(DbField VolumetricFieldNum)

Specify this if you want to create a volumetric profile.

Argument Description

DbField VolumetricFieldNum The field containing the volumetric item. Usually a number representing recentsy, frequency or monetary value.

In_Demographic_Uncoded(Enum Method)

Specifies what the engine will do with uncoded records.

Argument Description

Enum Method Valid values are:
"Discard"
"Distribute"
"PutInLastCluster"

In_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(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, Bool IsMetric=Default)

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, Bool IsMetric=Default)

Geography("PointFileEx", String FileName, String TableName, Number FileFormat, String or Number NameField, String or Number KeyField, "PointMapObj", String Radii, Bool IsMetric=Default)

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-1 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 Bool IsMetric=Default

IsMetric: [Optional] True to use Kilometers, False to use Miles. Defaults to the setting in the Allocate GUI settings dialog.

Note: This is used for running a custom Point file.

Back to Workspace Commands Back to Top

In_Group Group( String GroupName, String, usually Number GroupKey=GroupName)

Combines the previous Geography commands selection back to the previous Group 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.

Back to Workspace Commands Back to Top

In_StandardGeography_Summary(bool SummarizeRegions, [string strProfileName, string strProfileFieldName])

If not specified this will default to False

Argument Description

bool SummarizeRegions True or False

string strProfileName optional: the name of the resulting profile. Added in 6.1.50.6

string strProfileFieldName optional: the field name of the resulting profile. Added in 6.1.50.6

In_StandardGeography_Group(...)

Not Currently supported.

In_ProfileSet_Input(String FileName. String ProfileName, ...)

This is useful for copying a profile from 1 set to another or for changing the base.

Unlike other input types, more than 1 of these can be specified

Argument Description

String FileName The fully qualified profile set file name.

String ProfileSetName The full name of a profile set within the specified profileSet.

... 0 or more addition ProfileNames within this profileSet

In_ProfileSet_Summary(bool SummarizeRegions, [string strProfileName, string strProfileFieldName])

If not specified this will default to False

Argument Description

bool SummarizeRegions True or False

string strProfileName optional: the name of the resulting profile. Added in 6.1.50.6

string strProfileFieldName optional: the field name of the resulting profile. Added in 6.1.50.6

In_RawData_ProfileData(string demoVar, string dataCategory, double Value1, ..., double ValueN)

This is used for explicitly loading values into a profile.
In_RawData_ProfileData(Adult,Users,51597,70146,93413,101842,139129,...
In_RawData_ProfileData(Adult,Base,2071525,2946797,3089038,2583851,...In_RawData_RequireLicense(False)
In_RawData_PrimaryDemoVar(Adult)
In_RawData_MetaData(Source=Unknown\nMoreInfo=None)
In_RawData_Finalize("Computers: Am't spent on home PC: under $500", CPU_HOME_LT_500)
Argument Description

demoVar Can be any of the Solocast demo vars for the current data set. Can be specified either by the description or the fieldname. It must match exactly.

dataCategory

Valid values are: Users, Base or Volumetric
If Base is specified, than a Base("Profile", ...) cannot be used.

values

There must be the exact number of values that are in the current data set. (The uncoded cluster is optional.
if the dataCategory is Volumetric, the values are the total volume, not the average volume. If you have average volume, multiply it * the number of users in the same cluster 1st.
Floating point values are acceptable for all dataCategories, but probably only make sense for Volumetric.

In_RawData_RequireLicense(bool bRequireLicense)

See In_RawData_ProfileData for an example of this API.

Argument Description

bRequireLicense True to require a license to use this profile, False to not. Defaults to false if this command is ommitted.

In_RawData_PrimaryDemoVar(string demoVar)

See In_RawData_ProfileData for an example of this API.

Argument Description

demoVar Can be any of the Solocast demo vars for the current data set. Can be specified either by the description or the fieldname. It must match exactly.

In_RawData_MetaData(string metaData)

See In_RawData_ProfileData for an example of this API.

Argument Description

metaData A series of name=value pairs separated by \n. This is optional and is only used if there is more data that needs to be carried along with the profile.

In_RawData_Finalize(string profileName, string fieldName)

This API must appear after all related In_RawData_ APIs and completes a profile. Multiple profile can be loaded in a single call to the API by repeating all the commands, each profile ending with a In_RawData_Finalize command.
See In_RawData_ProfileData for an example of this API.

Argument Description

profileName The name of the profile.

fieldName The field name for this profile when writing database output. If blank then a default field name will be manufactured.

Base("None")

Create Profiles with no base values.

Base("Automatic")

Create profiles with an automatic base. The base methodology will be different for all the input types

Base("Profile", String BaseProfileSetName, String BaseProfileName)

Use a specific profile as the base

Argument Description

String BaseProfileSetName The fully qualified profile set file name.

String BaseProfileName The full name of a profile set within the specified profileSet.

Output_FilePath(String ProfileSetName)

Argument Description

String ProfileSetName The fully qualified name of the ProfileSet for output.

Output_Append(bool bAppend)

Argument Description

bool bAppend True to append to an existing output file, False to create a new output file.

Example

#include "windows.h"
#include "solocastdll.h"
#include

void main()
{
const char * pCreateString =
"In_Ring_Input(\"SRC Boulder Office\", 40.022853, -105.281088, 5, \"Miles\")\n"
"Output_FilePath(\"c:\\temp\\temp.scd\")\n";

const char * pWorkspace =
"ProfileSet_Select(\"C:\\Program Files\\MapInfoData\\TargetPro3\\Data\\usa\\Profiles\\MRI Sample.SCD\",\"To\",\"Telephony: Avg. number of calls made with calling card in avg. month\")\n"
"ProfileSet_SelectAll(\"c:\\temp\\temp.scd\",\"From\")\n"
"Compare_Mode(Detail)\n"
"Output_FilePath(\"c:\\temp\\temp.htm\")\n"
"OutputDetail_Sort(\"16\")\n"
"OutputDetail_Cols(Value,0,1,2,3,6,16,28,29)\n"
"OutputDetail_Template(\"C:\\Program Files\\MapInfoData\\TargetPro3\\Data\\usa\\Report\\Product Potential Volume Report.srp\")\n";

char buffer[256];
int handle = SC_Open("USA", buffer);

// SC_SetHelpPath(handle, "help/");

if (SC_CreateNewProfileSet(handle, pCreateString) && SC_LoadWorkspace(handle, pWorkspace))
{
std::cout << SC_RunReport(handle);

if (SC_Run(handle))
ShellExecute(NULL, NULL, "c:\\temp\\temp.htm", NULL, NULL, NULL);
}
else
MessageBox(NULL, SC_GetLastError(handle), NULL, NULL);

SC_Close(handle);

};

Public

Solocast API

Quick Launch
View All Site Content

Solocast API

Change List

Overview

'C' API

Workspace API Commands

Commands

NewProfile API Commands

Specifying Database fields

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

Parameters

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

Parameters

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

Parameters

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

Parameters

Geography("Profileset", String FileName)

Parameters

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, Bool IsMetric=Default)

Geography("PointFileEx", String FileName, String TableName, Number FileFormat, String or Number NameField, String or Number KeyField, "PointMapObj", String Radii, Bool IsMetric=Default)

Parameters

PointType="PointLatLong"

PointType="PointLatLong"

PointType="PointMapObj"

Parameters

Example

Public

Solocast API

Quick Launch View All Site Content

Solocast API

Change List

Overview

'C' API

Workspace API Commands

Commands

NewProfile API Commands

Specifying Database fields

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

Parameters

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

Parameters

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

Parameters

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

Parameters

Geography("Profileset", String FileName)

Parameters

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, Bool IsMetric=Default)

Geography("PointFileEx", String FileName, String TableName, Number FileFormat, String or Number NameField, String or Number KeyField, "PointMapObj", String Radii, Bool IsMetric=Default)

Parameters

PointType="PointLatLong"

PointType="PointLatLong"

PointType="PointMapObj"

Parameters

Example

Quick Launch
View All Site Content