Library Functions

This section includes a technical description of 500+ functions in the CS-MAP library. The descriptions are organized by the interface of which they are a part. An index is provided elsewhere in this document.

High Level Interface Functions

Functions described in this section are designed to be called from high level languages such as Visual Basic. Therefore, descriptions of most functions in this section also include a function declaration appropriate for use in Visual Basic and Delphi in addition to the standard C prototype.

CS_altdr Alternate Directory

Function CS_altdr (ByVal new_dir As String) As Integer function CS_altdr (alt_dr :PChar):Integer;
int CS_altdr (Const char alt_dir);

Normally, all functions in the Coordinate System Mapping Package library expect to find data files in the C:\MAPPING directory as defined in CSdata. CS_altdr can be used to specify an alternate directory at run time; that indicated by the alt_dir argument. CS_altdr returns zero if a coordinate system dictionary was indeed found in the directory provided; otherwise, it returns -1.

Calling CS_altdr with the NULL pointer as its argument instructs CS_altdr to use the value of the environmental variable CS_MAP_DIR as the location of the CS-MAP data files. Again a zero is returned if this was successful, -1 if not. (The string defining the name of the environmental variable name is defined in the cs_map.h header file.)

Calling CS_altdr with the alt_dir argument pointing to the null string instructs CS_altdr to use the current directory on the current drive as the location of CS-MAP data files. Again a zero is returned if this selection produces a directory which contains a Coordinate System Dictionary File. Otherwise -1 is returned.

Notice, that using the return status as a guide, several attempts at locating the CS-MAP data directory can be made in any application.

The name of the directory which is searched for all data files is maintained in a global character array cs_Dir, which is defined in the CSdata module. The cs_Dir array must, initially, contain a null terminated string, the last non-null character of which must be the directory separator character. The global character pointer cs_DirP (also defined in CSdata) is expected to point to the terminating null character of the string in cs_Dir. Under this scheme, Coordinate System Mapping Package data files are accessed as follows:

extern char cs_Dir [];
extern char *cs_DirP;
:
strcpy (cs_DirP,"file_name");
fd = open (cs_Dir,O_MODE);
:

Achieving this particular setup is relatively easy using CS_stcpy:

cs_DirP = CS_stcpy (cs_Dir,"C:\\MAPPING\\");

BUGS

The purpose of this function is to insulate the library from system implementation issues. Without a function of this nature, all applications using CS-MAP would have to implement a specific directory on a specific drive. Not very pleasant. There does not appear to be a nice clean solution to this problem.

CS_atof Ascii to floating point

Function CS_atof (ByRef result As Double,ByVal value As String) As Long
function CS_atof (var result :double;value: PChar) :LongInt;
long CS_atof (double *result,Const char *value);

CS_atof will convert the ASCII, null terminated string provided by the value argument to double precision floating point form, returning this result in the location pointed to by the result argument. Obviously, the string provided by value is expected to be an ASCII representation of a numeric value.

CS_atof has several features built into it for handling numeric formats that are commonly used in mapping, specifically, large numbers, and values in degrees, minutes, and seconds format. Use of thousands separators is supported and, when present, their improper use is reported. Other than leading white space, spaces in the input value are interpreted to indicate degrees, minutes, and seconds format. Values can be entered using minutes only (a single space) or minutes and seconds (two spaces encountered). Use of either directional characters (i.e. N, S, E, W) or plus and hyphen characters for sign is also supported. CS_atof returns a long that carries a complete specification of the format used to enter the value, suitable for use by CS_ftoa for formatting the value for output. CS_atof will also correctly process scale factors entered as ratios, and this feature can be mixed with the thousands separator feature. Thus, scale reduction for state plane coordinate systems can be entered as "1:17,000."

The return value is a bitmap of information used to contain precision, formatting specifications, and error status values. The following descriptions refer to constants defined in the various header files. Construct a format specification by inclusively or'ing the desired options:

Constant	Description
`cs_ATOF_PRCMSK`	The least significant five bits are used to indicate the number of digits found after the decimal point. The value is actually the number of digits plus one. (Zero is reserved to indicate automatic precision determination on output.) This constant is a mask that will mask out the precision value.
`cs_ATOF_VALLNG`	The value processed is acceptable for a longitude value.
`cs_ATOF_VALLAT`	The value processed is acceptable for a latitude value.
`cs_ATOF_MINSEC`	The value processed was in degrees, minutes, and seconds form.
`cs_ATOF_MINUTE`	The value processed was in degrees and minutes form.
`cs_ATOF_EXPNT`	The value processed was in scientific notation form.
`cs_ATOF_COMMA`	The value processed included thousands separators to the left of the decimal point.
`cs_ATOF_DIRCHR`	The value processed included directional characters to indicate sign.
`cs_ATOF_XEAST`	The directional characters used to indicate the sign came from the E and W set, as opposed to the N and S set.
`cs_ATOF_MINSEC0`	The value processed included leading zeros in the minutes or seconds fields.
`cs_ATOF_DEG0`	The value processed included leading zeros in the degrees field.
`cs_ATOF_0BLNK`	The value processed was the null string.
`cs_ATOF_FORCE3`	The value processed used minutes or minutes and seconds format, and 3 digits of degrees were encountered; implying a longitude value.
`cs_ATOF_RATIO`	The processed value was provided in the form of a ratio, e.g. 1:2500, to indicate a value such as, for example, 0.9996.

Bits defined by the following constants are set to indicate the associated error condition. The cs_ATOF_FMTERR bit is set if any error condition is detected and forces the return value to negative. In all such cases, CS_atof will report the error condition and a subsequent call to CS_errmsg will return an appropriate error message.

Constant	Description
`cs_ATOF_SECS60`	What was interpreted to be the seconds field of the processed value produced a value greater than or equal to 60.
`cs_ATOF_MINS60`	What was interpreted to be the minutes field of the processed value produced a value greater than or equal to 60.
`cs_ATOF_MLTPNT`	More than one decimal point was encountered in the input value.
`cs_ATOF_MLTSGN`	More than one sign indication was encountered in the input value.
`cs_ATOF_ERRCMA`	Improper positioning of the thousands separator character was detected in the input value.
`cs_ATOF_RATERR`	A string that contained the ratio character, usually ':', did not conform to the normal convention for a ratio. Usually, the character immediately left of the colon was not a '1'.
`cs_ATOF_FMTERR`	A general format error, not covered by the above, was encountered in the input value.
`cs_ATOF_ERRFLG`	This bit is set, producing a negative return value, if any of the above error conditions are encountered during processing. Whenever this bit is set, the error condition will have been reported to `CS_erpt`, and a subsequent call to `CS_errmsg` will produce an appropriate error message.

CS_azddll LatLong Azimuth Distance calculator

Function CS_azddll ( ByVal e_rad As Double, ByVal e_sq As Double, ByRef ll_fromAs Double,
                      ByVal azimuth As Double,
                      ByVal distance As Double,
                      ByRef ll_to As Double) As Integer
function CS_azddl (e_rad, e_sq: Double; var ll_from: Double; azimuth, distance : Double; var ll_to: Double): Integer;
int CS_azddl (double e_rad, double e_sq, double ll_from[3], double azimuth, double dist, double ll_to[3]);

CS_azddll calculates the latitude and longitude of a target point given an initial point, an azimuth from the initial point, and a distance. The initial point and the result are in degrees, where the longitude occupies the first element in the array and latitude the second element. The reference of the longitude is immaterial, as both (the initial point and the calculated point) will share the same reference whatever it is. Currently, the third element in each array is unused (i.e. un-referenced and unmodified). This may change in future releases. e_rad is the equatorial radius, and e_sq the eccentricity squared, of the ellipsoid to be used. The units of the radius are immaterial other than they must be the same as that used to specify the distance. Azimuth is the azimuth at the initial point given in degrees east of north. distance is the distance traveled in the same units as used to specify the equatorial radius of the ellipsoid. The result is returned in the array pointed to by the ll_to argument.

CS_azddll returns a zero to indicate success, -1 for failure. Failure of the internal Newton Rhapson iterative calculation is the only possible cause of failure. This can be caused by rather strange input values, specifically values that would produce results that are antipodal to the initial point.

The algorithm used is known as: "Solution of the geodetic inverse problem after T. Vincenty modified Rainsford's Method with Helmert's elliptical terms," whatever all that means. This algorithm is appropriate for any combination of points that are not antipodal.

CS_azsphr Azimuth on a Sphere

Function CS_azsphr (ByRef ll_1 As Double, ByRef ll_2 As Double) As Double
function CS_azsphr (var ll_1, ll_2 :Double) : Double;
double CS_azshpr (Const double ll0 [2],Const double ll1 [2]);

CS_azsphrl returns the azimuth, in degrees east of north, from the geographic location given by ll0 to the geographic location given by ll1. The calculation assumes a spherical earth, so a radius and eccentricity is not required.

CS_cnvrg Convergence function

Function CS_cnvrg (ByVal cs_name As String, ByRef ll_ary As Double) As Double
function CS_cnvrg (cs_name :PChar;var ll_ary :double) :Double;
double CS_cnvrg (Const char *cs_name, Const double ll_ary [2]);

CS_cnvrg returns the convergence angle of the coordinate system whose key name is provided by the cs_name argument, at the location provided by the ll_ary argument. The position provided by the ll_ary argument must be in longitude and latitude form, in degrees, where the first element of the array is the longitude and the second element of the array is the latitude. Use negative values for west longitude and south latitude. The returned value is in degrees, east of north.

CS_cnvrg uses the same cache of coordinate system definitions as does CS_cnvrt, therefore, the performance penalty of using this very simple function is not as great as one might expect.

Errors

CS_cnvrg will return a value of -360.0 (clearly a bogus value for a convergence angle) if an error is detected during the calculation. The most common cause of errors is an invalid coordinate system name.

CS_cnvrt generalized convert function

Function CS_cnvrt (ByVal src_cs As String,ByVal trg_cs As String, ByRef coord As Double) As Integer
function CS_cnvrt (src_cs,trg_cs :PChar;var coord :double) :Integer;
int CS_cnvrt (Const char *src_cs,Const char *trg_cs,double coord [3]);

CS_cnvrt is in essence a High Level Interface to the CS_MAP library. Using this single function, one can convert coordinates from any defined system to any other. Simply provide the key name of the source system via the src_cs argument, and the key name of the destination coordinate system via the trg_cs argument, and CS_cnvrt will cause the coordinate in the array given by the coord argument is converted from the source system to the destination system. CS_cnvrt returns zero if the conversion completed successfully without incident. Otherwise, a CS-MAP error code value is returned (see cs_map.h).

CS_cnvrt relies on a cache of coordinate systems, and for each conversion linearly searches the cache for the definitions of the two coordinate system definitions, and the datum conversion definition, it needs to perform its function. Thus, the performance penalty incurred from using this High Level Interface is not as great as one may think.

Currently, the third element of the coord argument is unused; but may be used in the future.

CS_cnvrt3D 3D generalized Convert function


Function CS_cnvrt3D (ByVal src_cs As String, ByVal dst_cs As String, ByRef coor d As Doubl e) As Integer
function CS_cnvrt3D (src_cs,dst_cs :PChar; var coord :Double):Integer
int CS_cnvrt3D (Const char *src_cs, Const char *dst_cs, double coord [3]);

