Home > Products > File Format Tools > DLL Reference
Welcome Products Services Contact Us Links
 
Products
GeoLab
Explorer
Closure
Smoother
Surface Area Calculator
Color Picker
File Format Tools
 
Services
Adjustments
Training
Software
Geoids

 
DLL Reference  
Data Types Most data types used by the Microsearch File Format Tools DLL are standard Windows data types as defined in the windows.h header file.  For more information on these standard data types, please see the documentation provided with your development tools.

The following special data structure is used by the MTFGetSupportedRecordIndex function, and is defined as follows in the MSTextFileFmt.h header file:

typedef struct tagMTFFRecordsInfo
{
LPCSTR lpRecordName;
LPCSTR lpFieldName;
LONG fieldType;
} MTFFRecordsInfo;

This structure allows you to easily set up a number of expected record names with  assocuated field names and field types  See the MTFGetSupportedRecordIndex documentation for more information.

The following special data structure is used by the MTFGetFieldInfo function, and is defined as follows in the MSTextFileFmt.h header file:

typedef struct tagMTFFFmtFieldInfo
{
LPCSTR cpFieldName;
LONG fieldType;
LONG iColumn;
LONG iWidth;
LONG iDecimals;
BOOL bExponential;
LPCSTR cpStrField;
LONG iField;
 double dField;
} MTFFFmtFieldInfo;

This structure allows you to retrieve field information. See the  MTFGetFieldInfo documentation for more information.

Function Reference

Name MTFGetHandle
Prototype MTF_HANDLE MTFGetHandle();
Description This function must be called to retrieve a handle required as a parameter in other functions, and always must be called before calling the other functions exported by the MSTextFileFmt.dll. To release resources allocated by this function, you must call the MTFReleaseHandle function (after you have finished using the handle in other function calls).
Return Values This function returns zero on failure, otherwise a valid handle is returned.

 

Name MTFIsHandleValid
Prototype BOOL MTFIsHandleValid(MTF_HANDLE handle);;
Description This function may be called to check that a handle is (still) valid. The handle parameter must have been created with the MTFGetHandle function.
Return Values This function returns true is the handle is valid, otherwise false is returned.

 

Name MTFReleaseHandle
Prototype BOOL MTFReleaseHandle(MTF_HANDLE handle);
Description This function releases resources allocated by the MTFGetHandle function. You must call this function after you have finished using the handle in other function calls in order to avoid memory leaks in your application.
Return Values This function returns TRUE on success. FALSE is returned if the handle parameter is invalid.

 

Name MTFLoadFormatFile
Prototype BOOL MTFLoadFormatFile(MTF_HANDLE handle, LPCSTR formatFilename);
Description This function loads a format file to use, and must be called before any text file I/O can be done. The specified format filename must exist, and must be a Microsearch Text Format file (normally with the "mtf" extension). Note that Microsearch Text Format files are created using the Microsearch File Format Editor (which you can use by calling the MTFShowTextFileFormatDlg function).
Return Values This function returns TRUE if the specified format file was loaded successfully. FALSE is returned if the handle is invalid, or if the specified file could not be loaded.

 

Name MTFGetRecordTypeCount
Prototype LONG MTFGetRecordTypeCount(MTF_HANDLE handle);
Description After a successful MTFLoadFormatFile call, get the number of record types defined in the loaded format.
Return Values A value greater than 0 is returned if the function succeeds. If the handle is not valid, or if a format was not loaded, 0 is returned.

 

Name MTFGetRecordTypeName
Prototype LPCSTR MTFFUNC MTFGetRecordTypeName(MTF_HANDLE handle, LONG index);
Description After a successful MTFLoadFormatFile call, get the name of the record type with the specified index.
Return Values If the handle is not valid, NULL is returned. If the index is out of range, NULL is returned, otherwise a pointer to the record name is returned.

 

Name MTFGetFieldCount
Prototype LONG MTFGetFieldCount(MTF_HANDLE handle, LPCSTR recordname);
Description After successful MTFLoadFormatFile and MTFGetRecordTypeName calls, get the number of fields in the record type with the specified name.
Return Values Zero is returned if the handle is not valid, a format was not loaded, or if the recordname is invalid. Otherwise the number of fields in the specified record is returned.

 

Name MTFGetFieldInfo
Prototype BOOL MTFGetFieldInfo(MTF_HANDLE handle, LPCSTR recordname, LONG index, MTFFFmtFieldInfo* pInfo);
Description After successful MTFLoadFormatFile and MTFGetRecordTypeName calls, get the field name with the specified record type and the specified field index.
Return Values TRUE is returned if the call is successful, otherwise FALSE is returned (the handle is not valid or the information could not be retrieved). If TRUE is returned, the structure pointed to by pInfo is filled with the requested information.

 

