GoldMine API Specification and ReferencePage 1
GoldMine Application Programming Interface
Specification and Reference
Copyright1999 GoldMine Software Corporation
______
Authors:Elan Susser
Nelson Fernandez
Nigel Bassel
Kim Novins
Product:GoldMine
Product Version:5.0
Created:May 15, 1999
Last Updated:November 9, 1999
Table of Contents
Table of Contents......
Introduction......
Business Logic Explained......
GM5S32.DLL - Loading and Logging In......
GMW_LoadBDE......
GMW_UnloadBDE......
GMW_SetSQLUserPass......
GM5S32.DLL - Name/Value Functions......
Introduction......
GMW_NV_Create......
GMW_NV_CreateCopy......
GMW_NV_Copy......
GMW_NV_Delete......
GMW_NV_GetValue......
GMW_NV_SetValue......
GMW_NV_NameExists......
GMW_NV_EraseName......
GMW_NV_EraseAll......
GMW_NV_Count......
GMW_NV_GetNameFromIndex......
GMW_NV_GetValueFromIndex......
GMW_NV_SetStr......
GMW_Execute......
Business Logic Methods......
Introduction......
WriteContact......
WriteContactNotes......
WriteOtherContact......
WriteDetail......
WriteLinkedDoc......
WriteReferral......
WriteSchedule......
WriteHistory......
AttachTrack......
SQLStream......
ReadRecord......
ReadContact......
GetContactAlerts......
SetContactAlerts......
GetAllAlerts......
GetUsersList......
GetGroupUsersList......
GetUserMemberships......
WriteGroupUsersList......
IsContactCurtained......
SendGMEmail......
ContactLogin......
GM5S32.DLL – Security Information Functions......
Introduction......
GMW_UserAccess......
GMW_CalAccess......
GMW_HistAccess......
GMW_GetLicenseInfo......
GMW_IsUserGroupMember......
GM5S32.DLL – DataStream Functions......
Introduction......
Advantages of using DataStream......
DataStream Record Selection......
GMW_DS_Range......
GMW_DS_Query......
GMW_DS_Fetch......
GMW_DS_Fetch’s Return Packet Explained......
GMW_DS_Close......
GM5S32.DLL - Low-Level access using Work Areas......
Introduction......
Opening/Closing databases
GMW_DB_Open......
GMW_DB_Close......
GMW_DB_IsSQL......
Creating and Deleting Records
GMW_DB_Append......
GMW_DB_Delete......
Reading/Writing Data
GMW_DB_Read......
GMW_DB_RecNo......
GMW_DB_Replace......
GMW_DB_Unlock......
Limiting scope of data
GMW_DB_Filter......
GMW_DB_Range......
Searching for data
GMW_DB_Search......
GMW_DB_Seek......
GMW_DB_SetOrder......
Navigating the database
GMW_DB_Move......
GMW_DB_Goto......
GMW_DB_Top......
GMW_DB_Skip......
GMW_DB_Bottom......
Quick Functions
GMW_DB_QuickSeek......
GMW_DB_QuickRead......
GMW_DB_QuickReplace......
GM5S32.DLL - Updating Sync Logs......
GMW_UpdateSyncLog......
GMW_ReadImpTLog......
GMW_NewRecID......
GMW_SyncStamp......
GM5 COM Object......
Introduction......
The Object Model......
The Application class......
Properties......
SystemFolder......
GoldmineFolder......
CommonFolder......
GMUserName......
GMPassword......
SQLUserName......
SQLPassword......
LicenseInfo......
Methods......
Login......
Logout......
NewContainer......
Execute......
NewWorkArea......
The Container class......
Properties......
Count......
_NewEnum......
Add......
Remove......
Methods......
Item......
CopyFrom......
Copy......
The Name/Value Pair Class......
Properties......
Count......
Name......
_NewEnum......
Methods......
Add......
Item......
The WorkArea Class......
Methods......
Append......
Replace......
Delete......
Unlock......
Read......
Top......
Bottom......
SetOrder......
Seek......
Skip......
Goto......
Move......
Search......
Filter......
Range......
RecNo......
IsSQL......
The LicenseInfo Class......
Properties......
Licensee......
LicenseNumber......
SiteName......
LicensedUsers......
LicensedSQLUsers......
LicensedGoldSyncSites......
IsDemo......
IsPrimaryLicense......
IsRemoteLicense......
IsUSALicense......
DLLVersion......
Code Examples - GM5S32.DLL......
C++......
Function prototypes......
Logging In......
Creating a Contact with Business Logic......
Enumerating a Name Value Container......
DataStream......
Low-Level Work Area......
Visual Basic......
Function prototypes......
Logging In......
Creating a Contact......
Enumerating a Container......
DataStream......
Low-Level WorkArea......
Delphi......
Function prototypes......
Logging In......
Creating a Contact......
Enumerating a Container......
DataStream......
Low-Level Work Area......
Code Examples - GM5 COM Object......
C++......
Logging In......
Creating a Contact......
Enumerating a Container......
VB/VBScript......
Logging In......
Creating a Contact......
Enumerating a Container......
JScript......
Logging In......
Creating a Contact......
Enumerating a Container......
WorkArea / LicenseInfo......
Delphi......
Logging in......
Creating a contact......
Enumerating a container......
Introduction
GoldMine’s GM5S32.DLL is a standard dynamic-link library (DLL) that offers developers efficient methods to both access GoldMine’s databases, and to update GoldMine’s synchronization logs when external applications update GoldMine data. Most development environments can load GM5S32.DLL. GoldMine does not need to run to use GM5S32.DLL.
GM5S32.DLL installs into the \WINDOWS\SYSTEM directory automatically with GoldMine 5.0. Therefore, third-party developers do not need to distribute GM5S32.DLL with their applications.
For an in-depth discussion on interfacing with GoldMine, visit the Public.GoldMine.Programming newsgroup, which you can access directly from the GoldMine Web site at
This document contains the information you need to:
- Load and initialize GM5S32.DLL
- Use of the new Business Logic functions
- Work with DataStream functions
- Work with low-level data access functions
- Update GoldMine synchronization information when data is changed by an external application
Business Logic Explained
GoldMine 5 introduces a new concept for people wishing to develop integrated products with GoldMine. We call this “Business Logic”. Business Logic transactions are commonly used procedures wrapped into a single call. For example to attach a new profile to a record you simple execute the WriteProfile function.
In order to make these Business Logic methods useful, there must be a way to pass multiple parameters to the various methods. To accomplish this GoldMine provides a set of functions to control Name/Value containers. All Business Logic functions rely on a Name/Value container to hold the multiple parameters and return values.
The GoldMine API allows you to call these functions from the GM5S32.DLL or a GM COM object.
Name/Values Containers
Name/Values - or NVs - are simply a ‘Name’ and a ‘Value combination. You can equate a Name/Value to the following example:
Company=GoldMine Software Corporation
‘Company’ is the Name and ‘GoldMine Software Corporation’ is the Value.
Using a set of NV pairs provides an easy mechanism to pass multiple parameters to a function. By allowing the user to populate the NV pairs into a set or ‘container’, and then executes a Business Logic transaction against the set. The transaction will then add extra pairs to the container to return the results.
Since the NV container remains in memory until you clear it, it can be used to make several calls without clearing all the previous values. This would be useful when you want to call the same function with only slight changes to the values such as scheduling a recurring activity or when a return value of one call is needed for a subsequent call.
The Business Logic methods allow the programmer to easily read and write GoldMine data. In the past one had to be very familiar with the schema and methodology of GoldMine databases in order to integrate with GoldMine. The new Business Logic functions ease this burden and provide a more standardized and safe way to integrate with GoldMine. Business Logic functions wrap several other low-level calls to perform common tasks. We can compare an example flow to a common task using both methods:
Method 1, updating a contact record using the GM5S32.DLL or DDE:
Step 1 – Open the Contact1 database
Step 2 – Set the index tag
Step 3 – Seek the record
Step 4 – If not found then Append a new record
Step 5 – Replace field values
Step 6 – Close the database
Method 2, updating a contact record using the Business Logic Methods:
Step 1 – Load an NV Container with the values for the contact record
Step 2 – Execute the ‘WriteContact’ method.
This is a basic example but you can see how much simpler Method 2 would be compared to Method 1.
GM5S32.DLL - Loading and Logging In
The following section describes the functions available for the programmer to Load the BDE and login to a GoldMine table. You can refer to section “Code Examples - GM5S32.DLL” for function prototypes and code examples in C++, Visual Basic and Delphi.
GMW_LoadBDE
Loads the BDE. GMW_LoadBDE must be called before calling any function that accesses databases, such as GMW_DB_Read and GMW_DS_Query. GMW_UnloadBDE must be called before unloading the DLL.
Syntax:GMW_LoadBDE( <szSysDir>, <szGoldDir>, <szCommonDir>, <szUser>, <szPassword> )
Parameters:szSysDirspecifies the location of LICENSE.DBF.
szGoldDirspecifies the location of CAL.DBF.
szCommonDir specifies the location of CONTACT1.DBF.
szUserspecifies the GoldMine user name (must be UPPERCASE).
szPasswordspecifies the user’s password (must be UPPERCASE).
Returns: 1 Success
0 BDE already loaded
-1BDE failed to load
-2LICENSE table not found in SysDir
-3Cannot load LICENSE table
-4Invalid username and/or password
-5CAL table not found in GoldDir
-6CONTACT1 table not found in CommonDir
GMW_UnloadBDE
Unloads the BDE. If GMW_LoadBDE is called, GMW_UnloadBDE must be called before unloading the DLL.
Syntax:GMW_UnloadBDE
Returns:1Success
0Failure
GMW_SetSQLUserPass
SQL only. GMW_SetSQLUserPass should be called immediately prior to the GMW_LoadBDE call. GMW_SetSQLUserPass is required only when accessing SQL tables and will have no affect on dBase tables.
Syntax: GMW_SetSQLUserPass( <szUserName>, <szPassword> )
Parameters:szUserName specifies the SQL login name.
szPassword> specifies the password for SQL login name.
Returns:1Success
0Failure
GM5S32.DLL - Name/Value Functions
Introduction
The following section describes the functions available for the programmer to manipulate Name Value containers. You can refer to section “Code Examples - GM5S32.DLL” (page 43) for function prototypes and code examples in C++, Visual Basic and Delphi.
Note: These functions require that you are successfully logged into a GoldMine database using the GMW_LoadBDE function.
GMW_NV_Create
This function creates a pointer to a new NV container.
Syntax:GMW_NV_Create()
Example: pGMNV := GMW_NV_Create;
Returns:Pointer to a new NV container.
GMW_NV_CreateCopy
Creates a new NV container and and copies the values from an existing NV container.
Syntax:GMW_NV_CreateCopy( <hgmnv> )
<hgmnv>Pointer to the source NV container.
Example:pGMNV2 := GMW_NV_CreateCopy(pGMNV);
Return:Pointer to a new NV container.
GMW_NV_Copy
Copies the values from one NV container to another. GMW_NV_Create or GMW_NV_CreateCopy must have previously created both NV containers.
Syntax:GMW_NV_Copy( <Dest_hgmnv>, <Source_hgmnv> )
<Dest_hmgmnv>Pointer to the destination container.
<Source_hgmnv>Pointer to the source container.
Example:GMW_NV_Copy(pGMNV2, pGMNV);
Return: n/a
GMW_NV_Delete
Deletes an NV container and releases it’s memory. Be sure to call this for all previously created containers before exiting your application.
Syntax:GMW_NV_Delete( <hgmnv> )
<hgmnv>pointer to the NV container to delete.
Example:GMW_NV_Delete(pGMNV);
Return:n/a
GMW_NV_GetValue
Reads a value stored in an NV container. If the name does not exit in the container the default value is returned.
Syntax:GMW_NV_GetValue( <hgmnv>, <Name>, <Default> )
<hgmnv>pointer to a valid name value container
<Name>name of the value to return
<Default>default value if <Name> is null or does not exist.
Example:sValue := GMW_NV_GetValue(pGMNV, ‘Phone1’, ‘(none)’);
Returns:The value of the <Name> is returned. If the <Name> is null or does not exist then the <Default> value is returned.
GMW_NV_SetValue
Stores a name value pair in the specified container.
Syntax:GMW_NV_SetValue( <hgmnv>, <Name>, <Value> )
<hgmnv>pointer to a valid name value container
<Name>name of the value to set
<Value>value to assign to <Name>.
Example:GMW_NV_SetValue(pGMNV, ‘Phone1’, ‘(310)555-1212’);
Return:n/a
GMW_NV_NameExists
Checks if the specified Name Value exists within the NV container.
Syntax:GMW_NV_NameExists( <hgmnv>, <value> )
<hgmnv>pointer to a valid name value container
<Name>name of the value to set
Example:iResult := GMW_NV_NameExists(pGMNV, ‘Phone1’);
Return:0 – Value does not exist in container
1 – Value exists in container
GMW_NV_EraseName
Remove a Name Value pair from the spcified container
Syntax:GMW_NV_EraseName( <hgmnv>, <value>)
<hgmnv>pointer to a valid name value container
<Name>name of the value to set
Example:GMW_NV_EraseName(pGMNV, ‘Phone1’)
Return:n/a
GMW_NV_EraseAll
Removes all Name Value pairs from the specified container
Syntax:GMW_NV_EraseAll( <hgmnv> )
<hgmnv>pointer to a valid name value container
Example:GMW_NV_EraseAll(pGMNV);
Return:n/a
GMW_NV_Count
Returns the number of Name Value pairs within the specified container.
Syntax:GMW_NV_Count( <hgmnv> )
<hgmnv>pointer to a valid name value container
Example:iCount := GMW_NV_Count( pGMNV);
Return:number of NVs within the specified container
GMW_NV_GetNameFromIndex
Finds the name of the NV stored at a specific index within the container. The first item in the container is at index value 1.
Syntax:GMW_NV_GetNameFromIndex( <hgmnv>, <Index> )
<hgmnv>pointer to a valid name value container
<Index>the item number to return
Example:sName := GMW_NV_GetNameFromIndex(pGMNV, 3);
Return:The name stored at <Index> within the container.
GMW_NV_GetValueFromIndex
Finds and returns the value of the NV stored at the specified index within the container. The first item in the container is stored an index value 1.
Syntax:GMW_NV_GetValueFromIndex( <hgmnv>, <Index>, <Default> )
<hgmnv>pointer to a valid name value container
<Index>the item number to return
<Default>the default value to return if the specified item is null.
Example:sValue := GMW_NV_GetValueFromIndex(pGMNV, 3, ‘Customer’);
Return:The value stored at <Index> within the container.
GMW_NV_SetStr
Sets one or more name value pairs
Syntax:GMW_NV_SetStr( <hgmnv>, <NameDlm>, <ValueDlm>, <ValueStr> )
<hgmnv>pointer to a valid name value container.
<NameDlm> the delimiter between the name and its value. *
<ValueDlm> the delimiter between each NV pairs. *
<ValueStr>String containing the name values.
* The delimiters may be the same.
Example:GMW_NV_SetStr(pGMNV,‘=’,‘;’,‘Company=GoldMine;Key1=Cust’);
GMW_NV_SetStr(pGMNV,‘&’,‘&’,‘Company&GoldMine&Key1&Cust’);
Return:n/a
GMW_Execute
All of the business logic methods are accessed through the GMW_Execute function. You must be successfully logged into a GoldMine database for this call to work properly. See page 13 for a list of valid business logic methods
Syntax:GMW_Execute( <Function>, <hgmnv> )
<Function>one of the various business logic functions described below.
<hgmnv>pointer to a Name Value container.
Example:GMW_Execute(“WriteContact”, pGMNV);
Returns:0 – failure
>0 – success
Business Logic Methods
Introduction
This section describes the business logic methods available to the programmer. These methods must be called from either the GMW_Execute function (GM5S32.DLL) or the Execute method of the GM COM object.
WriteContact
Updates or creates a new Contact record. If RecID is passed as null then a new record will be created, otherwise the record will be updated.
Required NVs: None
Optional NVs:Any valid Contact1 or Contact2 field.
Special NVs:EmailE-mail Address profile value
WebSiteWeb Site profile value
NonUSAPhoneInt'l phone format is used if NonUSAPhone = 1, Default is 0
WebUserNameWeb username to assign to this contact. See ContactLogin for more information.
WebPasswordWeb password to assign to this contact. See ContactLogin for more information.
Output NVs:RecIDIf new record created.
AccountNoAccountNo of the record
WriteContactNotes
Updates a Note for a primary contact record. 'Appends' to the top of the note with the proper header information. If both AccountNo and RecID are passed, only AccountNo will be used. The Note header will use the current date/time and default to the logged in username.
Required NVs:NotesThe note text to add
AccountNoAccountNo of the Contact1 record to add notes to. This NV is not required if RecID is used
RecIDRecID of the contact1 record to add the notes to. This NV is not required if AccountNo is used.
Optional NVs:UserIDUserID used in the note header
Output NVs:None
WriteOtherContact
Creates or updates an additional contact record. I f RecID is null then a new record will be created, otherwise the record will be updated. When RecID is passed as null, an AccountNo should be passed otherwise an unlinked record will be created
Required NVs:None
Optional NVs: RecIDRecID of the record to update. If null, a new record will be created.
AccountNoAccountNo of linked Contact1 record.
ContactContact name
TitleTitle
RefReference
DearSalutation
PhonePhone number
FaxFax number
ExtExtension
Address1Address Line 1
Address2Address Line 2
CityCity
StateState
ZipZip code
CountryCountry
NotesNotes
LinkAcctLink Account RecID
Special NVs:EmailEmail address of the additional contact
NonUSAPhoneSet to ‘1’ for a non USA phone format
UseMergeCodesSet to ‘1’ if you wish to set the ‘Use Merge Codes’ option
MergeCodesMerge codes
Output NVs:RecIDReturns the new RecNo or RecID if a new record was created.
WriteDetail
Creates or updates a detail record. If RecID is null then a new record will be created, otherwise the record will be updated. When a RecID is passed as null to create a new record, an AccountNo should be passed otherwise an unlinked record will be created.
Required NVs:DetailThe name of the detail.
Optional NVs: RecIDRecID of the record to update. If null, a new record will be created.
AccountNoAccountNo of linked Contact1 record.
RefValue of the detail being created or updated
NotesNotes for the detail record.
Special NVs:These fields correspond to the extended detail fields.
UField1
UField2
UField3
UField4
UField5
UField6
UField7
UField8
Output NVs:RecIDReturns the new RecNo if a new record was created.
WriteLinkedDoc
Creates or updates a linked document record. If RecID is null then a new record will be created, otherwise the record will be updated. When RecID is passed as null, an AccountNo should be passed otherwise an unlinked record will be created
Required NVs:RecIDRecID of the record to update. If null, a new record will be created.
Optional NVs: AccountNoAccountNo of linked Contact1 record.
FileNameFull path and filename
RefTitle of the document.
NotesNotes
Special NVs:SyncFileIf set to 1, the file will be synched with remote sites.
Output NVs:RecIDReturns the new RecNo if a new Record was created.
WriteReferral
Creates or updates a referral from one contact record to another.
Required NVs:RecIDRecID of the record to update. If null, a new record will be created.
Optional NVs: FromAccNoAccountNo of the ‘From’ referral
ToAccNoAccountNo of the ‘To’ referral.
FromRefReference line for the ‘From’ record.
ToRefReference line for the ‘To’ record.
NotesNotes
AppendNotesAppends Notes with a timestamp. You must pass a valid RecID.
Special NVs: OppSummary12 bit flag of opportunity summary checkboxes in the Referrals properties. This is a sequence of 12 "1"s or "0"s
Output NVs:RecIDReturns the new RecNo if a new Record was created.
WriteSchedule
Creates or updates a scheduled activity record. If RecID is null then a new record will be created, otherwise the record will be updated. When RecID is passed as null, an AccountNo should be passed otherwise an unlinked record will be created
Required NVs:RecIDRecID of the record to update. If null, a new record will be created.
Optional NVs: AccountNoAccountNo of linked Contact1 record.
RecTypeRecType. For a list of valid RecTypes, see the table structures for CAL.
UserIDUser name of activity
ContactContact name
RefReference: line
NotesNotes
ActvCodeActivity code
OnDateDate of activity.
OnTimeTime of activity.
DurationDuration of activity
AlarmIf set to 1, an alarm will set for the specified user. Default is 0.
AlarmDateDate of alarm. Must set Alarm to 1 for this to be used.
AlarmTimeTime of alarm. Must set Alarm to 1 for this to be used.
Special NVs:RSVPIf set to 1, the activity will be sent with an RSVP. Default is 0.
PrivateIf set to 1, the acivity will be marked as private. Default is 0.
NotifyIf set to 1, the scheduled user will receive a notification. Default is 0.
AmountSale amount. Only used when RecType = ‘S’
ProbSaleProbability of sale. Only used when RecType = ‘S’
UnitsSaleNumber of units in sale. Only used when RecType = ‘S’
Output NVs:RecIDReturns the new RecID if a new Record was created.
WriteHistory
Creates/updates a history record, or completes a scheduled activity record. If RecID is null then a new record will be created, otherwise the record will be updated. When RecID is passed as null, an AccountNo should be passed otherwise an unlinked record will be created. To complete a scheduled activity you must pass CalRecID.
Required NVs:RecIDRecID of the record to update. If null, a new record will be created.
Optional NVs:AccountNoAccountNo of linked Contact1 record.
RecTypeRecType. For a list of valid RecTypes, see the table structures for CONTHIST.
UserIDUser name of activity
ContactContact name
RefReference line
NotesNotes
ActvCodeActivity code
ResultCodeResult code
OnDateDate of activity.
OnTimeTime of activity.
DurationDuration of activity
Special NVs:CalRecIDRecID of the scheduled activity (Cal table)
SuccessIf set to 1, the activity was successful. Default is 1.
PrivateIf set to 1, the activity is marked as private. Default is 0.
RSVPIf set to 1, an RSVP is scheduled. Default is 0.
LinkIf Set to 1 indicates that it is linked to the contact record specified in AccountNo
AmountSales amount. Used where RecType = ‘S’