CS_cnvrt3D is in essence a High Level Interface with regard to three dimensional conversions. Using this single function, one can convert three dimensional coordinates from any defined system to any other. Simply provide the key name of the source system via the src_cs argument, and the key name of the destination coordinate system via the dst_cs argument, and CS_cnvrt3D will cause the coordinate in the array given by the coord argument to be converted from the source system to the destination system. CS_cnvrt3D returns a zero if the conversion completed successfully without incident. Otherwise, a CS_MAP error code value is returned.

CS_cnvrt3D relies on a cache of coordinate systems, and for each conversion linearly searches the cache for the definitions of the two coordinate system definitions, and the datum conversion definition, it needs to perform its function. Thus, the performance penalty incurred from using this High Level Interface is not as great as one may think.

Use CS_cnvrt3D only when converting data maintained in a three dimensional database. Note that if the application is able to supply the returned Z value during an inverse calculation, the inverted result may not match the original values.

CS_csEnum Coordinate System Enumerator

Function CS_csEnum ( ByVal index As Integer , ByVal key_name As String, ByVal size As Integer) As Integer
function CS_csEnum(index: Integer; key_name: Pchar; size: Integer):Integer;
int CS_csEnum(int index, char *key_name, int size);

CS_csEnum is used to enumerate all coordinate systems in the Coordinate System Dictionary. CS_csEnum returns in the memory buffer pointer to by the key_name argument the key name of the index'th entry in the Coordinate System Dictionary. CS_csEnum will never write more than size bytes to the indicated location. Index is a zero based index; the index of the first entry in the Coordinate System Dictionary is zero.

CS_csEnum returns a positive 1 to indicate success. If index is too large, a zero is returned.

Errors

CS_csEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary could not be found or otherwise opened. See CS_altdr.
`cs_IOERR`	A physical I/O error occurred in accessing the Coordinate System Dictionary.
`cs_CS_BAD_MAGIC`	The file assumed to be the Coordinate System Dictionary by virtue of its name was not a Coordinate System Dictionary; it had an invalid magic number or was of an incompatible release level.
`cs_INV_INDX`	The index argument was negative.

CS_csIsValid Coordinate System key name Is Valid

Function CS_csIsValid (ByVal key_name As String) As Integer
function CS_csIsValid (key_name: PChar) :Integer;
int CS_csIsValid (Const char *key_name);

CS_csIsValid is used to validate coordinate system key names. CS_csIsValid returns a positive 1 if key_name is a valid coordinate system key name, a zero if not.

Errors

CS_csEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary could not be found or otherwise opened. (See `CS_altdr`.)
`cs_IOERR`	A physical I/O error occurred in accessing the Coordinate System Dictionary.
`cs_CS_BAD_MAGIC`	The file assumed to be the Coordinate System Dictionary by virtue of its name was not a Coordinate System Dictionary; it had an invalid magic number. This can also be caused by an incompatible release.

CS_csRangeEnum Coordinate System Useful Range Enumerator

Function CS_csRangeEnum (ByVal index As Integer, ByVal csKeyName As String,
ByVal size As Integer) As Integer
function CS_csRangeEnum(index: Integer; csKeyName: Pchar; size: Integer):Integer;
int CS_csRangeEnum (int index, char * csKeyName, int size);

CS_csRangeEnum is used to enumerate all coordinate systems which were located by the last call to the CS_csRangeEnumSetup function. Using these two functions, it is possible to obtain a list of only those coordinate systems whose useful range include a specific point. CS_csRangeEnum returns in the memory buffer pointer to by the key_name argument the key name of the index'th entry in the list generated by CS_csRangeEnumSetup. CS_csRangeEnum will never write more than size bytes to the indicated location. Index is a zero based index; the index of the first entry in the Coordinate System Dictionary is zero.

CS_csEnum returns a positive 1 to indicate success. If index is too large, a zero is returned. A negative value is returned for a serious error, such as failure to call CS_csRangeEnumSetup prior to calling this function.

CS_csRangeEnumSetup Coordinate System Range Enumeration Setup

Function CS_csRangeEnumSetup (ByVal longitude As Double, ByVal latitude As Double) As Integer
function CS_csRangeEnumSetup (longitude, latitutde :Double) : Integer
int CS_csRangeEnumSetup (double longitude, double latitude);

Use this function to set the base location for subsequent CS_csEnumRange usage. That is, use this function to produce (internally) a list of all coordinate systems whose useful range includes the given location. Essentially, this function will generate the list, and the application programmer then uses the CS_csEnumRange function to enumerate the list.

The location is specified in geographical terms (i.e. latitude and longitude). These values must be in degrees, relative to Greenwich. Since datum differences are on the order of, at most, a few hundred meters, the datum upon which these coordinates are based is immaterial for the purpose of this function.

CS_csRangeEnumSetup will return a negative value in the event of a serious error, such as being unable to access the Coordinate System Dictionary. Use CS_errmsg to get a textual description of the error which can be reported to the application user. Otherwise, CS_csRangeEnumSetup will return the number of coordinate systems located, which can be zero.

Finally, note that the CS_recvr function will recover all allocated resources, including the list of coordinate systems generated by the last call to this function.

CS_dtEnum Datum Enumerator

Function CS_dtEnum(ByVal index As Integer, ByVal key_name As String, ByVal size As Integer) As Integer
function CS_dtEnum(index: Integer; key_name: Pchar; size: Integer) :Integer;
int CS_dtEnum(int index, char *key_name, int size);

CS_dtEnum is used to enumerate all datums in the Datum Dictionary. CS_dtEnum returns in the memory buffer pointer to by the key_name argument the key name of the index'th entry in the Datum Dictionary. CS_dtEnum will never write more than size bytes to the indicated location. Index is a zero based index; the index of the first entry in the Datum Dictionary is zero.

CS_dtEnum returns a positive 1 to indicate success. If index is too large, a zero is returned.

ERRORS

CS_dtEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_DTDICT`	The Datum Dictionary could not be found or otherwise opened. (See `CS_altdr`.)
`cs_IOERR`	A physical I/O error occurred in accessing the Datum Dictionary.
`cs_DT_BAD_MAGIC`	The file assumed to be the Datum Dictionary by virtue of its name was not a Datum Dictionary; it had an invalid magic number. This can also be caused by a dictionary file of an incompatible release.
`cs_INV_INDX`	The index argument was negative.

CS_dtIsValid Datum key name is valid

Function CS_dtIsValid (ByVal key_name As String) As Integer
function CS_dtIsValid (key_name: PChar): Integer;
int CS_dtIsValid (Const char *key_name);

CS_dtIsValid is used to validate datum key names. CS_dtIsValid returns a positive 1 if key_name is a valid datum key name, a zero if not.

ERRORS

CS_dtIsValid will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_DTDICT`	The Datum Dictionary could not be found or otherwise opened. (See `CS_altdr`.)
`cs_IOERR`	A physical I/O error occurred in accessing the Datum Dictionary.
`cs_DT_BAD_MAGIC`	The file assumed to be the Datum Dictionary by virtue of its name was not a Datum Dictionary; it had an invalid magic number. This can also be caused by a dictionary file of an incompatible release.

CS_elEnum Ellipsoid Enumerator

Function CS_elEnum(ByVal index As Integer, ByVal key_name As String, ByVal size As Integer) As Integer
function CS_elEnum(index: Integer; key_name: Pchar; size: Integer): Integer;
int CS_elEnum(int index, char *key_name, int size);

CS_elEnum is used to enumerate all ellipsoids in the Ellipsoid Dictionary. CS_elEnum returns in the memory buffer pointer to by the key_name argument the key name of the index'th entry in the Ellipsoid Dictionary. CS_elEnum will never write more than size bytes to the indicated location. Index is a zero based index; the index of the first entry in the Ellipsoid Dictionary is zero.

CS_elEnum returns a positive 1 to indicate success. If index is too large, a zero is returned.

ERRORS

CS_elEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary could not be found or otherwise opened. (See `CS_altdr`.)
`cs_IOERR`	A physical I/O error occurred in accessing the Ellipsoid Dictionary.
`cs_DT_BAD_MAGIC`	The file assumed to be the Ellipsoid Dictionary by virtue of its name was not an Ellipsoid Dictionary; it had an invalid magic number. Note that dictionary magic numbers can be different for different releases.
`cs_INV_INDX`	The index argument was negative.

CS_elIsValid Ellipsoid key name is valid

Function CS_elIsValid (ByVal key_name As String) As Integer
function CS_elIsValid (key_name: PChar): Integer;
int CS_elIsValid (Const char *key_name);

CS_elIsValid is used to validate ellipsoid key names. CS_elIsValid returns a positive 1 if key_name is a valid ellipsoid key name, a zero if not.

Errors

CS_elIsValid will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary could not be found or otherwise opened. (See `CS_altdr`.)
`cs_IOERR`	A physical I/O error occurred in accessing the Ellipsoid Dictionary.
`cs_EL_BAD_MAGIC`	The file assumed to be the Ellipsoid Dictionary by virtue of its name was not a Ellipsoid Dictionary; it had an invalid magic number. Note that magic numbers can be different for different releases.

CS_errmsg Error Message

Sub CS_errmsg (ByVal my_bufr As String, ByVal bufr_size As Integer)
procedure CS_errmsg (msg_bufr: PChar; bufr_size: Integer);
void CS_errmsg (char msg_bufr, int bufr_size);

CS_errmsg returns to the calling function a null terminated string which describes the last error condition detected by the CS_MAP library. The result is returned in the buffer pointed to by the msg_bufr argument, which is assumed to be bufr_size bytes long. The message is returned in one character per byte ANSI code characters.

CS_errmsg will return the null string if called before any error condition is detected.

BUGS

After returning an error message to the user, CS_errmsg should reset itself to the null string preventing the same error message from being returned a second time. It should, but it doesn't.

CS_erpt Error Report

extern int cs_Error,cs_Errno;
void CS_erpt (int err_num);

CS_erpt is called by all functions in the Coordinate System Mapping Package whenever an error condition is detected. The value of err_num indicates the specific error condition detected and must be one of the manifest constants defined in cs_map.h.

At the current time, CS_erpt does nothing other than set the value of global variable cs_Error to the supplied value of err_num and set the global variable of cs_Errno to the current value of the system's global variable errno.

It is expected that users will want to write their own CS_erpt function that will properly inform the operator of the nature of the problem encountered.

Each function in the Coordinate System Mapping Package is programmed to clean up after itself after return from CS_erpt. That is, upon return from CS_erpt, all memory malloc'ed by the function detecting the error is free'ed and any temporary file created by the function detecting the error is removed.

CS_fast FAST mode

Sub CS_fast(ByVal fast As Integer)
procedure CS_fast(fast: Integer);
void CS_fast(int fast);

CS_fast can be used to improve the performance of applications using the High Level Interface. When incorporated into a DLL, the High Level Interface normally verifies the veracity of each pointer argument provided by the application. This is convenient, of course, but also somewhat time consuming. Calling CS_fast with a non-zero value for the fast argument will disable this checking. It is recommended that calling CS_fast be added to your application only after it has been debugged. Fast mode can be turned off by calling CS_fast with argument fast set to zero.

CS_ftoa floating point TO Ascii