Name MTFDoesFormatHaveRecordWithField
Prototype BOOL MTFDoesFormatHaveRecordWithField(MTF_HANDLE handle, LPCSTR recordname, LPCSTR fieldname, LONG fieldtype);
Description This function asks whether the loaded format supports the specified field name with the specified field type in the specified record name. The fieldtype variable can be one of: MTFSTRING, MTFINTEGER, MTFDOUBLE, or MTFIDENT.
Return Values TRUE is returned if the specified record type exists in the loaded format, and that record type contains a field with the specified fieldname and fieldtype. FALSE is returned if the handle was invalid, if the reord is not defined in the file format, or if the field is not defined in the record.

 

Name MTFGetSupportedRecordIndex
Prototype LONG MTFGetSupportedRecordIndex(MTF_HANDLE handle, MTFFRecordsInfo* table, LONG nitems);
Description This function asks the loaded format to return the index of the first item in the specified table of MTFFRecordsInfo items contained in the format. If none of the items in the specified table are supported, -1 is returned. The variable nitems is the number of items in the specified table.
Return Values A value of -1 is returned if none of the table items are supported, or if the handle paramter is invalid. Other return values (0 or greater) are indices to the table of the first item supported by the format.

 

Name MTFShowTextFileFormatDlg
Prototype BOOL MTFShowTextFileFormatDlg(MTF_HANDLE handle, HWND parent, LPSTR formatFilename, LONG* nFilenameBufferSize);
Description This function displays the Microsearch Text Format Editor dialog which is a tool for creating and editing format files.
NOTE: for fixed-format records, the editor displays (to the user of the dialog) columns with origin 1 (the first column is 1).
The formatFilename parameter may contain the filename of a format file to load initialiy, but if not it should be null-terminated to an empty string. On return, the formatFilename variable contains the filename of the last format file loaded into the editor.
Specify the size (in bytes) of the buffer pointed to by formatFilename in the nFilenameBufferSize variable. If the buffer size is not large enough to hold the filename, it is set to the size required and false is returned. It is recommended that you use a buffer that is at least MAX_PATH bytes in size.
Return Values TRUE is returned if the Microsearch Text Format Editor dialog was displayed and the user clicked the OK button in that dialog. FALSE is returned if the handle parameter is invalid, if the user did not click the OK button, or if the filename buffer size was too small.

 

Name MTFGetFileFormatFilename
Prototype LPCSTR MTFGetFileFormatFilename(MTF_HANDLE handle);
Description This function returns a pointer to the current format filename (loaded by the MTFLoadFormatFile function). If no format filename is set, NULL is returned.
Return Values A pointer to the format filename is returned if successful, otherwise NULL is returned.

 

Name MTFTextFileOpen
Prototype BOOL MTFTextFileOpen(MTF_HANDLE handle, LPCSTR filename);
Description This function opens a text file with the specified filename for reading. When you are finished reading the file, you must call the MTFTextFileClose function.
Return Values This function returns TRUE if the handle parameter is valid, and if the specified file was opened. Otherwise FALSE is returned.

 

Name MTFTextFileReadRecord
Prototype LPCSTR MTFTextFileReadRecord(MTF_HANDLE handle, LONG* result, LPSTR pBadFieldName, LONG* nBadFieldNameBufferSize, LPSTR pMissingIncludeFilename, LONG* nFilenameBufferSize);
Description This function reads a line from the open text file. The text file must have been opened using the MTFTextFileOpen function. It returns the name of the record read if successful, or NULL if not successful. If NULL is returned, the result parameter will be set to one of the following values:
 
Result parameter Description
MTFEOF The normal end-of-file was encountered (all of the file was read successfully).
MTFBadRecord A non-blank and non-comment record was encountered that matched one of the record types defined in the file format, but the field parsing encountered invalid or insufficient data.
MTFNoFormat No format file was loaded (see the MTFLoadFormatFile function).
MTFFileNotOpen A text file was not opened (see the MTFTextFileOpen the function).
MTFInclude A file specified on an "include" record was not found. If pMissingIncludeFilename is not NULL, the missing filename is copied to the buffer pointed to by that variable. This result will occur only if the allowIncludes is TRUE.
MTFNoRecTypes No record types in the format file matched an encountered non-blank, non-comment record.
MTFHandle The handle parameter is invalid.
MTFBufferSize The nFilenameBufferSize buffer size was not large enough for the string that was to be copied into the pMissingIncludeFilename buffer.

