GSINITWP - geostan_1

GSINITWP - geostan_1 - 2024.01

GeoStan Geocoding Suite Reference for Windows, Linux, and z/OS

Product type

Software

Portfolio

Locate

Product family

GeoStan Geocoding Suite

Product

GeoStan Geocoding Suite > GeoStan

Version

2024.01

Language

English

Product name

GeoStan

Title

GeoStan Geocoding Suite Reference for Windows, Linux, and z/OS

2024

First publish date

1994

Last updated

2024-07-29

Published on

2024-07-29T23:01:18.924000

Initializes GeoStan using properties.

Syntax

01 INIT-PROP-LIST                Defined in GEOSTAN copy member.
01 STATUS-PROP-LIST              Defined in GEOSTAN copy member.
01 GSID                          PIC S9(9) BINARY.
CALL 'GSINITWP' USING INIT-PROP-LIST,STATUS-PROP-LIST, GS-ID.
IF GS-ID EQUAL ZERO DISPLAY '** ERROR ** GEOSTAN FAILED TO INITIALIZE' PERFORM GET-ERROR-MSG

Arguments

INIT-PROP-LIST, STATUS-PROP-LIST Pointer to property list structure. Input.

GSID ID returned by GSINITWP for the current instance of GeoStan. Input.

GSINITWP property options:

Property Name	Description
GS-INIT-CACHESIZE	Relative cache size used by GeoStan. Controls the amount of memory that GeoStan allocates to store temporary street data during address processing. A smaller cache may slow the performance of GeoStan. A cache size of 2 gives best performance, but uses more memory. Values: 0, 1 or 2.
GS-INIT-DATAPATH	List of paths to search for necessary files.
GS-INIT-DPV	Initialize DPV.
GS-INIT-DPV-DATA-ACCESS	Indicates the type of files to load and how to access the files. The following contains the possible values. • DPV-DATA-FULL-FILEIO — dpvh.db accessed via file I/O and Micro (U) memory model. This is a default value. • DPV-DATA-FULL-MEMORY — dpvh.db loaded completely into memory and Huge (H) memory model (about 1.3 GB). Use this option to gain performance improvement by reducing repetitive file I/O. • DPV-DATA-SPLIT-FILEIO — dpvs.db accessed via file I/O and Micro (U) memory model. Use if your file is sorted by ZIP Code and you have limited memory. Uses a split data format that separates the DPV data file into multiple smaller files, based on the first 2 digits of the ZIP Code. If you sort your mailing file by ZIP Code, you can use this value to bring the relevant portion of the DPV file into memory. This process uses 32 MB of storage, but reduces the number of I/O requests that normally occurs when you use the full DPV data. file. • DPV-DATA-SPLIT-MEMORY — dpvs.db loaded completely into memory and Huge (H) memory model (about 965 MB) • DPV-DATA-FLAT-FILEIO — dpv.db accessed via file I/O and Micro (U) memory model. • DPV-DATA-FLAT-MEMORY — dpv.db Large (L) memory model (about 70 MB). This configuration will provide the best performance overall.
GS-INIT-DPV-DIRECTORY	String that specifies the directory containing DPV data.
GS-INIT-DPV-SECURITYKEY	Security key for product authorization.
GS-INIT-FILE-MEMORY-LIMIT	Note: This property only applies to 64-bit applications. When GeoStan is initialized, it will memory-map as many data files into memory as the GS-INIT-FILE-MEMORY-LIMIT allows. The default value of 16 GB is sufficient for memory-mapping two streets and two points datasets. Memory mapping your data files can provide a 10-15% performance improvement compared to mapping none of them. However, if your environment has memory constraints, you can set the GS-INIT-FILE-MEMORY-LIMIT to the number of megabytes you can afford. This initialization property can only be set once per GeoStan executable process. If you attempt to set this property again (i.e., on a separate thread), the request is ignored. If all of the data files cannot be memory-mapped in the space provided, the status property GS-STATUS-FILE-MEM-SYS-EXCDD is set to true. To see how much virtual memory is being used for memory-mapping data files, query the status property GS-STATUS-MEMORY-USED.
GS-INIT-GEOSTAN-ID	If NULL, this means initialize GeoStan.
GS-INIT-GSVERSION	GeoStan version.
GS-INIT-LACSLINK	Initialize LACS^Link.
GS-INIT-LACSLINK-DIRECTORY	Directory of Lack^Link data.
GS-INIT-LACSLINK-SECURITY-KEY	Security key.
GS-INIT-LICFILENAME	License file name.
GS-INIT-OPTIONS-ADDR-CODE	Open files needed for address standardization and geocoding.
GS-INIT-OPTIONS-SPATIAL-QUERY	Open spatial query files.
GS-INIT-OPTIONS-Z9-CODE	Open files needed for ZIP centroid geocoding.
GS-INIT-OPTIONS-ZIP-PBKEYS	Open the file needed to return PreciselyIDs for ZIP centroid locations in Master Location Data. If the ZIP centroid file (zipsmld.gsd) that contains PreciselyIDs loaded successfully, GS-STATUS-FILE-ZIP-PBKEYS is True. (Default value = False). When an address point is not available for an address in Master Location Data, this option returns a ZIP centroid and the PreciselyID unique identifier, which can be used to unlock additional information about an address using GeoEnrichment data. To enable returning PreciselyIDs for ZIP centroid locations in MLD, theGS-FIND-Z-CODE GSFINDWP property needs to be enabled. If it is not enabled, an "E" location code is returned and the results data will not include a geocode nor PreciselyID.
GS-INIT-PASSWORD	License password.
GS-INIT-RDI-DIRECTORY	Directory containing Residential Delivery Indicator (RDI) data file, rdi.db. Max 255 characters. Requires Delivery Point Validation (DPV).
GS-INIT-RELDATE	String of the latest data to use in initialization.
GS-INIT-SUITELINK	Initializes Suite^Link
GS-INIT-SUITELINK-DIRECTORY	Directory containing Suite^Link data.
GS-INIT-Z4FILE	Name of the ZIP +4 directory file, us.z9.