Function CS_ftoa(ByVal buffer As String, ByVal size As Integer, ByVal value As Double, ByVal format As Long) As Long
function CS_ftoa buffer: Pchar; size: Integer; value: Double; format: Longint) :Longint;
long CS_ftoa(char *buffer, int size, double value, long format);

CS_ftoa formats the double precision floating point value provided by the value argument into ASCII form returning the result in the character array pointed to by the buffer argument. The result is always a null terminated string, and the length of the string is never longer than size - 1 characters. The format of the character string is controlled by the format argument. CS_ftoa returns a long that indicates the actual format used to format the value. The returned format specification may be different from the requested format if the buffer provided was not large enough, or if the requested format is not appropriate for the value provided.

CS_ftoa is intended to be a generalized formatting function that accommodates the formats commonly used in mapping. That is, large numbers and values in degrees minutes and seconds form. The somewhat awkward format argument is designed such that the value returned by CS_atof is suitable for use by CS_ftoa.

The original intent behind the design of the format specification was to enable users to indicate the desired format of output by simply entering a suitable value in the form they desire. The application would then use CS_atof to convert the value to binary form. If no errors occurred during the conversion, the returned long could then be used to format output. Experience will determine the success of this approach.

The format argument is a bitmap of information used to contain precision, formatting specifications, and error status values. The following descriptions refer to constants defined in the various header files. Construct a format specification by inclusively or'ing the desired options.

Constant	Description
`cs_ATOF_PRCMSK`	The least significant five bits are used to indicate the number of digits to be produced after the decimal point. The value is actually the number of desired digits plus one. Zero indicates that the precision is to be calculated automatically. This constant is a mask that will mask out the precision value.
`cs_ATOF_MINSEC`	Output is to be in degrees, minutes, and seconds form.
`cs_ATOF_MINUTE`	Output is to be in degrees and minutes form.
`cs_ATOF_EXPNT`	This bit is set in the returned value if `CS_ftoa` had to resort to scientific notation in order to format the value in the space provided.
`cs_ATOF_OVRFLW`	This bit is set in the returned value if `CS_ftoa` could only output the overflow indication (i.e. .) in the space provided.
`cs_ATOF_COMMA`	Output is to include thousands separators to the left of the decimal point as appropriate.
`cs_ATOF_DIRCHR`	Output is to include directional characters to indicate the sign of the numbers rather than plus or minus signs.
`cs_ATOF_XEAST`	Meaningful only when the `cs_ATOF_DIRCHR` bit is set. Indicates that character set used to indicate positive or negative are E and W as opposed to N and S.
`cs_ATOF_MINSEC0`	Output is to include leading zeros in the minutes and seconds fields instead of leading spaces.
`cs_ATOF_DEG0`	Output is to include leading zeros in the degrees field rather than spaces.
`cs_ATOF_0BLNK`	Output a null string if the provided value is zero.
`cs_ATOF_FORCE3`	Used to force at least three character output in the degree field. Usually used when formatting a longitude.
`cs_ATOF_RATIO`	Output the result in a ratio format, e.g. 1:2500. Can be used in conjunction with `cs_ATOF_COMMA` to get something like 1:2,500.

CS_geoctrSetUp Geocentric setup

Function CS_geoctrSetUp (ByVal ellipsoid As String) As Integer
function CS_geoctrSetUp (ellipsoid: PChar): Integer;
int CS_geoctrSetUp (const char *ellipsoid);

Use this function to specify the ellipsoid definition that is to be used in geocentric coordinate calculations. The ellipsoid argument must be the key name of an ellipsoid defined in the ellipsoid dictionary. Zero is returned on success, -1 on error. Errors are usually caused by invalid ellipsoid names.

CS_geoctrGetXyz Geocentric get XYZ

Function CS_geoctrGetXyz (ByRef xyz As Double, ByRef llh As Double) As Integer
function CS_geoctrGetXyz (var xyz, llh: Double): Integer;
int CS_geoctrGetXyz (double xyz[3], double llh[3]);

Given the geographic coordinates of a point via the llh argument, CS_geoctrGetXyz returns the corresponding geographic coordinate in the array indicated by the xyz argument. Use the CS_geoctrSetUp to specify the ellipsoid that is to be used in the calculation. Note that the returned geocentric coordinates will be in meters, and the third element of the llh argument is considered to be the ellipsoidal height in meters. CS_geoctrGetXyz returns zero on success and –1 on failure. Failure can be caused by failing to specify an ellipsoid by calling CS_geoctrSetUp, or providing a bogus set of geographic coordinates.

CS_geoctrGetLlh Geocentric get LatLongHgt

Function CS_geoctrGetLlh (ByRef llh As Double, ByRef xyz As Double) As Integer
function CS_geoctrGetLlh (var llh, xyz :Double): Integer;
int CS_geoctrGetLlh (double llh[3], double xyz[3]);

Given the geocentric coordinates of a point via the xyz argument, CS_geoctrGetLlh returns the corresponding geographic coordinate in the array indicated by the llh argument. Use the CS_geoctrSetUp to specify the ellipsoid that is to be used in the calculation. Note that the geocentric coordinates must be in meters, and the height (i.e. the third element of the llh result) is the ellipsoidal height in meters. CS_geoctrGetLlh returns zero on success and –1 on failure. Failure can be caused by failing to specify an ellipsoid by calling CS_geoctrSetUp, or providing a bogus set of geocentric coordinates.

CS_getCountyFips Get County Federal Information Processing Standard code

Function CS_getCountyFips ( ByVal stateFips As Integer , ByVal count yName As String) As Integer
function CS_getDataDirectory (stateFips :Integer; countyName :PChar) : Integer;
int CS_getCountyFips ( int stateFips, Const char * count yName);

This function returns the Federal Information Processing Standard code value assigned to a county indicated by the countyName argument. This is appropriate for the US only. You can obtain the appropriate value for the stateFips argument by using CS_getStateFips. Note, that countyName must be the complete official name of the county without any punctuation. The lookup procedure is NOT case sensitive. The function returns zero if the information provided by the two arguments fails to produce a county code.

CS_getDataDirectory GET DATA DIRECTORY

Function CS_getDataDirectory (ByVal data_dir As String, ByVal dir_sz As Integer) As Integer
function CS_getDataDirectory (data_dir: PChar; dir_sz: Integer): Integer;
int CS_getDataDirectory (char *data_dir, int dir_sz);

CS_getDataDirectory will return in the character array pointed to by the data_dir argument the full path to the directory it is searching for supporting data file. It will always return a null terminated string, but never write more than dir_sz characters to the array. CS_getDataDirectory will return TRUE if the directory returned does indeed contain a Coordinate System Dictionary file (i.e. a file named COORDSYS).

CS_getDatumOf Get Datum of a Coordinate System

Function CS_getDatumOf ( ByVal csKeyName As String, ByVal datumName As String, ByVal size As Integer) As Integer
function CS_getDatumOf (csKeyName, datumName: PChar; size: Integer) : Integer;
int CS_get DatumOf ( Const char * csKeyName, char * datumName, int size);

Use this function to obtain the key name of the datum assigned to the coordinate system whose key name is provided by the csKeyName argument. The datum key name is returned in the string pointed to by the datumName argument. CS_getDatumOf will never write more than size characters to the datumName string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. The string at datumName will be the empty string if the coordinate system referred to is cartographically referenced (i.e. referenced directly to an ellipsoid).

CS_getDescriptionOf Get Description of a Coordinate System

Function CS_getDescriptionOf ( ByVal csKeyName As String, ByVal description As String,
ByVal size As Integer) As Integer
function CS_getDescriptonOf (csKeyName, description :PChar; size :Integer) : Integer;
int CS_getDescriptionOf (Const char *csKeyName, char *description, int size);

Use this function to obtain the description the coordinate system whose key name is provided by the csKeyName argument. The description is returned in the string pointed to by the description argument. CS_get DescriptionOf will never write more than size characters to the datumName string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. Note that description field of a coordinate system definition is limited to 63 characters, and size is typically 64 (to accommodate for the null terminating character used in C).

CS_getEllipsoidOf Get Ellipsoid Of a Coordinate System

Function CS_getEllipsoidOf ( ByVal csKeyName As String, ByVal ellipsoidName As String, ByVal size As Integer) As Integer
function CS_getEllipsoidOf (csKeyName, ellipsoidName: PChar; size :Integer) :Integer;
int CS_getEllipsoidOf (Const char *csKeyName, char *ellipsoidName, int size);