If the result parameter is MTFBadRecord, the name of the offending field is copied to the buffer pointed to by the pBadFieldName parameter (unless the buffer size specified by nBadFieldNameBufferSize is too small, in which case the field name is not copied to the buffer, and the required buffer size is set in BadFieldNameBufferSize).
Use the MTFGetRecXXXFieldData method(s) to retrieve the data in the record read. Blank lines are ignored so this method won't return until a valid non-blank, non-comment line is encountered or the EOF is reached.
If the pMissingIncludeFilename parameter is not NULL, and if a C-style include record is encountered, line reading continues in the referenced file and then back to the line after the "include line", and so on. If the file for an "included filename" is not found, and pMissingIncludeFilename is not NULL, the filename of the missing file is copied to the pMissingIncludeFilename parameter and 0 is returned, in which case you can decide whether to ignore the missing file and continue, or not. Note that "include" records can be nested to any depth.
Specifiy the size of the buffer pointed to by pMissingIncludeFilename using the nFilenameBufferSize parameter. If this buffer size is too small for the filename of the missing "include" file, the nFilenameBufferSize is set to the required size and NULL is returned (to avoid this, ensure the buffer size is MAX_PATH or larger).
Return Values This function returns the name of the record read if successful, or NULL if not successful. See above for details.

 

Name MTFGetRecStringFieldData
Prototype BOOL MTFGetRecStringFieldData(MTF_HANDLE handle, LPCSTR fieldname, LPSTR data, LONG* nDataBufferSize);
Description After a successful MTFTextFileReadRecord call, this function retrieves the data for the record's field with the specified fieldname. NOTE: This function may be called for any field type, but the other two (MTFGetRecLongFieldData and MTFGetRecDoubleFieldData) will only be successful if the field data type matches the type of the data parameter. Specify the size (in bytes) of the buffer pointed to by the data parameter using the nDataBufferSize parameter.
Return Values This function returns TRUE if the field data was successfully retrieved. FALSE is returned if the handle is invalid, the field was invalid, or if the buffer size is too small to hold the field's data. If the buffer size was too small, the nDataBufferSize variable is set to the required size.

 

Name MTFGetRecLongFieldData
Prototype BOOL MTFGetRecLongFieldData(MTF_HANDLE handle, LPCSTR fieldname, LONG* data);
Description After a successful MTFTextFileReadRecord call, this function retrieves the data for the record's field with the specified fieldname. If the field type for the field with the specified field name is not MTFINTEGER, this function will return FALSE.
Return Values This function returns TRUE if the field data was successfully retrieved. FALSE is returned if the handle is invalid or if the field was invalid.

 

Name MTFGetRecDoubleFieldData
Prototype BOOL MTFGetRecDoubleFieldData(MTF_HANDLE handle, LPCSTR fieldname, double* data);
Description After a successful MTFTextFileReadRecord call, this function retrieves the data for the record's field with the specified fieldname. If the field type for the field with the specified field name is not MTFDOUBLE, this function will return FALSE.
Return Values This function returns TRUE if the field data was successfully retrieved. FALSE is returned if the handle is invalid or if the field was invalid.

 

Name MTFGetRecordText
Prototype BOOL MTFGetRecordText(MTF_HANDLE handle, LPSTR record, LONG* nRecordBufferSize);
Description After a successful call to MTFTextFileReadRecord , this function retrieves the text of the line (record) read. Specify the size of the buffer pointed to by the record variable using the nRecordBufferSize variable.
Return Values This function returns TRUE if the handle parameter is valid, and if the text line was successfully retrieved. If the buffer size specified by the nRecordBufferSize parameter is too small to hold the line, nRecordBufferSize is set to the required size and FALSE is returned.

 

Name MTFTextFileCreate
Prototype BOOL MTFTextFileCreate(MTF_HANDLE handle, LPCSTR filename);
Description This function creates a new, empty text file for writing, and must be called before you call the MTFPutRecXXXFieldData functions.
Return Values This function returns TRUE if the handle parameter is valid, and if the specified file was created. Otherwise, FALSE is returned.

 

Name MTFSetRecordType
Prototype BOOL MTFSetRecordType(MTF_HANDLE handle, LPCSTR recname);
Description This function sets the record type to write. If the record name specified does not exist in the currently loaded format (see MTFLoadFormatFile), false is returned, otherwise true is returned and you can use the MTFPutRecXXXFieldData methods to set the record's field data. NOTE: If there is only one record type in the currently loaded format, this function need not be called.
Return Values This function returns TRUE if the handle parameter is valid, and if the record type was successfully set. Otherwise, FALSE is returned.

 

