GoldMine Application Programming Interface Specification and Reference
GMW_DS_Fetch’s Return Packet Explained
Download 465.93 Kb.
|
- Navigate this page:
- GM5S32.DLL - Low-Level access using Work Areas
- GM5S32.DLL - Updating Sync Logs
- GM5 COM Object
GMW_DS_Fetch’s Return Packet ExplainedGMW_DS_Fetch returns a single packet string containing the data from all requested records. The packet includes a header record, followed by one record for each record evaluated by “fetch.” Within each record in the packet, the fields are separated by a field delimiter specified in GMW_DS_Range or GMW_DS_Query. By default, the field delimiter is the carriage return character (13 or 0x0D). The records in the packet are separated by the record delimiter. By default, the record delimiter is the line feed character by default (10 or 0x0A). These delimiters are convenient when the requested data does not contain notes from blob fields. When requesting notes, override the default delimiters by passing other delimiter values to GMW_DS_Range() and GMW_DS_Query(). For packets with notes, good delimiters are the ASCII characters 1 and 2. GMW_DS_Fetch might return a packet of data similar to: 3000-0004 Bill|Boston|23 Michael|London|393 Calvin|Los Angles|633 Larry|New York|29
0 - indicates that more records are available, which could be fetched with another GMW_DS_Fetch call 3 - indicates the end-of-file (EOF) 4 - indicates the beginning-of-file (BOF)
Syntax: GMW_DS_Fetch( <iHandle>, <szBuf>, <iBufSize>, <nGetRecs> ) Parameters: <iHandle> The Datastream handle returned by GMW_DS_Range or GMW_DS_Query <szBuf> Buffer to hold result packet <iBufSize> Size of returned <nGetRecs> Number of records to fetch. GMW_DS_Close GMW_DS_Close must be called when the DataStream operation is complete. Unclosed DataStreams will leak memory and leave the database connections needlessly open. Passing a Handle of 0 closes all open DataStream objects. Syntax: GMW_DS_Close( <iHandle>) Parameters: <iHandle> The Datastream handle returned by GMW_DS_Range or GMW_DS_Query Returns: 1 Success
GM5S32.DLL - Low-Level access using Work AreasIntroduction GoldMine’s GM5S32.DLL provides a complete set of functions that allow low-level access to the database tables. Using these functions, you can:
Note! These functions allow direct access to the data and require a very sophiscated knowledge of the GoldMine schema and database methodology. It is highly recommended that before resorting to these functions you first look at the Business logic functions to handle your needs. The Business Logic functions actually wrap these low-level functions and use them properly and are therefore “safer” to use. Database applications that need varied access to GoldMine data typically use this suite of functions. To work successfully, these functions rely on a work area parameter. Using this parameter, you can open multiple data files concurrently, and manipulate each file independently by referencing the file by work area. These functions also maintain synchronization information, which is stored in the TLogs. Detailed descriptions of each database access function appear on the following pages. Some of the following functions make reference to table names, field names, and index names. For details, see “Database Structures” in the GoldMine Reference Manual and/or Help file. Opening/Closing databases These are functions important to all other low-level operations. Opening and closing databases is required for proper operation of all other low-level functions. GMW_DB_Open Opens one of GoldMine’s data files for processing by another application. Syntax: GMW_DB_Open( <szTablename> ) Parameters: <szTableName> The name of the table to open. You may use a full path if required for dBase tables Returns: >0 Success – A Work Area handle is returned
GMW_DB_Close Releases a previously opened file when processing is complete. All previously opened files must be properly closed—failure to do so can result in database errors.
0 Failure GMW_DB_IsSQL Used to determine if the table is SQL or dBASE. Syntax: GMW_DB_IsSQL( <lWorkArea> ) Parameters: <lWorkArea> The work area handle as returned by GMW_DB_Open Returns: 1 Table is SQL
Creating and Deleting Records The following functions will allow you to add and delete records from the database.
Adds a new, empty record to a GoldMine data file. Before using GMW_DB_Append, you must open a data file using the GMW_DB_Open function. After executing the GMW_DB_Append function, the record pointer is positioned at the new empty record, and the record is locked and ready to accept field replacements. This function will lock the record so you should always call GMW_DB_Unlock when finished using this function. When a CONTACT1 record is appended, GoldMine automatically fills in the new record with the appropriate ACCOUNTNO and CREATEBY values. For all other table records, you must replace the ACCOUNTNO field with the value from the CONTACT1 record with which the new record is to be linked. For records that require remote synchronization initialization, GoldMine will automatically fill in the value of the RECID field when these records are appended. Syntax: GMW_DB_Append( Parameters: Returns: RecNo of new record (dBase) RecID of new record is returned in
GMW_DB_Delete Deletes the current record in the specified work area, and moves the record pointer to the next record. For records that require remote synchronization initialization, GoldMine will automatically maintain the TLog entry. Syntax: GMW_DB_Delete( <lWorkArea> ) Parameters: <lWorkArea> The work area handle as returned by GMW_DB_Open Returns: 1 Success 0 Failure Reading/Writing Data The following functions allow you to read and write to the database.
Queries a data file for the value of a field. Syntax: GMW_DB_Read(l <lWorkArea>, <szField>, <szBuf>, <iBufSize> ) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. Returns: 1 Success 0 Failure
Used to determine either current record number (dBASE), or the RecID (SQL). Syntax: GMW_DB_RecNo( <lWorkArea> ) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. Returns: RecNo dBase returns the current record number. RecID SQL returns the current RecID. GMW_DB_Replace Changes the value in a particular field in one of GoldMine’s data files. You should always call GMW_DB_Unlock when finished using this function. Syntax: GMW_DB_Replace(long lWorkArea, char *szField, char *szData, int iAddTo) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. Returns: 1 Success
GMW_DB_Unlock Unlocks a record previously locked by a call to either GMW_DB_Append or GMW_DB_Replace. under SQL, an optimistic lock replace failure will suppress the UI and cause GMW_DB_Unlock to return FALSE.
Limiting scope of data These functions will limit the scope of data available. You might wat to limit the data to only those records in a particular state for example. Using scopes wisely can greatly increase performace for subsequent operations. GMW_DB_Filter Limits access to data in a GoldMine database by creating a subset of records based on expression criteria. This function is similar to GMW_DB_Range. If successfully called, all other functions (GMW_DB_Top, GMW_DB_Bottom, GMW_DB_Skip, etc.) will respect the filter. Syntax: GMW_DB_Filter( <lWorkArea>, <szFilterExpr>) Parameters: <lWorkArea> The work area handle as returned by GMW_DB_Open <szFilterExpr> An xBase filter expression. Returns: 1 Success 0 Failure GMW_DB_Range Activates the index in a table, and set a range of values to limit the scope of data that GoldMine will search. This function is faster than GMW_DB_Filter. The Min and Max values must be formatted the same as the selected index name’s expression. If successfully called, all other functions (GMW_DB_Top, GMW_DB_Bottom, GMW_DB_Skip, etc.) will respect the range. Syntax: GMW_DB_Range( <lWorkArea>, <szMin>, <szMax>, <szTag>) Parameters: <lWorkArea> The work area handle as returned by GMW_DB_Open <szMin> Minimum or lower value of the range. <szTag> the index name. Returns: 1 Success 0 Failure Searching for data These functions allow you to perform searches on the database. GMW_DB_Search Performs a sequential search on a file. Syntax: GMW_DB_Search(<lWorkArea>, <szExpr>, <szRecID>) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. Returns: >0 RecNo (dBase) or RecID (SQL) of matching record 0 No match found
Positions to the first record matching the seek value. You should use GMW_DB_SetOrder prior to using this function. Syntax: GMW_DB_Seek(long lWorkArea, char * szParam) Parameters: Returns: 2 Exact match not found. Cursor placed at closest match
0 No match or Error occurred GMW_DB_SetOrder Sets the current index on the table. Syntax: GMW_DB_SetOrder( Parameters: Returns: 1 Index successfully activated 0 Error
These function will allow you to move to different records in the database. Most of the functions in this section will respect any scope limits placed on the table by the GMW_DB_Filter or GMW_DB_range functions.
Positions the record pointer to a particular record in a data file. This function accepts several commands. Each of these commands has an independent function equivalent that is the preferred method to use. This function remains as a legacy to its DDE counterpart:
Syntax: GMW_DB_Move( <lWorkArea>, <szCommand>, <szParam> ) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. <szParam> The scope or value for the command. Returns: 4 Cursor at beginning of file (BOF) 3 Cursor at end of file (EOF)
0 Error GMW_DB_Goto Positions to a specific record in the table.
Returns: 4 Cursor at beginning of file (BOF) 3 Cursor at end of file (EOF) 2 Exact match not found. Cursor placed at closest match. 1 Exact match found, Cursor moved, or index successfully activated 0 Error
Positions to the first record in the table.
GMW_DB_Skip Moves the cursor forward or back in the table.
3 Cursor at end of file (EOF) 1 Exact match found, Cursor moved, or index successfully activated 0 Error
GMW_DB_Bottom Positions to the last record in the table. Syntax: GMW_DB_Bottom( <lWorkArea>) Parameters: <lWorkArea> The work area handle of the file opened by the GMW_DB_Open function. Returns: 1 Cursor positioned at the last record in the file 0 Error
Quick Functions The functions in this section are wrappers for the various other low-level functions. They are provided as a quick and easy way to perform common tasks. Be aware that although the functions are named “Quick” it is meant in the context of convenience and not speed of operation. When used in a single instance these functions are just as fast as the low-level function however, when used in loops these function perform more slowly. The reason is because these function each open/close their own work areas each time they are called. GMW_DB_QuickSeek This function will wrap several other DB functions to provide a quick and easy way to seek a record in the database. Syntax: GMW_DB_QuickSeek(char *szTableName, char *szIndex, char *szSeekValue, char *szRecID) Parameters: <szTableName> The name of the table to be opened. <szIndex> The index to use for the table. <szSeekValue> The seek expression to use. <szRecID> Returned by the function. This will be the RecID of the record that is found. Returns: 1 Success
-1 Invalid table -2 Invalid Index GMW_DB_QuickRead This function will wrap several other DB functions to provide a quick and easy way to read a field value from record in the database. Syntax: GMW_DB_QuickRead( <szTableName>, <szRecID>, <szField>, <szValue>, <iLen> ) Parameters: <szTableName> The name of the table to be opened. <szRecID> The RecID of the record to read from. <szField> The Field name to return. <szValue> The value returned by the function. <iLen> The length of the returned data. Returns: 1 Success
-1 Invalid Table -3 RecID not found -4 Invalid Fieldname GMW_DB_QuickReplace This function will wrap several other DB functions to provide a quick and easy way to replace a field value from record in the database. Syntax: GMW_DB_QuickReplace( <szTableName>, <szRecID>, <szField>, <szValue>, <iAddTo>) Parameters: <szTableName> The name of the table to be opened. <szRecID> The RecID of the record to be updated. <szField> The Field name to replace. <szValue> The value to store in the field. <iAddTo> Indicates if the value data is to be appended (1) or replaced (0=default). Returns: 1 Success
-1 invalid table -2 Invalid RecID -3 RecID Not Found -4 Invalid Fieldname GM5S32.DLL - Updating Sync LogsGoldMine’s GM5S32.DLL offers developers a method to update the GoldMine synchronization logs whenever an external application updates GoldMine data outside of the GM5S32.DLL or GM5 COM object functions. GMW_UpdateSyncLog GMW_LoadBDE must be called before calling GMW_UpdateSyncLog for the first time. When updating multiple fields of the same record, GMW_UpdateSyncLog must be called for each modified field. However, if the first call returns 1 or 2, it is not necessary to call GMW_UpdateSyncLog for the rest of the modified fields for that specific record.
4 Field Tlog entry created 2 New Tlog entry update 1 New Tlog entry created 0 Failure GMW_ReadImpTLog GMW_LoadBDE must be called before calling GMW_ReadImpTLog for the first time. GMW_ReadImpTLog is executed in a thread, so multiple calls can be made. Your application can determine when the imported process completes by setting the iDeleteWhenDone parameter to 1, and noting when the import file is deleted. The TLog import must have the structure shown below:
Syntax: GMW_ReadImpTLog( <szFile>, <bDelDone>, <szStatus> ) Parameters: <szFile> Specifies the import file name. <bDelDone> Specifies to delete the import file when the process has completed. <szStatus> Buffer used to monitor the status of the process. Optional, can be NULL. If passed, the szStatus buffer must be at least 10 characters long. Returns: >0 Success. Total number of imported Tlog records.
GMW_NewRecID GMW_NewRecID returns a new RecID in the szRecIDBuf. GMW_NewRecID can be called without first calling GMW_LoadBDE.
GMW_SyncStamp Converts Sync Stamp to time format and back.
Returns: 1 Success 0 Failure
The GoldMine COM API wraps the 'C' API (GM5S32.DLL) in order to simplify access to the Name/Value pair component of the GoldMine API as well as the low-level WorkArea API. All objects are exposed using dual interfaces, in order to make them accessible to both clients that support virtual table binding, and clients that only support Dispatch Table binding (such as VBScript or JScript). This document describes the objects in the COM API and how to use them. For specific information about available Name/Value pairs, and the transactions that can be executed, refer to “Business Logic Methods”. For specific information about the low-level WorkArea API, refer to the section "GM5S32.DLL - Low Level Access using Work Areas" The Object Model Figure 1 shows the objects in the model, together with their methods and properties. Not all of these objects are visible to the Visual Basic/Visual Basic Scripting Edition/ or Java Script client. The two enumerator objects are present to support Visual Basic’s For Each syntax. A brief summary of the model is in order at this point. Only the top level object (GMApplication) is directly creatable by the client. This object encapsulates the functionality required to manage logins and logouts. The client would create an instance of this object, set its properties, and call Login. After a successful login, the client would then call NewContainer to create a new Name Value pair container. This would return an instance of the GMWContainer class. The container class exhibits standard COM Collection semantics. It supports methods to allow the client to add name/value pairs, remove them, and get them by name. It also supports an enumerator that allows enumeration through all the pairs on a specific container. The use of default methods allows VB(Script) and JavaScript clients a simplified syntax for accessing the object. This will be expanded on in the specific documentation on the Container object. When a client adds a new Name/Value pair, a GMNVPair object is returned. This can in turn behave as a collection of values, since it is possible to have single of multiple valued NV Pairs. Once again, the use of default methods simplifies the client programming model. To Use the WorkArea API, the developer would call NewWorkArea on the Application object, which is the equivalent of the GMW_DB_Open function on the ‘C’ API. Thereafter the methods on the WorkArea class will act on the WorkArea (or table) that was opened, to allow the developer to read and update this table. All methods on all classes make use of standard COM error handling to indicate failure. In the event of a call failing, a failure HRESULT will be returned (a VB exception), and a standard COM ErrorInfo object will be used to provide rich error information. All Error codes are made available through the EGMErrors enumeration in the type library. The Application class. This is the entry point to the Object Model. The Application class is call GMApplication. It can be instantiated using the ProgId “GMCOMApi.Application”. Directory: downloads downloads -> Northern England’s set-jetting locations downloads -> Dynatest 3031 lwd light Weight Deflectometer downloads -> Forth coming competitive exams downloads -> Brush High School Morning Announcements Friday, September 05, 2014 all school downloads -> Year 9 The Arts — Music downloads -> Years 7 and 8 standard elaborations — Australian Curriculum: Music draft downloads -> Chris Young sets 2016 “I’m Comin’ Over” Tour headlining dates downloads -> Slavery and Abolition: the Plymouth Connection Introduction downloads -> Summer Assignment Download 465.93 Kb. Share with your friends:
|
Figure 1 - The GM COM API Object Model