Use this function to obtain the ellipsoid referenced by the coordinate system whose key name is provided by the csKeyName argument. The ellipsoid key name is returned in the string pointed to by the ellipsoidName argument. CS_getEllipsoidOf will never write more than size characters to the ellipsoidName string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. Note that key names are limited to 23 characters, and size is typically 24 (to accommodate for the null terminating character used in

This function usually returns the empty string as most coordinate systems are referenced to a datum rather than an ellipsoid. Use this function only in those cases where the CS_getDatumOf function returns the empty string, indicating a coordinate system which is cartographically referenced.

CS_getReferenceOf Get Reference Of a Coordinate System

Function CS_getReferenceOf ( ByVal csKeyName As String, ByVal reference As String, ByVal size As Integer) As Integer
function CS_getReferenceOf ( csKeyName, reference : PChar; size :Integer) :Integer;
int CS_getReferenceOf (Const char *csKeyName, char *reference, int size);

Use this function to obtain an ASCII representation of what the coordinate system referenced by the csKeyName argument is referenced to. This operates correctly for both geodetic and cartographic references. The returned ASCII string will include an indication of the type of reference, and also the keyname involved. The reference description is returned in the string pointed to by the reference argument. CS_getRefernceOf will never write more than size characters to the reference string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. 32 is a customary value for the size argument. A geodetic reference looks something like: Datum: WGS84.

CS_getSourceOf Get Source Of Coordinate System

Function CS_getSourceOf ( ByVal csKeyName As String, ByVal source As String, ByVal size As Integer) As Integer
function CS_getSourceOf (csKeyName, source: PChar; size: Integer): Integer;
int CS_getSourceOf (Const char *csKeyName,char *source,int size);

Use this function to obtain the source of information field of the coordinate system definition whose key name is provided by the csKeyName argument. The source information is returned in the string pointed to by the source argument. CS_getSourceOf will never write more than size characters to the source string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. Note that source of information field of a coordinate system definition is limited to 63 characters, and size is typically 64 (to accommodate for the null terminating character used in C).

CS_getUnitsOf Get Units of a Coordinate System

Function CS_getUnitsOf (ByVal csKeyName As String,ByVal units As String, ByVal size As Integer) As Integer
function CS_getUnitsOf (csKeyName, units: PChar; size: Integer) :Integer;
int CS_getUnitsOf (Const char *csKeyName, char *units, int size);

Use this function to obtain the key name of the units of the coordinate system definition whose key name is provided by the csKeyName argument. The unit key name is returned in the string pointed to by the units argument. CS_ge UnitsOf will never write more than size characters to the units string. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid coordinate system key name. Note that unit key name field of a coordinate system definition is limited to 23 characters, and size is typically 24 (to accommodate for the null terminating character used in C).

CS_getElValues Get Ellipsoid Values

Function CS_getElValues ( ByVal elKeyName As String, ByRef eRadius As Double, ByRef eSquared As Double) As Integer
function CS_getElVal ues ( elKeyName: PChar ; var eRadius, eSquared : Double) : Integer;
int CS_getElValues ( Const char * el KeyName, double * eRadius, double * eSquared ;

Use this function to obtain the equatorial radius and the eccentricity squared values for the ellipsoid referenced by elKeyName argument. The appropriate values are returned in the double variables pointed to by the eRadius and eSquared arguments.. A zero value is returned for success, and -1 for failure. Failure is almost always caused by providing an invalid ellipsoid key name. Note that the value returned in eRadius is the equatorial radius and is always in meters. The value returned in the eSquared variable is unit less, and will be zero if the ellipsoid definition referenced by the elKeyName argument is actually the definition of a sphere.

CS_getCurvatureAt get curvature at specified latitude

Function CS_getCurvatureAt ( ByVal csKeyName As String, ByVal latitude As Double) As Double
function CS_getCurvatureAt (csKeyName, source: PChar; latitude: double) : Double;
double CS_getCurvatureAt ( Const char * csKeyName, double latitude);

This function uses the ellipsoid underlying the coordinate system definition indicated by the csKeyName argument, and computes the Gaussian curvature at the specified latitude. The key name argument must be that of a coordinate system definition, and the latitude argument is specified in degrees.

The function returns a hard zero in the event of an error, which can be caused by providing an invalid coordinate system key name. The latitude argument is not checked and used as is, since only the sine of the latitude is necessary for the calculation (and all real values have, technically, a sine value).

CS_isgeo is geographic

Function CS_isgeo (ByVal key_nmAs String) As Integer
function CS_isgeo (key_nm: PChar): Integer;
int * CS_isgeo (Const char * key_nm);

CS_isgeo will check the coordinate system definition with the key name indicated by the key_nm argument and return +1 (i.e. TRUE) if the coordinate system does return geographic coordinates. A zero is returned if the named coordinate system is not geographic. CS_isgeo returns a negative value in the event of a hard error. The most frequent cause of a hard error is providing an invalid coordinate system name.

CS_llazdd Lat/Long to Azimuth and Distance calculator


Function CS_llazdd(ByVal e_rad As Double, ByVal e_sq As Double, ByRef ll_from As Double, ByRef ll_to As Double, ByRef dist As Double) As Double
function CS_llazdd(e_rad, e_sq: Double; var ll_from, ll_to: Double; var dist: Double): Double;
double CS_llazdd (double e_rad, double e_sq, Const double ll_from[2], Const double ll_to [2], double *dist);

CS_llazdd returns the ellipsoidal azimuth and distance between two points on the surface of an ellipsoid specified in terms of latitude and longitude. e_rad specifies the equatorial radius and e_sq specifies the square of the eccentricity of the ellipsoid. The returned azimuth is calculated from the location specified by ll_from to that specified by ll_to, and the distance between the two points is returned at the location pointed to by dist. The units of the returned distance are the same as those used to specify the equatorial radius.

Latitude and longitude values are in degrees where the first element in each array is the longitude and the second element is the latitude. West longitude and south latitude are negative.

The algorithm used is known as: "Solution of the geodetic inverse problem after T. Vincenty modified Rainsford's Method with Helmert's elliptical terms."

ERRORS

CS_llazdd makes no checks for possible errors. The algorithm used is appropriate for any combination of points that are not antipodal. That is, the points used must not be exactly opposite each other, i.e. on the endpoints of a straight line that passes through the center of the earth.

CS_llFromMgrs calculate Lat/Long from MGRS

Function CS_mgrsFromLl(ByRef latLng As Double, ByVal mgrs As String) As Integer
function CS_mgrsFromLl(var latLng: Double; mgrs: PChar) :Integer;
double CS_mgrsFromLl (double latLng[2], const char *mgrs);

CS_llFromMgrs returns in the array indicated by the latLng argument the geographic coordinate equivalent of the MGRS (Military Grid Reference System) string provided by the mgrs argument. This function is aware of the poles and the rather strange stuff that happens in the northern Europe.

CS_llFromMgrs returns a zero for success, and –1 for failure. Failure can be caused by failing to call the CS_mgrsSetUp prior to calling CS_llFromMgrs or providing an invalid MGRS string.

CS_mgrsFromLl calculate MGRS from Lat/Long

Function CS_mgrsFromLl(ByVal mgrs As String, ByRef latLng As Double, ByVal precision As Integer) As Integer
function CS_mgrsFromLl(mgrs :PChar; var latLng :Double; precision :Integer) : Integer;
double CS_mgrsFromLl (char *mgrs, double latLng [2], int precision);

CS_mgrsFromLl returns the MGRS (Military Grid Reference System) equivalent of the geographic position provided by the latLng argument in the character array (string) indicated by the mgrs argument. The precision of the result is controlled by the precision argument that must have a value between 1 and 5 (inclusive). The result array is assumed to be at least 16 bytes in length. The latLng argument must adhere to the convention established for internal coordinates. This function is aware of the poles and the rather strange stuff that happens in the northern Europe.

CS_mgrsFromLl returns a zero for success, and –1 for failure. Failure can be caused by failing to call the CS_mgrsSetUp prior to calling CS_mgrsFromLl or providing an invalid geographic coordinate.

CS_mgrsSetUp MGRS setup

Function CS_mgrsSetUp (ByVal ellipsoid As String, ByVal bessel As Integer) As Integer
function CS_mgrsSetUp (ellipsoid: PChar; bessel: Integer): Integer;
double CS_mgrsSetUp (const char* ellipsoid, int bessel);

Use the CS_mgrsSetUp to specify the ellipsoid that is to be used in the MGRS (Military Grid Reference System) calculations. Use the ellipsoid argument to provide the key name of the ellipsoid definition that is to be used. There are two alphabetic code sequences used with MGSR. A zero value for the bessel argument causes the normal code sequence to be used, a value of +1 indicates that the code sequence associated with the Bessel ellipsoid is to be used.

CS_mgrsFromLl returns a zero for success, and –1 for failure. Failure is usually caused by a invalid ellipsoid name.

CS_recvr recover resources

Sub CS_recvr
procedure CS_recvr;
void CS_rcvr (void);

CS_rcvr will release all system resources allocated by use of the single function user interface functions CS_cnvrt, CS_cnvrg, and CS_scale. It essentially frees up the coordinate system cache and the datum conversion cache established by these functions to enhance performance.

CS_scale grid SCALE factor function

Function CS_scale (ByVal cs_name As String, ByRef ll As Double) As Double
function CS_scale (cs_name: PChar; var ll :Double): Double;
double CS_scale (Const char *cs_name, double ll[2]);

CS_scale returns the grid scale factor of the coordinate system whose key name is provided by the cs_name argument, at the location provided by the ll argument. The position provided by the ll argument must be in longitude and latitude form, in degrees, where the first element of the array is the longitude and the second element of the array is the latitude. Use negative values for west longitude and south latitude. The returned value is the grid scale factor.

CS_scale uses the same cache of coordinate system definitions as does CS_cnvrt, therefore, the performance penalty of using this very simple function is not as great as one might expect.

In the case of a conformal projection, the K and H scale factors are the same; there is no ambiguity. For non-conformal projections, however, the K and H functions are not the same. In these cases, this function will return the more interesting of the two factors. For example, for the Equidistant Conic, the K factor is always 1.0, and this function would return the H factor for this projection.

ERRORS

CS_scale will return a negative one (i.e. -1.0) if an error occurs. Providing an invalid coordinate system name is the most common source of error.

C## S_scalh grid scale factor(H) function

Function CS_scalh (ByVal cs_name As String, ByRef ll As Double) As Double
function CS_scalh (cs_name: PChar; var ll: Double) :Double;
double CS_scalh (Const char *cs_name, double ll[2]);

CS_scalh returns the grid scale factor along a meridian of the coordinate system whose key name is provided by the cs_name argument, at the location provided by the ll argument. The position provided by the ll argument must be in longitude and latitude form, in degrees, where the first element of the array is the longitude and the second element of the array is the latitude. Use negative values for west longitude and south latitude. The returned value is the grid scale factor.

CS_scalh uses the same cache of coordinate system definitions as does CS_cnvrt, therefore, the performance penalty of using this very simple function is not as great as one might expect.

ERRORS

CS_scalh will return a negative one (i.e. -1.0) if an error occurs. Providing an invalid coordinate system name is the most common source of error.

CS_scalk grid SCALE factor(K) function

Function CS_scalk (ByVal cs_name As String, ByRef ll As Double) As Double
function CS_scalk (cs_name: PChar; var ll: Double): Double;
double CS_scalk (Const char *cs_name, double ll[2]);

CS_scalk returns the grid scale factor along a parallel of the coordinate system whose key name is provided by the cs_name argument, at the location provided by the ll argument. The position provided by the ll argument must be in longitude and latitude form, in degrees, where the first element of the array is the longitude and the second element of the array is the latitude. Use negative values for west longitude and south latitude. The returned value is the grid scale factor.

CS_scalk uses the same cache of coordinate system definitions as does CS_cnvrt, therefore, the performance penalty of using this very simple function is not as great as one might expect.

ERRORS

CS_scalk will return a negative one (i.e. -1.0) if an error occurs. Providing an invalid coordinate system name is the most common source of error.

CS_setHelpPath SET HELP PATH

Function CS_setHelpPath (ByVal helpPath As String) As Integer
function CS_setHelpPath (helpPath: PChar): Integer;
int CS_setHelpPath (const char *helpPath);

Use the CS_setHelpPath function to set the directory that you desire to have CS-MAP search when seeking the MFC dialog help file. The helpPath argument must point to a null terminated string that carries the full path to the desired directory.

CS_setHelpPath returns +1 (i.e. TRUE) if a properly named file exists in the indicated directory. Zero (i.e. FALSE) is returned if such a file does not exist.

CS_spZoneNbrMap State Plane Zone Number Mapper

Function CS_spzone (ByValue csKeyName As String,ByVal is83 As Integer) As Integer
function CS_spzone (csKeyName: PChar; is83: Integer): Integer
int CS_spzone (char *csKeyName, int is83);

CS_spZoneNbrMap examines the character array provided by the csKeyName argument and if it determines that the array contains a valid state plane zone number specification, the contents of the array is replaced with the appropriate corresponding coordinate system key name. If the is83 parameter is non-zero, the zone number is interpreted as a NAD83 zone number. Otherwise, the zone number is interpreted as a NAD27 zone number.

If the original content of the character array pointed to be the csKeyName argument is not a valid state plane zone number, the contents of the array remains unchanged.

CS_spZoneNbrMap returns 0 if a substitution was made. A positive one is returned if a substitution was not made because the value passed was not considered to be a valid state plane zone number. Minus one is returned if the original passed value is close to a state plane zone number (i.e. consisted of three or four digits), but did not match a valid state plane zone number.

CS_unEnum Units Enumerator

Function CS_unEnum(ByVal ByVal ByVal index As Integer,ByVal type As Integer, key_name As String, name_sz As Integer) As Integer
function CS_unEnum(index, type: Integer; key_name: Pchar; name_sz: Integer): Integer;
int CS_unEnum(int index, int type, char *key_name, int nm_size);

CS_unEnum is used to enumerate all units of a specific type in the CS-MAP units table. CS_unEnum returns in the memory buffer pointer to by the key_name argument the name of the index'th entry in the unit table of the type specified by the type argument. CS_unEnum will never write more than nm_size bytes to the indicated location. Index is a zero based index; the index of the first entry in the unit table is zero.

Currently, only two types of units supported, length and angular measure. Manifest constants defined in the cs_map.h header file are used to distinguish the desired type. These are cs_UTYP_LEN, for linear units, and cs_UTYP_ANG, for angular units. The type argument must be one of these values.

CS_unEnum returns a positive 1 to indicate success. If index is too large, a zero is returned.

Errors

CS_unEnum will return a -1 and set csError appropriately if any of the following conditions are encountered:

Constant	Description
`cs_INV_INDX`	The index argument was negative.

BUGS

If called with an invalid type, CS_unEnum should probably return an error condition, but it doesn't. Calling CS_unEnum with an invalid type causes a return value of zero for all positive values of the index argument.

CS_unitlu unit look up

Function CS_unitlu (ByVal type As Integer, ByVal unit_nmAs String) As Double
function CS_unitlu (type: Integer; unit_nm: PChar): Double;
double CS_unitlu (short type, Const char *unit_nm);

Given the type of measurement, either length or angular, as specified by the type argument and the unit name as specified by the unit_nm argument, CS_unitlu will return a double which represents the multiplier required to convert a value in the unit system indicated by unit_nm to units of meters or degrees.

Currently, only two types of units supported, length and angular measure. Manifest constants defined in the cs_map.h header file are used to distinguish the desired type. These are cs_UTYP_LEN and cs_UTYP_ANG. The type argument must be one of these values.

unit_nm must be a null terminated string matching one of the supported units as defined in CSdataU. CS_unitlu returns zero in the event the provided unit name is not known. unit_nm may be one of the supported abbreviations for any of the units defined in the unit table.

For example, to convert a value in feet to meters, one could code:

double CS_unitlu(); {
  meters = feet * CS_unitlu(cs_UTYP_LEN, "FOOT");
}

Or to convert degrees to grads:

double CS_unitlu (); {
  grads = degrees / CS_unitlu (cs_UTYP_ANG, "GRAD");
}

CS_unitlu knows about the first and second abbreviations provided for in the cs_Unittab_ structure. Therefore, the following are equivalent to the above:

double CS_unitlu(); {
  meters = feet * CS_unitlu (cs_UTYP_LEN,"FT");
}

double CS_unitlu(); {
  grads = degrees / CS_unitlu (cs_UTYP_ANG,"GR");
}

ERRORS

CS_unitlu will return zero and set cs_Error to cs_INV_UNIT if the unit name pointed to by unit_nm is not defined in cs_Unittab for the specified type, or the specified type is not valid.

High Performance Interface

Functions which are considered part of the High Performance Interface are described in this section. Several of these functions return addresses (i.e. pointers to) malloc'ed memory, and therefore these functions are not suitable for all languages. Function prototype definitions are given in the C syntax only.

CS_audflt Angular unit default

char *CS_audlt (Const char *new_dflt);

Use CS_audflt to control the status of the "defaultable" angular unit reference feature of CS-MAP. new_dflt must be either a pointer to a valid angular unit name, a pointer to the null string, or the NULL pointer. In the case where new_dflt is a pointer to a valid angular unit name, CS_audflt causes the default angular unit feature to be activated, using the angular unit name provided as the, possibly new, default value. When new_dflt is a pointer to the null string, CS_audflt disables the default angular unit feature. When new_dflt is the NULL pointer, the status of the angular unit default feature remains unchanged.

In all cases, CS_audflt returns the previous status (or in the case of new_dflt == NULL, the current status) in the form of a pointer to a static character array that contains the name of the previous default angular unit. Should the returned pointer point to a null string, the indicated previous status is disabled.

ERRORS

CS_audflt will return the NULL pointer if the key name provided is not that of a valid angular unit. In this event, the current status of the default angular unit feature remains unchanged.

CS_cs2ll Coordinate System to Latitude/Longitude

void CS_cs2ll(Const struct cs_Csprm_ *csprm,double ll[2], Const double xy[2]);

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_cs2ll will convert the coordinates xy to latitude and longitude, returning the results in ll. The ll and xy arguments may point to the same array.

In the array arguments, the X coordinate and the longitude occupy the first element, the Y coordinate and the latitude the second element. West longitudes and south latitudes are negative. The returned values are in degrees.

CS_cscnv Coordinate System Convergence

double CS_cscnv(Const struct cs_Csprm_ *csprm, Const double ll[2]);

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_cscnv will return the convergence angle in degrees east of north at the location given by ll.

The location, as given by ll is in terms of latitude and longitude. The longitude is the first element of the ll array, latitude is the second, and both must be given in degrees. Positive values are used to specify north latitude and east longitude, negative values are used to specify south latitude and west longitude.

CS_csdef Coordinate System definition locator

struct cs_Csdef_ * CS_csdef (Const char* key_nm);

CS_csdef will return a pointer to a malloc'ed cs_Csdef_ structure that contains the definition of the coordinate system indicated by key_nm. Key_nm must point to an array that contains the null terminated key name of the desired coordinate system. The memory allocated for the coordinate system definition may be released by calling CS_free when no longer needed.

ERRORS

CS_csdef will return a NULL pointer and set cs_Error if any of the following conditions are detected:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary file could not be found or otherwise opened. (See `CS_altdr`).
`cs_IOERR`	A physical I/O error occurred during access to the Coordinate System Dictionary file.
`cs_CS_BAD_MAGIC`	The file accessed under the assumption that it was a Coordinate System Dictionary wasn't a Coordinate System Dictionary after all; it had an invalid magic number on the front end.
`cs_CS_NOT_FND`	A coordinate system definition with the name given by key_nm was not found in the Coordinate System Dictionary.
`cs_NO_MEM`	Insufficient dynamic memory was available to allocate space for the `cs_Csdef_` structure.

CS_csdel Coordinate System definition delete

int CS_csdel(struct cs_Csdef_ *csdef);

CS_csdel will delete from the Coordinate System Dictionary the definition of the coordinate system pointed to by csdef.

The delete is accomplished by creating a new Coordinate System Dictionary file and copying all but the referenced coordinate system definitions from the existing dictionary to the new one. This implies that sufficient disk space must exist to perform the copy. A zero is returned if the delete was successfully completed, a -1 if a problem occurred. An attempt to delete a non-existent coordinate system definition is NOT considered an error.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_csdel will not delete a coordinate system which is marked as being a distribution coordinate system (i.e. cs_Csdef_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined coordinate system is protected. For example, is cs_Protect is 60, a user-defined coordinate system becomes protected 60 days after it is last modified.

ERRORS

CS_csdel will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred in copying the Coordinate System Dictionary to the new file.
`cs_CS_BAD_MAGIC`	The file assumed to be the Coordinate System Dictionary by virtue of its name was not a Coordinate System Dictionary; it had an invalid magic number.
`cs_TMP_CRT`	The attempt to create a new file, to which the modified Coordinate System Dictionary was to be copied, failed.
`cs_DISK_FULL`	Insufficient disk space was available to accommodate the copying of the Coordinate System Dictionary to the new file.
`cs_UNLINK`	The request to remove the old copy of the Coordinate System Dictionary failed.
`cs_RENAME`	The request to rename the new Coordinate System Dictionary file from its temporary name to COORDSYS failed.
`cs_CS_PROT`	The coordinate system to be deleted is a distribution coordinate system and may not be deleted.
`cs_CS_UPROT`	The coordinate system is a user defined coordinate system that has not been modified for 60 days and is therefore protected.

CS_csEnumByGroup Coordinate System Enumerator By Group

int CS_csEnumByGroup (int index, Const char * grp_name, struct cs_Csgrplst_ * cs_descr);

CS_csEnumByGroup is used to enumerate a specific group of coordinate systems in the Coordinate System Dictionary. CS_csEnumByGroup returns a completed cs_Csgrplst_ structure at the location given by the cs_descr argument containing information that describes the index'th entry in the coordinate system group named by the grp_name argument. Index is a zero based index; the index of the first coordinate system in any group is zero. The next element of the returned cs_Csgrplst_ structure is always set to the NULL pointer.

CS_csEnumByGroup returns a positive 1 to indicate success. If index is too large, a zero is returned.

ERRORS

CS_csEnumByGroup will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred in accessing the Coordinate System Dictionary.
`cs_CS_BAD_MAGIC`	The file assumed to be the Coordinate System Dictionary by virtue of its name was not a Coordinate System Dictionary; it had an invalid magic number.
`cs_CSGRP_INVKEY`	The grp_name argument was not that of a valid group name.
`cs_INV_INDX`	The index argument was negative.

CS_csGrpEnum Coordinate System grour enumerator

int CS_csGrpEnum(int index, char *grp_name, int name_sz, char *grp_dscr, int dscr_sz);

CS_csGrpEnum is used to enumerate all groups in the Coordinate System Group table. CS_csGrpEnum returns in the memory buffer pointer to by the grp_name argument the key name of the index'th entry in the Coordinate System Group Table. CS_csGrpEnum will never write more than name_sz bytes to the indicated location. Similarly, CS_csGrpEnum returns the Coordinate System Group description in the buffer pointed to be grp_dscr and whose size in indicated by dscr_sz. The grp_name and/or the grp_dscr arguments may be the NULL pointer to suppress return of the indicated item.

Index is a zero based index; the index of the first entry in the Coordinate System Group Table is zero. CS_dtEnum returns a positive 1 to indicate success. If index is too large, a zero is returned. Inactive groups (a feature planned for a future release) are ignored, and are not considered to exist as far as index is concerned.

ERRORS

CS_csGrpEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_INV_INDX`	The index argument was negative.

CS_csloc Coordinate System locate and initialize

struct cs_Csprm_ *CS_csloc(Const char *cs_nam);
struct cs_Csprm_ *Cscsloc1(Const struct cs_Csdef_ *cs_ptr);
struct cs_Csprm_ *Cscsloc2(Const struct cs_Csdef_ *csPtr,
                          Const struct cs_Dtdef_ *dtPtr,
                          Const struct cs_Eldef_ *elPtr);
struct cs_Csprm_ *Cscsloc(Const struct cs_Csdef_ *csPtr,
                          Const struct cs_Dtdef_ *dtPtr);

CS_csloc locates the coordinate system definition indicated by cs_nam and returns a pointer to a malloc'ed, coordinate system parameter structure initialized for the specified coordinate system. The return value is the argument required by CS_cs2ll, CS_ll2cs, CS_csscl, and CS_cscnv. When no longer needed, the memory pointed to by the returned pointer should be released using CS_free.

CS_csloc accesses the definition dictionaries as is necessary to accomplish its task. The alternative functions enable applications to create coordinate system parameter structures using definitions that may have been obtained from sources other than the dictionaries. For example, certain applications may store definitions in vehicles other than the dictionaries, and then desire to construct a coordinate system parameter structure from these definitions.

Note that Cscsloc1 does not need to access the coordinate system dictionary as the coordinate system definition is provided by the cs_ptr argument. However, it will need to access the datum and ellipsoid dictionaries to resolve datum and ellipsoid references. Cscsloc2 is completely independent of all dictionaries as all three definitions must be provided. CScsloc is simply a basic function is encapsulates the basic functions of CS_csloc and its alternatives, and thus prevents duplication of large amounts of code.

ERRORS

CS_csloc, CScsloc1, CScsloc2, and CScsloc return a NULL pointer and set cs_Error through the use of CS_erpt if any of the following conditions occur:

Constant	Description
`cs_UNKWN_PROJ`	The projection specified in the coordinate system definition is unknown to the system.

CS_csloc uses the following functions that detect a majority of the exceptional conditions that may occur:

Constant	Description
`CS_csdef`	Locates and fetches the coordinate system definition from the Coordinate System Dictionary.
`CS_dtloc`	Locates and fetches the datum definition from the Datum Dictionary.
`CS_eldef`	Locates and fetches the ellipsoid definition from the Ellipsoid Dictionary.

CScsloc1 uses the following functions that detect a majority of the exceptional conditions that may occur:

Constant	Description
`CS_dtloc`	Locates and fetches the datum definition from the Datum Dictionary.
`CS_eldef`	Locates and fetches the ellipsoid definition from the Ellipsoid Dictionary.

CS_cssch Coordinate System Scale H, along a meridian

double CS_cssch (Const struct cs_Csprm_ *csprm, Const double ll[2]);

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_cssch will compute the grid scale factor along a meridian at the location given by ll and return this value. See CS_cssck for the grid scale factor along a parallel. Note that in conformal projections, the grid scale along a parallel equals the grid scale along a meridian at any point.

The location, as given by ll, is in terms of latitude and longitude. The longitude is the first element of the ll array, latitude is the second, and both must be given in degrees. Positive values are used to specify north latitude and east longitude, negative values are used to specify south latitude and west longitude.

CS_cssck Coordinate System Scale K, along a parallel

double CS_cssck (Const struct cs_Csprm_ *csprm, Const double ll[2]);

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_cssck will compute the grid scale factor along a parallel at the location given by ll and return this value. See CS_cssch for the grid scale factor along a meridian. Note that in conformal projections, the grid scale along a parallel equals the grid scale along a meridian at any point.

CS_csscl Coordinate System Scale

double CS_csscl (Const struct cs_Csprm_ *csprm, Const double ll[2]);

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_csscl will compute the grid scale factor at the location given by ll and return this value.

Non-conformal projections have two different grid scale factors: the scale along a meridian and the scale along a parallel. In the case of azimuthal projections, the two scale factors are along a radial line from the origin and normal to such radial lines, respectively. In these cases, CS_csscl will return the more interesting of the two. For example, in the American Polyconic, the grid scale factor along all parallels is always 1.0; therefore CS_csscl return the grid scale factor along a meridian for this projection.

CS_csupd Coordinate system dictionary update

int CS_csupd (struct cs_Csdef_ *csdef, int crypt);

CS_csupd will cause coordinate system definition pointed to by csdef to be added to the Coordinate System Dictionary. If a coordinate system with the same key name already exists, it is replaced by the definition provided. If no such definition exists, the new definition is added to the dictionary. If crypt is non-zero, the entry will be encrypted before being written to the dictionary.

In the event that the indicated coordinate system already exists, CS_csupd will return a 1 to indicate a successful update. In the event that the provided coordinate system had to be added to the Coordinate System Dictionary, a zero is returned. A -1 is returned if the update failed for any reason.

Please note that the addition of a new coordinate system definition requires the sorting of the Coordinate System Definition file. This may take a few seconds to complete, depending upon the size of the Coordinate System Dictionary.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_csupd will not change a coordinate system which is marked as being a distribution coordinate system (i.e. cs_Csdef_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined coordinate system is protected. For example, if cs_Protect is 60, a user-defined coordinate system becomes protected 60 days after it is last modified.

Additionally, if the value of the global character variable cs_Unique is not the null character, CS_csupd will not add a coordinate system definition if its key name does not contain the character indicated. For example, if cs_Unique is set to the colon character, CS_csupd will not add a coordinate system whose key name does not contain a colon character.

ERRORS

CS_csupd will return a -1 and set cs_Error appropriately if any of the following conditions are encountered during the update:

Constant	Description
`cs_CSDICT`	The Coordinate System Dictionary file could not be opened. (See `CS_altdr`).
`cs_IOERR`	A physical I/O error occurred during the update process.
`cs_CS_BAD_MAGIC`	The file that, by virtue of its name and location, was supposed to be a Coordinate System Dictionary wasn't a Coordinate System Dictionary; its magic number was invalid.
`cs_DISK_FULL`	There was insufficient disk space available to add the coordinate system definition to the dictionary.
`cs_CS_PROT`	The coordinate system to be updated is a distribution coordinate system and may not be updated.
`cs_CS_UPROT`	The coordinate system is a user defined coordinate system that has not been modified for 60 days and is therefore protected.
`cs_UNIQUE`	The coordinate system provided does not already exist and would need to be added; but the key name does not contain the unique character.

CS_dtcls Datum conversion close

void CS_dtcls (struct cs_Dtcprm_ *dtc_ptr);

Initializing a datum conversion can use file descriptors (handles) and allocate memory from the heap. Applications may need to recover these system resources for other use prior to exiting. CS_dtcls will release all system resources allocated to the datum conversion indicated by the dtc_ptr argument (as returned by CS_dtcsu). This function is, essentially, the inverse of CS_dtcsu.

CS_dtcsu Datum conversion set up

struct cs_Dtcprm_ *CS_dtcsu (Const struct cs_Csprm_ *src_cs, Const struct cs_Crprm_ *dest_cs, int dat_err, int blk_err);

CS_dtcsu, CS_dtcvt, and CS_dtcls, are designed to provide a generic application interface for datum conversion. The objective is to enable application programmers to incorporate datum conversion capabilities into applications with a minimum of impact. Therefore, application programmers use CS_dtcsu to set up a datum conversion and CS_dtcvt to perform the actual conversions independently of the number or type of datum conversions that may or may not be supported. CS_dtcls provides a means of recovering any system resources that may be allocated by the activation of a datum conversion.

Application programmers use CS_dtcsu to initiate a datum conversion process. Src_cs points to the coordinate system definition of the source data that is to be converted while dest_cs points to the coordinate system definition for the results. CS_dtcsu examines the datum references in these coordinate systems, initializes the appropriate datum shift conversion, and returns a pointer to a malloc'ed datum conversion parameter block. The returned pointer is a required argument for the CS_dtcvt function.

As is often the case, should the source and destination coordinate systems share the same datum, the null datum conversion is activated. That is, source latitudes and longitudes are copied directly to the destination array without modification.

The dat_err argument is used to indicate the desired disposition of certain errors that are encountered during the setup of the datum conversion. The error disposition control afforded by dat_err applies only to errors indicating that an unsupported datum conversion was requested. System errors, such as physical I/O or insufficient memory for example, are always treated as fatal errors and a NULL pointer is returned.

The following values for dat_err are recognized:

Constant	Description
`cs_DTCFLG_DAT_I`	Ignore unsupported datum conversion request errors and, in the event of such an error, silently activate the null conversion.
`cs_DTCFLG_DAT_W`	In the event of an unsupported datum conversion request error, report the condition as a warning to `CS_erpt` (`cs_DTC_DAT_W`) and activate the null conversion. In this case, the user is notified, but data processing continues.
`cs_DTCFLG_DAT_F`	In the event of any error, report the condition as a fatal error to `CS_erpt` (`cs_DTC_DAT_F`) and return the NULL pointer.

The blk_err argument is used to indicate the desired disposition of certain errors that are encountered during the conversion of individual coordinate values. The error disposition control afforded by blk_err applies only to errors indicating that the required data for the geographic region containing the coordinate to be converted is not available. System errors, such as physical I/O or insufficient memory for example, are always treated as fatal errors.

The following values for blk_err are recognized:

Constant	Description
`cs_DTCFLG_BLK_I`	Ignore datum conversion errors caused by data availability problems and silently use the null conversion for the specific coordinate that could not be converted and cause `CS_dtcvt` to return a zero value.
`cs_DTCFLG_BLK_W`	In the event a datum conversion fails due to data availability, report a warning through `CS_erpt` (`cs_DTC_BLK_W`), convert the coordinate using the null conversion, and cause a `CS_dtcvt` to return a positive non-zero value for the specific coordinate that could not be converted. The warning message is issued for each coordinate that could not be converted.
`cs_DTCFLG_BLK_1`	In the event a datum conversion fails due to data availability, cause `CS_dtcvt` to return a positive non-zero value for the specific coordinate that could not be converted. That such an error has been reported is recorded in the datum parameter block and this is used to suppress repeated reporting of the error with regard to the same block.
`cs_DTCFLG_BLK_F`	Report a fatal condition through `CS_erpt` (`cs_DTC_BLK_F`), convert the coordinate using the null conversion, and cause `CS_dtcvt` to return a negative non-zero value to indicate that the expected conversion did not take place.

Special cases

Three special cases have been coded into this function. Normally, the geographic coodinates of the source datum are converted to WGS84 values, and the resulting WGS84 values are then converted to the target datum.

There are three cases where this genberal technique proved to be unsatisfactory. In these three cases, CS_dtcsu has been expressly coded to look at the source and target datums, and implement direct conversions where appropriate. Note, that in each case, a specific Geodetic Data Catalog file is also involved. Thus, if the required Geodetic Data Catalog file is not present, all of the special processing is disabled.

The following table defines the special cases:

Source Datum	Target Datum	Geodetic Data Catalog	Description
NAD27	ATS77	Nad27ToAts77.gdc	Converts directly from NAD27 to ATS77 using the very special `TRANSFORM` algorithm.
ATS77	CSRS	Ats77ToCsrs.gdc	Converts directly as direct NTv2 format files are generally available.
NAD27	CSRS	Nad27ToCsrs.gdc	Converts directly as direct NTv2 format files are generally available.

ERRORS

Should the requested datum conversion requested be unsupported, CS_dtcsu will perform as indicated by the dat_err argument. Should the initialization of a supported datum conversion fail due to a system error, the NULL pointer will be returned and cs_Error set to indicate the nature of failure. Should a datum conversion for which appropriate code is present fail because a required data file is not present, the failure is treated as an unsupported datum conversion request.

CS_dtcvt Datum Convert

int CS_dtcvt (struct cs_Dtcprm_ *dtc_ptr, Const double src_ll[2], double dest_ll[2]);

CS_dtcvt performs the datum conversion indicated by dtc_ptr returning in the array pointed to by dest_ll the result of converting the latitude and longitude values pointed to by src_ll. Src_ll and dest_ll may point to the same array. Latitude and longitude values must be given in degrees, where negative values indicate south and west. The longitude is carried in the first element of the array and the latitude is carried in the second element. The dtc_ptr argument is that which is returned by CS_dtcsu.

ERRORS

Should a system error occur during the conversion (e.g. a physical I/O error or insufficient memory) CS_dtcvt returns a negative non-zero value and sets cs_Error to indicate the cause of the failure.

Conversion failures caused by a lack of data covering the specific coordinate to be converted are handled as indicated by the blk_err element of the cs_Dtcprm_ structure pointed to by the **tc_ptr** argument. The **blk_err** element is set byCS_dtcsuto the value of its **blk_err** argument prior to returning **dtc_ptr**. Refer toCS_dtcsu` for a detailed description of how such errors are handled.

In all cases, the null conversion is always performed before any other processing is attempted.

EXAMPLE

This function, and its companion CS_dtcsu have been designed such that the following sequence of code is all that is necessary to perform a complete coordinate conversion, including a datum conversion (error handling omitted):

#define XX 0
#define YY 1
struct cs_Csprm * src_cs, * dest_cs;
struct cs_Dtcprm_ *dtc_ptr;
double src_xy [2], ll[2], dest_xy[2];
.
.
src_cs = CS_csloc ( src_name) ;
dest_cs = CS_csloc (dest_name);
dtc_ptr = CS_dtcsu ( src_cs, dest_cs, cs_DTCFLG_DAT_F, cs_DTCDLG_BLK_1) ; .
.
while (TRUE)
{
.
.
src_xy[XX] = ???;
src_xy[YY] = ???;
CS_cs2ll (src_cs,ll,src_xy); CS_dtcvt (dtc_ptr,ll,ll); CS_ll2cs (dest_cs,dest_xy,ll);
??? = dest_xy[XX]; ??? = dest_xy[YY]; .
.
}
CS_free (src_cs); CS_free (dest_cs); CS_dtcls (dtc_ptr);

Notice, that adding the datum conversion to a simple cartographic conversion requires only the insertion of three lines of code (error handling aside) to the simple High Performance Interface described elsewhere in this manual.

CS_dtdef Datum Definition locator

struct cs_Dtdef_ * CS_dtdef ( Const char * key_nm) ;

CS_dtdef will return a pointer to a malloc'ed cs_Dt def_ structure which contains the definition of the datum indicated by key_nm. Key_nm must point to an array that contains the null terminated key name of the desired datum definition. The memory allocated for the datum definition should be released by using CS_free when no longer needed.

ERRORS

CS_dtdef will return a NULL pointer and set cs_Error if any of the following conditions are detected:

Constant	Description
`cs_DTDICT`	The Datum Dictionary file could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred during access to the Datum Dictionary file.
`cs_DT_BAD_MAGIC`	The file accessed under the assumption that it was a Datum Dictionary wasn't a Datum Dictionary after all; it had an invalid magic number on the front end.
`cs_DT_NOT_FND`	A datum definition with the name given by key_nm was not found in the Datum Dictionary.
`cs_NO_MEM`	Insufficient dynamic memory was available to allocate space for the `cs_Dtdef_` structure.

CS_dtdel DaTum definition delete

int CS_dtdel (struct cs_Dtdef_ *dtdef);

CS_dtdel will delete from the Datum Dictionary the definition of the Datum pointed to by dtdef.

The delete is accomplished by creating a new Datum Dictionary file and copying all but the referenced datum definition from the existing dictionary to the new one. This implies that sufficient disk space must be available to perform this copy. A zero is returned if the delete was successfully completed, a - 1 if a problem occurred. An attempt to delete a non-existent datum definition is NOT considered a problem.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_dtdel will not delete a datum definition which is marked as being a distribution datum definition (i.e. cs_Dt def_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined datum is protected. For example, is cs_Protect is 60, a user-defined datum becomes protected 60 days after it is last modified.

ERRORS

CS_dtdel will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_DTDICT`	The Datum Dictionary file could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred in copying the Datum Dictionary to the new file.
`cs_DT_BAD_MAGIC`	The file assumed to be the Datum Dictionary by virtue of its name and location was not a Datum Dictionary; it had an invalid magic number.
`cs_TMP_CRT`	The attempt to create a new file, to that the modified Datum Dictionary was to be copied, failed.
`cs_DISK_FULL`	Insufficient disk space was available to accommodate the copying of the Datum Dictionary to the new file.
`cs_UNLINK`	The request to remove the old copy of the Datum Dictionary failed.
`cs_RENAME`	The request to rename the new Datum Dictionary file from its temporary name to DATUMS failed.
`cs_DT_PROT`	The datum definition to be updated is a distribution datum definition and may not be deleted.
`cs_DT_UPROT`	The datum is a user-defined datum which has not been modified for 60 days and is therefore protected.

CS_dtdflt Datum default

char *CS_dtdflt (Const char *new_dflt);

Use CS_dtdflt to control the status of the "defaultable" datum reference feature of CS-MAP. New_dflt must be either a valid datum key name, a pointer to the null string, or the NULL pointer. In the case where new_dflt is a pointer to a valid datum definition key name, CS_dtdflt causes the default datum feature to be active, using the datum key name provided as the default value. When new_dflt is a pointer to the null string, CS_dtdflt disables the default datum feature. When new_dflt is the NULL pointer, the status of the default feature remains unchanged.

In all cases, CS_dtdflt returns the previous status (or in the case of new_dflt == NULL, the current status) in the form of a pointer to a static character array which shall contain the name of the previous default datum. Should the returned pointer point to a null string, the indicated status is disabled.

ERRORS

CS_dtdflt will return the NULL pointer if the key name provided is not that of a valid datum. In this event, the status of the default datum feature remains unchanged.

CS_dtloc Datum locate

struct cs_Datum_ *CS_dtloc (Const char * key_nm) ;
struct cs_Datum_ *Csdtloc1 (Const struct cs_Dtdef_ *dtPtr);
struct cs_Datum_ *Csdtloc2 (Const struct cs_Dtdef_ *dtPtr, Const struct cs_Eldef_ *elPtr);

CS_dtloc will return a pointer to a malloc'ed cs_Datum_ structure which contains the definition of the datum indicated by key_nm along with the ellipsoid information referenced by the datum definition. Key_nm must point to an array that contains the key name of the desired datum. The memory allocated for the datum definition should be released using CS_free when no longer needed.

CSdtloc1 and CSdtloc2 are alternatives to CS_dtloc that enable alternative sources for datum and ellipsoid definitions. These have been provided for applications that may, for example, store the datum, and/or ellipsoid, definitions in an application database.

Note that while CSdtloc1 will not need to access the Datum Dictionary, it will need to access the Ellipsoid Dictionary to resolve the ellipsoid reference in the datum definition provided. CSdtloc2 is completely independent of both dictionaries.

ERRORS

CS_dtloc, Csdtloc, and CSdtloc2 will return a NULL pointer and set cs_Error if any of the following conditions are detected:

Constant	Description
`cs_NO_MEM`	Insufficient dynamic memory was available to allocate space for the `cs_Datum_` structure.

CS_dtloc uses CS_dtdef and CS_eldef to obtain definition records from the Datum and Ellipsoid Dictionaries. Therefore, all of the error conditions detected by these functions apply to this function as well.

CSdtloc1 uses CS_eldef to obtain definition records from the Ellipsoid Dictionary. Therefore, all of the error conditions detected by this function apply to this function as well.

CS_dtupd Datum dictionary update

int CS_dtupd (struct cs_Dtdef_ *dt_def, int crypt);

CS_dtupd will cause the datum definition pointed to by dt_def to be added to the Datum Dictionary. If a datum with the same key name exists, it is replaced by the definition provided. If no such definition exists, the new definition is added to the dictionary. If crypt is non-zero, the datum entry is encrypted before being written.

In the event that the indicated datum already existed, CS_dtupd will return a 1 to indicate a successful update. In the event that the provided datum definition had to be added to the Datum Dictionary, a zero is returned. A -1 is returned if the update failed for any reason.

Please note that the addition of a new datum definition requires the sorting of the Datum Dictionary file. This may take a few seconds to complete, depending upon the size of the Datum Dictionary.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_dtupd will not change a datum definition which is marked as being a distribution datum definition (i.e. cs_Dtdef_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined datum is protected. For example, is cs_Protect is 60, a user-defined datum becomes protected 60 days after it is last modified.

Additionally, if the value of the global character variable cs_Unique is not the null character, CS_dtupd will not add a datum definition if its key name does not contain the character indicated. For example, if cs_Unique is set to the colon character, CS_dtupd` will not add a datum definition whose key name does not contain a colon character.

ERRORS

CS_dtupd will return a -1 and set cs_Error appropriately if any of the following conditions are encountered during the update:

Constant	Description
`cs_DTDICT`	The Datum Dictionary file could not be opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred during the update process.
`cs_DT_BAD_MAGIC`	The file which, by virtue of its name and location, was assumed to be a Datum Dictionary wasn't a Datum Dictionary; its magic number was invalid.
`Cs_DISK_FULL`	There was insufficient disk space available to add the datum definition to the Datum Dictionary.
`Cs_DT_PROT`	The datum definition to be updated is a distribution datum definition and may not be updated.
`cs_DT_UPROT`	The datum is a user-defined datum that has not been modified for 60 days and is therefore protected.
`cs_UNIQUE`	The datum provided does not already exist and would need to be added; but the key name does not contain the unique character.

CS_eldef Ellipsoid definition locator

struct cs_Eldef_ * CS_eldef ( Const char * key_nm) ;

CS_eldef will return a pointer to a malloc'ed cs_Eldef_ structure which contains the definition of the ellipsoid indicated by key_nm. Key_nm must point to an array that contains the null terminated key name of the desired ellipsoid definition. The memory allocated for the ellipsoid definition should be released using CS_free when no longer needed.

ERRORS

CS_eldef will return a NULL pointer and set cs_Error if any of the following conditions are detected:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary file could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred during access to the Ellipsoid Dictionary file.
`cs_EL_BAD_MAGIC`	The file accessed under the assumption that it was an Ellipsoid Dictionary wasn't an Ellipsoid Dictionary after all; it had an invalid magic number on the front end.
`cs_EL_NOT_FND`	A ellipsoid definition with the name given by key_nm was not found in the Ellipsoid Dictionary.
`cs_NO_MEM`	Insufficient dynamic memory was available to allocate space for the `cs_Eldef_` structure

CS_eldel Ellipsoid definition delete


int CS_eldel (struct cs_Eldef_ *eldef);

CS_eldel will delete from the Ellipsoid Dictionary the definition of the Ellipsoid pointed to by eldef.

The delete is accomplished by creating a new Ellipsoid Dictionary file and copying all but the referenced ellipsoid definition from the existing dictionary to the new one. This implies that sufficient disk space must be available to perform this copy. A zero is returned if the delete was successfully completed, a -1 if a problem occurred. An attempt to delete a non-existent ellipsoid definition is NOT considered a problem.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_eldel will not delete an ellipsoid definition which is marked as being a distribution ellipsoid definition (i.e. cs_El def_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined ellipsoid is protected. For example, is cs_Protect is 60, a user-defined ellipsoid becomes protected 60 days after it is last modified.

ERRORS

CS_eldel will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred in copying the Ellipsoid Dictionary to the new file.
`cs_EL_BAD_MAGIC`	The file assumed to be the Ellipsoid Dictionary by virtue of its name and location was not an Ellipsoid Dictionary; it had an invalid magic number.
`cs_TMP_CRT`	The attempt to create a new file, to which the modified Ellipsoid Dictionary was to be copied, failed.
`cs_DISK_FULL`	Insufficient disk space was available to accommodate the copying of the Ellipsoid Dictionary to the new file.
`cs_UNLINK`	The request to remove the old copy of the Ellipsoid Dictionary failed.
`cs_RENAME`	The request to rename the new Ellipsoid Dictionary file from its temporary name to ELIPSOID failed.
`cs_EL_PROT`	The ellipsoid definition to be updated is a distribution ellipsoid definition and may not be deleted.
`cs_EL_UPROT`	The ellipsoid is a user-defined ellipsoid which has not been modified for 60 days and is therefore protected.

CS_eldflt Ellipsoid default

char *CS_eldlt (Const char *new_dflt);

Use CS_eldflt to control the status of the "defaultable" ellipsoid reference feature of CS-MAP. New_dflt must be either a pointer to a valid ellipsoid key name, a pointer to the null string, or the NULL pointer. In the case where new_dflt is a pointer to a valid ellipsoid definition key name, CS_eldflt causes the default ellipsoid feature to be activated, using the ellipsoid key name provided as the, possibly new, default value. When new_dflt is a pointer to the null string, CS_eldflt disables the default ellipsoid feature. When new_dflt is the NULL pointer, the status of the default feature remains unchanged.

In all cases, CS_eldflt returns the previous status (or in the case of new_dflt == NULL, the current status) in the form of a pointer to a static character array that shall contain the name of the previous default ellipsoid. Should the returned pointer point to a null string, the indicated status is disabled.

ERRORS

CS_eldflt will return the NULL pointer if the key name provided is not that of a valid ellipsoid. In this event, the status of the default ellipsoid feature remains unchanged.

CS_elEnum Ellipsoid enumerator

int CS_elEnum(int index, char *key_name, int size);

CS_elEnum returns a positive 1 to indicate success. If index is too large, a zero is returned.

ERRORS

CS_elEnum will return a -1 and set cs_Error appropriately if any of the following conditions are encountered:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary could not be found or otherwise opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred in accessing the Ellipsoid Dictionary.
`cs_DT_BAD_MAGIC`	The file assumed to be the Ellipsoid Dictionary by virtue of its name was not an Ellipsoid Dictionary; it had an invalid magic number.
`cs_INV_INDX`	The index argument was negative.

CS_elupd Ellipsoid dictionary update

int CS_elupd (struct cs_Eldef_ *el_def, int crypt);

CS_elupd will cause the ellipsoid definition pointed to by el_def to be added to the Ellipsoid Dictionary. If an ellipsoid with the same key name exists, it is replaced by the definition provided. If no such definition exists, the new definition is added to the dictionary. If crypt is non-zero, the ellipsoid entry is encrypted before being written.

In the event that the indicated ellipsoid already existed, CS_elupd will return a 1 to indicate a successful update. In the event that the provided ellipsoid had to be added to the Ellipsoid Dictionary, a zero is returned. A -1 is returned if the update failed for any reason.

Please note that the addition of a new ellipsoid definition requires the sorting of the Ellipsoid Dictionary file. This may take a few seconds to complete, depending upon the size of the Ellipsoid Dictionary.

If the value of the global variable cs_Protect is greater than or equal to zero, CS_elupd will not change an ellipsoid definition which is marked as being a distribution ellipsoid definition (i.e. cs_Elde_.protect == 1). If the value of cs_Protect is greater than zero, it is interpreted as the number of days after which a user defined ellipsoid is protected. For example, is cs_Protect is 60, a user-defined ellipsoid becomes protected 60 days after it is last modified.

Additionally, if the value of the global character variable cs_Unique is not the null character, CS_elupd will not add an ellipsoid definition if its key name does not contain the character indicated. For example, if cs_Unique is set to the colon character, CS_elupd will not add an ellipsoid definition whose key name does not contain a colon character.

ERRORS

CS_elupd will return a -1 and set cs_Error appropriately if any of the following conditions are encountered during the update:

Constant	Description
`cs_ELDICT`	The Ellipsoid Dictionary file could not be opened. (See `CS_altdr`)
`cs_IOERR`	A physical I/O error occurred during the update process.
`cs_EL_BAD_MAGIC`	The file which, by virtue of its name and location, was assumed to be an Ellipsoid Dictionary wasn't an Ellipsoid Dictionary; its magic number was invalid.
`cs_DISK_FULL`	There was insufficient disk space available to add the ellipsoid definition to the Ellipsoid Dictionary.
`cs_EL_PROT`	The ellipsoid definition to be updated is a distribution ellipsoid definition and may not be updated.
`cs_EL_UPROT`	The ellipsoid is a user-defined ellipsoid that has not been modified for 60 days and is therefore protected.
`cs_UNIQUE`	The ellipsoid provided does not already exist and would need to be added; but the key name does not contain the unique character.

CS_errmsg Error message

void CS_errmsg (char msg_bufr, int bufr_size);

CS_errmsg returns to the calling function a null terminated string that describes the last error condition detected by the CS-MAP library. The result is returned in the buffer pointed to by the msg_bufr argument, which is assumed to be bufr_size bytes long. The message is returned in one character per byte ANSI code characters.

CS_errmsg will return the null string if called before any error condition is detected.

BUGS

After returning an error message to the user, CS_errmsg should reset itself to the null string preventing the same error message from being returned a second time. It should, but it doesn't.

CS_ll2cs Latitude/Longitude TO Coordinate System

void CS_ll2cs (Const struct cs_Csprm_ *csprm, double xy[2], Const double ll[2] );

Given the definition of the coordinate system, csprm, such as returned by CS_csloc, CS_ll2cs will convert the latitude and longitude given by ll to X and Y coordinates, returning the results in xy. The ll and xy arguments may point to the same array.

In the arrays, the X coordinate and the longitude occupy the first element, the Y coordinate and the latitude the second element. The latitude and longitude must be given in degrees where negative values are used to indicate west longitude and south latitude.

CS_llchk Lat/Long limits check

int CS_llchk (Const struct cs_Csprm_ *csprm, int cnt, Const double pnts[][3]);

CS_llchk determines if the points, great circles, and regions defined by the point list provided by the cnt and pnts arguments are within the mathematical domain and useful range of the coordinate system provided by the csprm argument. All points in the point list are expected to be geographic coordinates. Use CS_xychk to check a list of cartesian coordinates.

CS_llchk returns cs_CNVRT_OK if all coordinate subject to the determination are both within the mathematical domain of the coordinate system and the useful range of the coordinate system. cs_CNVRT_DOMN is returned if one or more coordinates is outside of the mathematical domain of the coordinate system. cs_CNVRT_USFL is returned if all coordinates subject to the determination are within the mathematical domain of the coordinate system, but one or more coordinates are outside of the useful range of the coordinate system.

The useful range of a coordinate system may be defined by the user as part of the coordinate system definition. In the absence of such a definition, the setup function for each projection computes a useful range based on the parameters for the projection. In some cases, this computed useful range will be too liberal; in others it may be too conservative. In any case, checking coordinates to be converted against the useful range is a good way to alert users of a possible problem, such as using the wrong coordinate system for a set of coordinates.

CS_ludflt linear unit default

char *CS_ludlt (Const char *new_dflt);

Use CS_ludflt to control the status of the "defaultable" linear unit reference feature of CS-MAP. New_dflt must be either a pointer to a valid linear unit name, a pointer to the null string, or the NULL pointer. In the case where new_dflt is a pointer to a valid linear unit name, CS_ludflt causes the default linear unit feature to be activated, using the linear unit name provided as the, possibly new, default value. When new_dflt is a pointer to the null string, CS_ludflt disables the default linear unit feature. When new_dflt is the NULL pointer, the status of the linear unit default feature remains unchanged.

In all cases, CS_ludflt returns the previous status (or in the case of new_dflt == NULL, the current status) in the form of a pointer to a static character array which shall contain the name of the previous default linear unit. Should the returned pointer point to a null string, the indicated status is disabled.

ERRORS

CS_ludflt will return the NULL pointer if the key name provided is not that of a valid linear unit. In this event, the status of the default linear unit feature remains unchanged.

CS_xychk X and Y limits check

int CS_xychk (Const struct cs_Csprm_ *csprm, int cnt, Const double pnts[][3]);

CS_xychk determines if the points, line segments, and regions defined by the point list provided by the cnt and pnts arguments are within the mathematical domain and useful range of the coordinate system provided by the csprm argument. All points in the point list are expected to be cartesian coordinates. Use CS_llchk to check a list of geographic coordinates.

CS_xychk returns cs_CNVRT_OK if all coordinate subject to the determination are both within the mathematical domain of the coordinate system and the useful range of the coordinate system. cs_CNVRT_DOMN is returned if one or more coordinates is outside of the mathematical domain of the coordinate system. cs_CNVRT_USFL is returned if all coordinates subject to the determination are within the mathematical domain of the coordinate system, but one or more coordinates are outside of the useful range of the coordinate system.

CS_usrUnitPtr - Units look up hook function

double CS_usrUnitPtr (short type, Const char *unitName);

This name, CS_usrUnitPtr , does not refer to a function. Rather, it refers to a global variable which is defined as a pointer to a function which is defined as the above given prototype declares. Applications can use a function as declared above, and the related global pointer variable, to implement unit definitions in a dynamic manner.

If the global variable CS_usrUnitPtr (defined in CSdata.c) is not null, the indicated function is called whenever the CS-MAP library is asked to access a specific unit definition. This function, then, can be used to dynamically supply a unit conversion value which does not exist in the compiled unit table. Applications can use this to implement their own unit definition table or dynamically generate such a definition based on the unit name provided.

CS-MAP passes the unitName argument to the hook function prior to any validation, thus dynamic definition names need not adhere to the CS-MAP key name conventions. In the event that the hook function determines that it wishes to supply the definition, the desired conversion value must be returned. CS-MAP passed the unit type requested to the hook function using the type argument.

The hook function returns an integer value:

a positive non-zero value to indicate that a conversion value is being supplied by the hook function, and the value returned is indeed the conversion value.
zero is returned to indicate that normal CS-MAP unit table access is to be performed.
a negative value is returned to indicate that an error is to be reported. It is expect that the nature of the error would have already reported through the use of CS_erpt.

CS_unitAdd - Add unit to table

int CS_unitAdd (struct cs_Unittab_ *unitPtr);

Use this function to add a new unit to the unit table at run time. Essentially, the unit definition pointed to by the unitPtr argument is copied to a disabled entry in the compiled unit table. This function does not check any of the entries in the provided unit definition, so use this function with great care.

ERRORS

CS_unitAdd returns a zero value for success. A negative return value indicates a failure. In this case, one of the following error conditions will have been reported through the use of CS_erpt:

Constant	Description
`cs_UADD_TYP`	The type of unit specified in the provided definition was invalid. Must be either `cs_UTYP_LIN` or `cs_UTYP_ANG`.
`cs_UADD_DUP`	A unit definition with the (singular) name of given in the provided definition already exists in the unit table.
`cs_UADD_FULL`	All of the disabled slots in the unit table have been filled; thus the unit table is currently full.

CS_unitDel -- Delete unit from table

int CS_unitDel (short type, Const char *name);

Use this function to disable an entry in the unit table. The specific unit is identified by the type and name arguments. Type must be given as either cs_UTYP_LIN or cs_UTYP_ANG. Note that compiled (i.e. not necessarily added) unit entries can also be disabled. This will remove them from subsequent unit enumerations performed by CS_unEnum.

Errors

CS_unitDel will return a zero for success. A negative 1 is return to indicate failure. In the event of failure, one of the following error conditions will have been reported through CS_erpt:

Constant	Description
`cs_UDEL_NONE`	The named unit, of the provided type, did not exist in the unit table.

Low level interface functions

Functions which are considered part of the Low Level Interface are described in this section. Several of these functions require geographic arguments. Remember that these are required to be:

in longitude, latitude, and height order, and
given in degrees, and
referenced to Greenwich meridian, and
where west lonigtude and south latitude are represented by negative values.

Function prototype definitions are given in the C syntax only.