GsInit_r - geostan_1 - 2024.01

Deprecated. Initializes GeoStan.

Syntax

GsId GsInit_r ( GsInitStruct *gis );

Arguments

*gis   Contains the following:

gsVersion   Set to GS_GEOSTAN_VERSION. Input.

options   The following table contains valid enums. Input.

Except for a few cases, you should always specify GS_FILE_ADDR_CODE and GS_FILE_Z9_CODE. For example:

GS_FILE_ADDR_CODE | GS_FILE_Z9_CODE

pGeoPaths   List of paths to search for necessary files. Input.

pZ4Dir   Name of the ZIP + 4 directory file. Input.

licFilePassword    Password for the license file. Input.

licFileName   String [GS_MAX_STR_LEN] that specifies the path and name of the license file, for example, c:\license\geostan.lic. Input.

cacheSize   Relative cache size used by GeoStan; either 0, 1, or 2. Input.

relDate   String [GS_MAX_STR_LEN] that specifies the latest data to use in initialization, in the format YYYYMMDD. Input.

status   Pointer to a long (32 bit) integer that stores details on the successfully initialized components. Output.

GeoStan uses the following constants to test each significant bit:

Return Values

Valid GsId    System initialized correctly.

NULL   GeoStan failed to initialize. This can occur for one of the following reasons:

n GeoStan did not find the necessary files. Check the Status argument to view the files GeoStan found.

n GeoStan could not find the license files or the passwords were incorrect.

n There is not enough memory for GeoStan to initialize.

n All available GSD files have expired. Indicated by GS_FILE_EXPIRED in the status argument.

GS_WARNING   If you are using GsSetFilememoryLimit, you can only call GsSetFilememoryLimit once per process. When calling GsInit_r more than once, you do not need to call GsSetFileMemoryLimit again.

Notes

GsInit_r is the recommended way to start a GeoStan application. It sets the license and expiration date, and initializes the library.

You can use GsSetFilememoryLimit to control the amount of memory used for mapped files. If you are using GsSetFilememoryLimit, call GsSetFilememoryLimit before calling GsInit_r.

Example

bool showAllMessages = true;
GsId gs;
char message[256];
char details[256];
intlu lDays;
GsInitStruct GIS;
 
/* Initialize GeoStan */
/* Complete the initialization structure */

GIS.gsVersion = GS_GEOSTAN_VERSION;
GIS.options = GS_FILE_ADDR_CODE|GS_FILE_Z9_CODE;
strcpy(GIS.pGeoPaths, "c:\\geostan\\datasets;c:\\geostan");
strcpy(GIS.pZ4Dir, "c:\\geostan\\datasets\\us.z9");
GIS.licFilePassword=43218765;
strcpy(GIS.licFileName, "c:\\license\\geostan.lic");
GIS.cacheSize=2;
strcpy(GIS.relDate,"");
GIS.status=0;
 
/* Initialize the library */
gs = GsInit_r(&GIS);
   
if ( gs == 0 || showAllMessages )
{
 while ( GsErrorHas(gs) )
  { 
   GsErrorGetEx(gs, message, details);
   printf ("%s\n %s\n", message, details); 
  }
 
 if ( gs == 0 )
  {
   /* GeoStan failed to initialize */
   printf("Unable to initialize GeoStan library, status = %04X.\n", GIS.status);
   return(1);
  }
}
 
/* GeoStan is initialized */
/* retrieve information about your GeoStan license */

lDays = GsFileStatusEx(gs, GS_STATUS_DAYS_REMAINING, 0, 0);
if ( lDays == DAYS_UNLIMITED )
{
printf("License is non-expiring.\n");
}
else
{
printf("License will expire in %d days.\n", lDays);
}
 
/* retrieve information about your GeoStan data */
lDays = GsFileStatusEx(gs, GS_STATUS_DATATYPE_STR, message, 256);
if ( lDays == GS_SUCCESS )
{
printf("GeoStan data type is %s.\n", message);
}
else
{
printf("Failed to retrieve information about data.\n");
}
 
/* do your geocoding ...*/
/* close the library */
GsTerm(gs);
return(0);