Return Values

Returns the ID of the GeoStan instance that was initialized.

Prerequisites

GSPLSTCR and GSPSET*

Notes

Initializes GeoStan using a property list. Upon return, this function utilized the properties, but left the property list intact. The application owns the property lists. The status property list is guaranteed to contain properties for all defined status properties with their values properly set.

GSINITWP can be used to initialize GeoStan, DPV, and LACS^Link with a single call (if the appropriate initialization properties are in the init list). When this function successfully completes, it populates the GS-INIT-GEOSTAN-ID property in the property list referred to by the pInitProps parameter with the actual GeoStan ID.

If you invoke this function with the GeoStan ID property pre-set to a valid GeoStan ID, it will not attempt to re-initialize GeoStan. This is how GSINITWP can be used to initialize DPV and/or LACS^Link after GeoStan has already been initialized with a previous call to GSINITWP. If you intend to reuse the same initialization property list to initialize GeoStan several times you must reset the GS-INIT-GEOSTAN-ID property back to zero, or completely remove the property from the list. This informs GeoStan that you want a new GeoStan instance when you call GSINITWP.

These initialization properties are required for GSINITWP to function correctly:

GS-INIT-LICFILENAME
GS-INIT-DATAPATH
GS-INIT-PASSWORD

These initialization properties are recommended, but not required:

GS-INIT-Z4FILE (required for ZIP centroid matching).
GS-INIT-OPTIONS-Z9-CODE (required for ZIP centroid matching).
GS-INIT-CACHESIZE (to improve GeoStan performance).
GS-INIT-OPTIONS-ADDR-CODE (required for address matching).
GS-INIT-OPTIONS-SPATIAL-QUERY (required for reverse geocoding and the MBR-related functions).

All other available initialization properties are entirely optional.