Name MTFClearRecordFields
Prototype BOOL MTFClearRecordFields(MTF_HANDLE handle);
Description After a successful SetRecordType, clear all fields in the set record type (note that if there is an "Identifier" field in the record, it is not cleared). Fields are "cleared" by setting their contents to an empty string for "String" fields, or to zero for "Integer" and "Double" fields.
Return Values This function returns TRUE if the handle parameter is valid, and if the fields were successfully cleared. Otherwise, FALSE is returned.

 

Name MTFPutRecStringFieldData
Prototype BOOL MTFPutRecStringFieldData(MTF_HANDLE handle, LPCSTR fieldname, LPCSTR data);
Description After a successful MTFSetRecordType call, this function sets the data in the specified field. NOTE: The specified field's type must be MTFSTRING or MTFIDENT for this function to succeed.
Return Values This function returns TRUE if the handle parameter is valid, and if the data was succesfully written to the specified field. Otherwise, FALSE is returned.

 

Name MTFPutRecLongFieldData
Prototype BOOL MTFPutRecLongFieldData(MTF_HANDLE handle, LPCSTR fieldname, LONG data);
Description After a successful MTFSetRecordType call, this function sets the data in the specified field. NOTE: The specified field's type must be MTFINTEGER for this function to succeed.
Return Values This function returns TRUE if the handle parameter is valid, and if the data was succesfully written to the specified field. Otherwise, FALSE is returned.

 

Name MTFPutRecDoubleFieldData
Prototype BOOL MTFPutRecDoubleFieldData(MTF_HANDLE handle, LPCSTR fieldname, double data);
Description After a successful MTFSetRecordType call, this function sets the data in the specified field. NOTE: The specified field's type must be MTFDOUBLE for this function to succeed.
Return Values This function returns TRUE if the handle parameter is valid, and if the data was succesfully written to the specified field. Otherwise, FALSE is returned.

 

Name MTFTextFileWriteRecord
Prototype BOOL MTFTextFileWriteRecord(MTF_HANDLE handle);
Description This function writes a line to the text file. The contents (fields) of the line are written to the created text file (see MTFTextFileCreate).
Return Values This function returns TRUE if the handle parameter is valid, and if the record was successfully written. Otherwise, FALSE is returned.

 

Name MTFGetIgnoreCharacterSets
Prototype BOOL MTFGetIgnoreCharacterSets(MTF_HANDLE handle, LPSTR startingWith, LPSTR notStartingWith, LONG* nBufferSize);
Description This function retrieves the character sets for the format's "ignore lines starting with" and "ignore lines not starting with" configuration. If either of these settings is not used by the file format, the corresponding parameter will be set to an empty string. The nBufferSize must be set to the size (in bytes) of the buffers pointed to by the startingWith and notStartingWith parameters.
Return Values This function returns TRUE if the strings were successfully retrieved, otherwise FALSE is returned. If the size specified by the nBufferSize is too small to hold the strings, FALSE is returned and the required size is set in the nBufferSize parameter.

 

Name MTFTextFileWriteLine
Prototype BOOL MTFTextFileWriteLine(MTF_HANDLE handle, LPCSTR line);
Description This function writes a 'comment' line to the text file (note that the rules for non-blank comment lines are specified in the format, , see MTFGetIgnoreCharacterSets). Note that this function looks after adding the '\n' character to the line written. Also note that you don't have to call the MTFTextFileWriteRecord function after using this function because this function does the actual write.
Return Values This function returns TRUE if the handle parameter is valid, and if the line was successfully written. Otherwise, FALSE is returned.

 

Name MTFTextFileClose
Prototype BOOL MTFTextFileClose(MTF_HANDLE handle);
Description This function closes the text file after a MTFTextFileOpen or MTFTextFileCreate call.
Return Values This function returns TRUE if the handle parameter is valid, and if the file was successfully closed. Otherwise, FALSE is returned.

 

Name MTFGetVersionString
Prototype BOOL MTFFUNC MTFGetVersionString(LPSTR version, LONG* nBufferSize);
Description This function copies the current version string into the buffer pointed to by the version parameter. That buffer size should be at least 64 bytes. Specify the buffer size in the nBufferSize parameter. The version string is in the form: "Microsearch Text File Format Tools, V2001.3.12.0".
Return Values TRUE is returned if the function succeeds in retrieving the version string, otherwise FALSE is returned. If the specified buffer size (nBufferSize) is too small to hold the version string, FALSE is returned, and the nBufferSize parameter is set to the required size.
 
 
©2006 BitWise Ideas Inc. All Rights Reserved.
All names are (registered) trademarks of their respective companies.