Goldmine5 Advanced Programming Interface

GoldMine Application Programming Interface
Specification and Reference Copyright1999 GoldMine Software Corporation

______________________________________________________________________________________
Authors: Elan Susser Nelson Fernandez Nigel Bassel Kim Novins Product: Product Version: Created: Last Updated: GoldMine 5.0 May 15, 1999 November 9, 1999
GoldMine API Specification and Reference
Page 2
Table of Contents
Table of Contents.......................................................................................................................................2 Introduction...............................................................................................................................................6
BUSINESS LOGIC EXPLAINED..............................................................................................................................6

GM5S32.DLL - Loading and Logging In.................................................................................................8
GMW_L OADBDE..........................................................................................................................................8 GMW_UNLOADBDE......................................................................................................................................8 GMW_SETSQLUSERPASS..............................................................................................................................8

GM5S32.DLL - Name/Value Functions ..................................................................................................9
INTRODUCTION..................................................................................................................................................9 GMW_NV_C REATE.......................................................................................................................................9 GMW_NV_C REATECOPY...............................................................................................................................9 GMW_NV_C OPY..........................................................................................................................................9 GMW_NV_D ELETE.......................................................................................................................................9 GMW_NV_G ETVALUE................................................................................................................................10 GMW_NV_S ETVALUE.................................................................................................................................10 GMW_NV_N AMEEXISTS..............................................................................................................................10 GMW_NV_E RASENAME..............................................................................................................................10 GMW_NV_E RASEALL.................................................................................................................................11 GMW_NV_C OUNT......................................................................................................................................11 GMW_NV_G ETNAMEFROMINDEX................................................................................................................11 GMW_NV_G ETVALUEFROMINDEX...............................................................................................................11 GMW_NV_S ETSTR.....................................................................................................................................12 GMW_E XECUTE...........................................................................................................................................12
Business Logic Methods .........................................................................................................................13
INTRODUCTION................................................................................................................................................13 WRITECONTACT ............................................................................................................................................13 WRITECONTACTNOTES....................................................................................................................................13 WRITEOTHER CONTACT...................................................................................................................................13 WRITEDETAIL................................................................................................................................................14 WRITELINKEDDOC.........................................................................................................................................14 WRITEREFERRAL............................................................................................................................................15 WRITESCHEDULE............................................................................................................................................15 WRITEHISTORY..............................................................................................................................................16 ATTACHTRACK...............................................................................................................................................16 SQLSTREAM.................................................................................................................................................16 READRECORD................................................................................................................................................17 READCONTACT...............................................................................................................................................17 GETCONTACTALERTS......................................................................................................................................17 SETCONTACTALERTS......................................................................................................................................18 GETALLALERTS.............................................................................................................................................18 GETUSERSLIST..............................................................................................................................................18 GETGROUPUSERSLIST....................................................................................................................................19 GETUSERMEMBERSHIPS..................................................................................................................................19 WRITEGROUPUSERSLIST.................................................................................................................................19 ISCONTACTCURTAINED....................................................................................................................................19 SENDGMEMAIL.............................................................................................................................................20 CONTACTLOGIN..............................................................................................................................................20
GM5S32.DLL Security Information Functions ..................................................................................21
INTRODUCTION................................................................................................................................................21 GMW_USERACCESS.....................................................................................................................................21 GMW_C ALACCESS.......................................................................................................................................21 GMW_HISTACCESS......................................................................................................................................22 GMW_GETLICENSEINFO...............................................................................................................................22 GMW_ISUSERGROUPMEMBER.......................................................................................................................22 Copyright 1999 GoldMine Software Corporation
Page 3
GM5S32.DLL DataStream Functions..................................................................................................23
INTRODUCTION................................................................................................................................................23 ADVANTAGES OF USING DATASTREAM...............................................................................................................23 DATASTREAM RECORD SELECTION....................................................................................................................23 GMW_DS_R ANGE.......................................................................................................................................24 GMW_DS_QUERY.......................................................................................................................................24 GMW_DS_FETCH........................................................................................................................................24
GMW_DS_Fetchs Return Packet Explained..........................................................................................................25
GMW_DS_C LOSE........................................................................................................................................25
GM5S32.DLL - Low-Level access using Work Areas...........................................................................27
INTRODUCTION................................................................................................................................................27 OPENING/CLOSING DATABASES..........................................................................................................................28 GMW_DB_OPEN........................................................................................................................................28 GMW_DB_C LOSE.......................................................................................................................................28 GMW_DB_ISSQL......................................................................................................................................28 CREATING AND DELETING RECORDS..................................................................................................................29 GMW_DB_APPEND.....................................................................................................................................29 GMW_DB_DELETE.....................................................................................................................................29 READING/WRITING DATA...............................................................................................................................30 GMW_DB_R EAD........................................................................................................................................30 GMW_DB_R ECNO.....................................................................................................................................30 GMW_DB_R EPLACE....................................................................................................................................30 GMW_DB_UNLOCK....................................................................................................................................30 LIMITING SCOPE OF DATA.................................................................................................................................32 GMW_DB_F ILTER.......................................................................................................................................32 GMW_DB_R ANGE......................................................................................................................................32 SEARCHING FOR DATA......................................................................................................................................33 GMW_DB_S EARCH.....................................................................................................................................33 GMW_DB_S EEK........................................................................................................................................33 GMW_DB_S ETORDER.................................................................................................................................33 NAVIGATING THE DATABASE.............................................................................................................................34 GMW_DB_M OVE.......................................................................................................................................34 GMW_DB_GOTO........................................................................................................................................34 GMW_DB_T OP..........................................................................................................................................35 GMW_DB_S KIP..........................................................................................................................................35 GMW_DB_B OTTOM....................................................................................................................................35 QUICK FUNCTIONS..........................................................................................................................................36 GMW_DB_QUICKSEEK................................................................................................................................36 GMW_DB_QUICKREAD...............................................................................................................................36 GMW_DB_QUICKREPLACE..........................................................................................................................36
GM5S32.DLL - Updating Sync Logs.....................................................................................................38
GMW_UPDATESYNCLOG..............................................................................................................................38 GMW_R EADIMPTLOG..................................................................................................................................38 GMW_NEWRECID.......................................................................................................................................39 GMW_SYNCSTAMP.......................................................................................................................................39

GM5 COM Object ..................................................................................................................................40
INTRODUCTION................................................................................................................................................40 THE OBJECT MODEL.......................................................................................................................................40 THE APPLICATION CLASS..................................................................................................................................41 PROPERTIES.....................................................................................................................................................41

SystemFolder............................................................................................................................................................41 GoldmineFolder........................................................................................................................................................41 CommonFolder.........................................................................................................................................................41 GMUserName...........................................................................................................................................................41 GMPassword............................................................................................................................................................41 SQLUserName.........................................................................................................................................................41 SQLPassword...........................................................................................................................................................41 LicenseInfo...............................................................................................................................................................42
Copyright 1999 GoldMine Software Corporation
Page 4
METHODS...........................................................................................................................................................42
Login.........................................................................................................................................................................42 Logout.......................................................................................................................................................................42 NewContainer...........................................................................................................................................................42 Execute.....................................................................................................................................................................42 NewWorkArea..........................................................................................................................................................42
THE CONTAINER CLASS....................................................................................................................................42 PROPERTIES.....................................................................................................................................................42

Count........................................................................................................................................................................42 _NewEnum...............................................................................................................................................................42 Add...........................................................................................................................................................................42 Remove.....................................................................................................................................................................42
METHODS...........................................................................................................................................................42
Item...........................................................................................................................................................................42 CopyFrom ................................................................................................................................................................43 Copy..........................................................................................................................................................................43
THE NAME/VALUE PAIR CLASS.......................................................................................................................43 PROPERTIES.....................................................................................................................................................43

Count........................................................................................................................................................................43 Name.........................................................................................................................................................................43 _NewEnum...............................................................................................................................................................43
METHODS...........................................................................................................................................................43
Add...........................................................................................................................................................................43 Item...........................................................................................................................................................................43
THE WORKAREA CLASS.................................................................................................................................43 METHODS...........................................................................................................................................................43

Append......................................................................................................................................................................43 Replace.....................................................................................................................................................................43 Delete........................................................................................................................................................................43 Unlock......................................................................................................................................................................43 Read..........................................................................................................................................................................43 Top............................................................................................................................................................................43 Bottom......................................................................................................................................................................44 SetOrder....................................................................................................................................................................44 Seek..........................................................................................................................................................................44 Skip...........................................................................................................................................................................44 Goto..........................................................................................................................................................................44 Move.........................................................................................................................................................................44 Search.......................................................................................................................................................................44 Filter..........................................................................................................................................................................44 Range........................................................................................................................................................................44 RecNo.......................................................................................................................................................................44 IsSQL........................................................................................................................................................................44
THE LICENSEINFO CLASS.................................................................................................................................44 PROPERTIES.....................................................................................................................................................44

Licensee....................................................................................................................................................................44 LicenseNumber.........................................................................................................................................................44 SiteName..................................................................................................................................................................44 LicensedUsers...........................................................................................................................................................44 LicensedSQLUsers...................................................................................................................................................44 LicensedGoldSyncSites............................................................................................................................................45 IsDemo......................................................................................................................................................................45 IsPrimaryLicense......................................................................................................................................................45 IsRemoteLicense......................................................................................................................................................45 IsUSALicense...........................................................................................................................................................45 DLLVersion..............................................................................................................................................................45
Page 5
Code Examples - GM5S32.DLL ............................................................................................................46
C++.............................................................................................................................................................46 VISUAL BASIC................................................................................................................................................54 DELPHI..........................................................................................................................................................62

Code Examples - GM5 COM Object......................................................................................................70
C++.............................................................................................................................................................70 VB/VBS CRIPT..............................................................................................................................................71 JSCRIPT.........................................................................................................................................................72 DELPHI..........................................................................................................................................................76
Page 6
Introduction
GoldMines GM5S32.DLL is a standard dynamic-link library (DLL) that offers developers efficient methods to both access GoldMines databases, and to update GoldMines 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 http://www.goldminesw.com/newsgroups. 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 Copyright 1999 GoldMine Software Corporation
Page 7
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.
Page 8
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: <szSysDir> specifies the location of LICENSE.DBF. <szGoldDir> specifies the location of CAL.DBF. <szCommonDir> specifies the location of CONTACT1.DBF. <szUser> specifies the GoldMine user name (must be UPPERCASE). <szPassword> specifies the users password (must be UPPERCASE). Returns: 1 0 -1 -2 -3 -4 -5 -6 Success BDE already loaded BDE failed to load LICENSE table not found in SysDir Cannot load LICENSE table Invalid username and/or password CAL table not found in GoldDir CONTACT1 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: Returns: GMW_UnloadBDE 1 0 Success Failure
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: 1 0 Success Failure
Page 9
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>, <Dest_hmgmnv> <Source_hgmnv> <Source_hgmnv> )
Pointer to the destination container. Pointer to the source container.
Example: GMW_NV_Copy(pGMNV2, pGMNV); Return: n/a
GMW_NV_Delete
Deletes an NV container and releases its 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. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference Example: GMW_NV_Delete(pGMNV); Return: n/a
Page 10
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> <Name> <Default> pointer to a valid name value container name of the value to return 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> <Name> <Value> pointer to a valid name value container name of the value to set 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> <Name> pointer to a valid name value container 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>) Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference <hgmnv> <Name> pointer to a valid name value container name of the value to set
Page 11
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> <Index> Example: sName := Return: pointer to a valid name value container the item number to return GMW_NV_GetNameFromIndex(pGMNV, 3);
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> <Index> <Default> pointer to a valid name value container the item number to return the default value to return if the specified item is null. Copyright 1999 GoldMine Software Corporation
Page 12
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> <NameDlm> <ValueDlm> <ValueStr> pointer to a valid name value container. the delimiter between the name and its value. * the delimiter between each NV pairs. * 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> <hgmnv> one of the various business logic functions described below. pointer to a Name Value container.
Example: GMW_Execute(WriteContact, pGMNV); Returns: 0 failure >0 success
Page 13
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: Email WebSite NonUSAPhone WebUserName WebPassword E-mail Address profile value Web Site profile value Int'l phone format is used if NonUSAPhone = 1, Default is 0 Web username to assign to this contact. See ContactLogin for more information. Web password to assign to this contact. See ContactLogin for more information. If new record created. AccountNo of the record
Output NVs:
RecID AccountNo
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: Notes AccountNo RecID Optional NVs: UserID Output NVs: None The note text to add AccountNo of the Contact1 record to add notes to. This NV is not required if RecID is used RecID of the contact1 record to add the notes to. This NV is not required if AccountNo is used. UserID used in the note header
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: RecID AccountNo RecID of the record to update. If null, a new record will be created. AccountNo of linked Contact1 record. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference Contact Title Ref Dear Phone Fax Ext Address1 Address2 City State Zip Country Notes LinkAcct Special NVs: Email NonUSAPhone UseMergeCodes MergeCodes RecID Contact name Title Reference Salutation Phone number Fax number Extension Address Line 1 Address Line 2 City State Zip code Country Notes Link Account RecID Email address of the additional contact Set to 1 for a non USA phone format Set to 1 if you wish to set the Use Merge Codes option Merge codes Returns the new RecNo or RecID if a new record was created.
Page 14
Output NVs:
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: Detail Optional NVs: RecID AccountNo Ref Notes Special NVs: The name of the detail. RecID of the record to update. If null, a new record will be created. AccountNo of linked Contact1 record. Value of the detail being created or updated Notes for the detail record.
These fields correspond to the extended detail fields. UField1 UField2 UField3 UField4 UField5 UField6 UField7 UField8 RecID Returns the new RecNo if a new record was created.
Output NVs:
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: RecID Optional NVs: AccountNo RecID of the record to update. If null, a new record will be created. AccountNo of linked Contact1 record. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference FileName Ref Notes Special NVs: Output NVs: SyncFile RecID Full path and filename Title of the document. Notes If set to 1, the file will be synched with remote sites. Returns the new RecNo if a new Record was created.
Page 15
WriteReferral
Creates or updates a referral from one contact record to another. Required NVs: RecID Optional NVs: FromAccNo ToAccNo FromRef ToRef Notes AppendNotes Special NVs: Output NVs: OppSummary RecID RecID of the record to update. If null, a new record will be created. AccountNo of the From referral AccountNo of the To referral. Reference line for the From record. Reference line for the To record. Notes Appends Notes with a timestamp. You must pass a valid RecID. 12 bit flag of opportunity summary checkboxes in the Referrals properties. This is a sequence of 12 "1"s or "0"s Returns 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: RecID Optional NVs: AccountNo RecType RecID of the record to update. If null, a new record will be created.
AccountNo of linked Contact1 record. RecType. For a list of valid RecTypes, see the table structures for CAL. UserID User name of activity Contact Contact name Ref Reference: line Notes Notes ActvCode Activity code OnDate Date of activity. OnTime Time of activity. DurationDuration of activity Alarm If set to 1, an alarm will set for the specified user. Default is 0. AlarmDate Date of alarm. Must set Alarm to 1 for this to be used. AlarmTime Time of alarm. Must set Alarm to 1 for this to be used. RSVP Private Notify Amount ProbSale If set to 1, the activity will be sent with an RSVP. Default is 0. If set to 1, the acivity will be marked as private. Default is 0. If set to 1, the scheduled user will receive a notification. Default is 0. Sale amount. Only used when RecType = S Probability of sale. Only used when RecType = S Copyright 1999 GoldMine Software Corporation
Special NVs:
GoldMine API Specification and Reference UnitsSale Output NVs: RecID Number of units in sale. Only used when RecType = S Returns the new RecID if a new Record was created.
Page 16
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: RecID Optional NVs: AccountNo RecType RecID of the record to update. If null, a new record will be created.
AccountNo of linked Contact1 record. RecType. For a list of valid RecTypes, see the table structures for CONTHIST. UserID User name of activity Contact Contact name Ref Reference line Notes Notes ActvCode Activity code ResultCode Result code OnDate Date of activity. OnTime Time of activity. DurationDuration of activity CalRecID Success Private RSVP Link Amount ProbSale UnitsSale RecID of the scheduled activity (Cal table) If set to 1, the activity was successful. Default is 1. If set to 1, the activity is marked as private. Default is 0. If set to 1, an RSVP is scheduled. Default is 0. If Set to 1 indicates that it is linked to the contact record specified in AccountNo Sales amount. Used where RecType = S Probability of sale. Used where RecType = S Numer of units in sale. Used where RecType = S Returns the new RecNo if a new record was created.
Special NVs:
Output NVs:
RecID
AttachTrack
Attaches an automated process to a contact record Required NVs: AccountNo Track UserID Output NVs: RecID AccountNo of the contact record (Contact1) to attach with.
SQLStream
Executes an SQL and returns the data in a DataStream. See documentation for DataStream for more information. Required NVs: SQL Optional NVs: Filter SQL Statement to execute. xBase filter expression. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference FldDlm RecDlm StartRec GetRecs MaxBufSize Output NVs: Output Field delimiter. Defaults to CR. Record delimiter. Defaults to LF. Starting record. Defaults to 1 Maximum records to return. Defaults to 100 Maximum buffer size. Defaults to 32k Return DataStream.
Page 17
ReadRecord
Reads a record from the specified table based on RecID. When the TableName=Contact1, all Contact2 fields will also be returned. Required NVs: TableName RecID Optional NVs: AddressBlock Special NVs: Output NVs: AccountNo The GoldMine table to read from. The RecID of the Contact1 record to return. When equal to 1, the address will return as one block of text instead of in seperate fields for Address1, Address2, City, State, etc... If TableName=Contact1 this can be used to find the record in place of RecID
All field values for the specified record. Email If TableName=Contact1 the primary email address will return Website If TableName=Contact1 the website profile will return
ReadContact
Reads a contact record from Contact1 and Contact2. Required NVs: RecID Optional NVs: AddressBlock Special NVs: Output NVs: AccountNo The RecID of the Contact1 record to return. When equal to 1, the address will return as one block of text instead of in seperate fields for Address1, Address2, City, State, etc... This can be used to find the record in place of RecID
All Contact1 and Contact2 field values. Email If TableName=Contact1 the primary email address will return Website If TableName=Contact1 the website profile will return
GetContactAlerts
Returns all alerts attached to a contact. Required NVs: One of the following: RecID The RecID of the Contact1 record. You may optionally use AccountNo. AccountNo The AccoutnNo of the Contact1 record. You may optionally use RecID. Output NVs: The function returns the number of contact alerts in the AlertsCount name value. For each alert the functionreturns five fields. Each set of alert fields has the alert number appended to the field name (represented by X below): AlertsCount Number of alerts Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference CodeX DescX NotesX CreatorX SaveHist
Page 18
3 character alert code 80 character description 64k of RTF alert message (optional) The user that assigned the alert A value of "1" indicates that GoldMine will save a history record when the user acknowledges the alert.
SetContactAlerts
Attaches an Alert to the specified contact record. An Alert list is available by executing the GetAllAlerts function Required NVs: RecID AccountNo Code Creator SaveHist Output NVs: None. The GMW_Execute function will return the following values: 0 - Contact not found 1 - Alert is added. 2 - Alert is already attached. The RecID of the Contact1 record to attach this alert to. You may optionally use AccountNo. The AccoutnNo of the Contact1 record. You may optionally use RecID. 3 character Alert Code Creator of the Alert If set to 1 then a history record is generated each time the Alert is acknowledged.
GetAllAlerts
Returns all alerts defined within GoldMine Required NVs: None Output NVs: The function returns the number of contact alerts in the AlertsCount name value. For each alert the function returns five fields. Each set of alert fields has the alert number appended to the field name (represented by X below): AlertsCount CodeX DescX NotesX Number of alerts 3 character alert code 80 character description 64k of RTF alert message (optional)
GetUsersList
Returns a list of all GoldMine users. Required NVs: None Output NVs: UserList UserCount UserGroupsList UserGroupsCount Comma delimited list of all usernames The number of users in the list. Comma delimited list of user groups The number of user groups
The GMW_Execute function will return the same value as UserCount. Copyright 1999 GoldMine Software Corporation
Page 19
GetGroupUsersList
Returns a list of all members of a GoldMine user group. Required NVs: GroupNo The user group number. See the GetUsersList or GetUserMemberships functions for information on how to retrieve a UserGroupsList and their numbers Comma delimited list of all usernames The number of users in the list.
Output NVs:
UserList UserCount
The GMW_Execute function will return the same value as UserCount.
GetUserMemberships
Returns a list of all user group memberships for the specified UserID. Required NVs: UserID Output NVs: UserGroupsList UseGroupsCount The GoldMine user name. Comma delimited list of user group numbers that the user is a member of. The number of users in the list.
The GMW_Execute function will return the same value as UserGroupsCount.
WriteGroupUsersList
Saves the user members to a user group. Required NVs: GroupNo UserList Output NVs: UserCount The user group number. See the GetUsersList or GetUserMemberships functions for information on how to retrieve a UserGroupList and their numbers A comma separated list of users that are members of the specified group. The number of updated user records.
The GMW_Execute function will return the same value as UserCount. Note that this function requires a Master Rights login.
IsContactCurtained
Tests a contact record for curtaining. Required NVs: RecID AccountNo Output NVs: Curtain This is the RecID of the Contact1 record to test. AccountNo can be passed in place of this NV. This is the AccountNo of the Contact1 record to test. RecID can be passed in place of this NV. Value can be one of the following: 0 - not curtained 1 - partial curtaining 2 - fully curtained.
The GMW_Execute function will return TRUE if the record was found. Copyright 1999 GoldMine Software Corporation
Page 20
SendGMEmail
Sends an email to a GoldMine user attached to a specific contact. This function wraps the WriteSchedule function, automatically passing a RecType of 'M' Required NVs: UserID Subject BodyText AccountNo Recipients username Subject line of email Body of message AccountNo of the contact record (Contact1) to attach with.
Optional NVs: Since this function wraps the WriteSchedule API function, all parameters accepted by WriteSchedule can also be passed. Special NVs: Output NVs: Since this function wraps the WriteSchedule API function, all parameters accepted by WriteSchedule can also be passed. RecID Returns the new RecID if a new Record was created.
ContactLogin
Validates a WebUserName/WebPassword assigned to a contact. Required NVs: UserName Password Special NVs: NewUserName NewPassword Contact's Web username. Contact's Web Password. Used to change the existing web username. Must be used with NewPassword and a valid UserName/Password must also be passed for verification. Used to change the existing web password. Must be used with NewUserName and a valid UserName/Password must also be passed for verification. Returns the AccountNo of the contact record. Returns the RecID for the contact record.
Output NVs:
AccountNo RecID
Notes: This function is useful for those wishing to write an extranet solution for GoldMine. To enable GUI access to these features, set ContWebAccess=1 under the [GoldMine] section of your user.ini. You can then select Edit>record Properties>WebAccess to set the web user/pass (max 15 characters each). The web access info is stored in ContSupp with a RecType of "W". Username and password must be unique. This information does NOT sync.
Page 21
GM5S32.DLL Security Information Functions

Introduction
The following section describes the functions available for the programmer to request various security levels for the logged in user. Note: These functions require that you are successfully logged into a GoldMine database using the GMW_LoadBDE function.
GMW_UserAccess
This function allows you to query various rights assigned to the user. Syntax: GMW_UserAccess(<iOption>) The right you wish to query. Possible values are:
Parameters: <iOption>
100 - Master Rights 101 - Access to other user's calendar 102 - Access to other user's history 103 - Access to other user's sales 104 - Access to other user's reports 105 - Access to other user's merge forms 106 - Access to other user's filters 107 - Access to other user's groups 108 - Access to other user's links 111 - Right to create a new record 112 - Right to edit a record 113 - Right to delete a record 114 - Right to change record owner 115 - Right to field views 116 - Right to schedule automated processes 118 - Right to SQL Query 119 - Right to NetUpdate 124 - Right to build groups Returns: 1 0 User has that right. User does not have that right.
GMW_CalAccess
Using this function you can query if the logged in user has the rights to access a specific type of CAL table record. Syntax: GMW_CalAccess(<szRecType>, <szUserID>, <szNumber1>) The RecType you wish to query. The GoldMine user name associated with the record. The value of the Number1 field of the record.
Parameters: <szRecType> <szUserID> <szNumber1> Returns: 1 0
User has the right to access the record User does NOT have the right to access the record. Copyright 1999 GoldMine Software Corporation
Page 22
GMW_HistAccess
Using this function you can query if the user logged in via the DLL has rights to access a CONTHIST record. Syntax: GMW_HistAccess( <szRecType>, <szUserID> ) The RecType of the record The GoldMine username associated with the record.
Parameters: <szRecType> <szUserID> Returns: 1 0
User has the right to access the record. User does not have the right to access the record.
GMW_GetLicenseInfo
This function will return various information about the GoldMine license being used. Syntax: GMW_GetLicenseInfo( <pLicInfo>) Pointer to a client allocated structure defined as follows: Name Licensee LicNo SiteName LicUsers; SQLUsers; GSSites; isDemo; isServerLic; isRemoteLic; isUSALicense; DLLVersion Reserved1 Reserved2 sReserved Description Licensee name Master serial number Undocked site name Licensed users Licensed SQL users License GoldSync sites is demo install? 1=True is primary ('D' or 'E') license? 1=True is remote (U or S) license? 1=True is USA license? 1=True DLL Version number Reserved Reserved Resreved
Parameters: <pLicInfo> Type/Size char / 60 char / 20 char / 20 long integer long integer long integer long integer long integer long integer long integer long integer long integer long integer char / 100 Returns: 1 0 Success Failure
GMW_IsUserGroupMember
Test for group membership. Passing the group number achieves faster performance since the group number need not be resolved from the group name. Syntax: GMW_IsUserGroupMember( <szGroup>, <szUserID> ) The Group name or Group Number The GoldMine username
Parameters: <szGroup> <szUserID> Returns: 1 0
User belongs to the group User does not belong to the group
Page 23
GM5S32.DLL DataStream Functions

Introduction
DataStream returns the data of ordered records from any GoldMine table using the most efficient method available. The caller can specify: Fields and expressions to return Range of records to return Optional filter to apply to the data set
DataStreams SQL query capabilities are very fast on SQL databases. The DataStream method allows for many useful applications. One such group of applications could merge HTML templates with the data returned by GoldMines DataStream to publish the contents of GoldMine data on the Internet. Web pages can be created to display GoldMine data requested by a visitor. Based on the visitor's selections, a company could dynamically present a variety of HTML pages, including dealer addresses in a particular city, financial numbers stored in Contact2, and even seating availability at upcoming conferences. With a fast Internet connection and a strong SQL server, the GoldMine client could respond simultaneously to dozens of requests.
Advantages of using DataStream

GoldMines DataStream is absolutely the fastest way to read data from GoldMine tables! Used correctly, DataStream will return the data faster than most development environments would directly. DataStream offers the following advantages: Efficiency: DataStream issues a single, most efficient SQL query or dBASE seek to retrieve records from the back-end database to the local client. On SQL databases, requests of a few hundred records could be sent from the server to the client with a single network transaction, greatly minimizing network traffic. Speed: All fields and expressions are parsed initially by GMW_DS_Range() and GMW_DS_Query(), then quickly evaluated against each record in GMW_DS_Fetch. Other DDE methods (and development environments) require that each field be parsed and evaluated each time its data is read. This makes a big difference when reading hundreds or thousands of records. Simplicity: Only three function calls are required to read all the data. Using traditional record-by-record querying would require one call for each field of each record (reading 10 fields from 50 records would require 500 function calls). Results: All the work to gather and format the data is done in C++, which is the fastest way to fly. The caller needs only to parse the resulting packet string.
DataStream Record Selection

The following DATASTREAM functions are listed in the order in which they must be called. GMW_DS_Range(): opens a ranged cursor GMW_DS_Query(): opens an SQL query cursor GMW_DS_Fetch(): fetches records GMW_DS_Close(): closes cursor Note that either the GMW_DS_Range() function or the GMW_DS_Query() function must be called first to request the data. These functions return an integer handle which must be passed to the GMW_DS_Fetch() and GMW_DS_Close() functions.
GoldMine API Specification and Reference You must use either GMW_DS_Range() or GMW_DS_Query()you cannot use both. The GMW_DS_Range and GMW_DS_Query functions execute equally fast on SQL databases. GMW_DS_Range executes much faster on dBASE tables than GMW_DS_Query.
Page 24
GMW_DS_Range
GMW_DS_Range returns a range of records based on an index. Syntax: GMW_DS_Range( <szTable>, <szTag>, <szTopLimit>, <szBotLimit>, <szFields>, <szFilter>, <szFDlm>, <szRDlm> ) specifies the table name (such as Contact1) or the table ID. designates the tag that corresponds to the index file. specifies the top limit of the range. (Must conform to the index specifies the bottom limit of the range. (Must conform to the index expression.) The szFields parameter passed to GMW_DS_Range should consist of the field names and dBASE expressions to evaluate against each record in the data set. Each field must be terminated with a semicolon (;). dBASE expressions must be prefixed with an ampersand (&), and terminated with a semicolon. For example: Company; Contact; Phone1; &Substr(Zip,1,5);
Parameters: <szTable> <szTag> <szTopLimit> expression.) <szBotLimit> <szFields>
The following parameters are optional: <szFilter > <szFDlm> <szRDlm> Returns: 1-20 0 designates an optional xBASE filter expression. specifies the field delimiter (default: carriage return). specifies the record delimiter (default: line feed).
Succesful handle Failure.
GMW_DS_Query
Returns a range of records based on an SQL query. This function is very fast on SQL databases. Syntax: Parameters: GMW_DS_Query( <szSQL>, <szFilter>, <szFDlm>, <szRDlm> ) <szSQL> query sends the query for evaluation on the server. The SQL query can join multiple tables and return any number of fields.
The following parameters are optional: <szFilter > <szFDlm> <szRDlm> Return: 1-20 0 -1 designates an optional xBASE filter expression. specifies the field delimiter (default: carriage return). specifies the record delimiter (default: line feed).
Succesful handle Failure. Invalid SQL Query/Timeout
GMW_DS_Fetch
Returns a single packet string containing the requested data from all records processed by the current fetch command, as specified by the nGetRecs parameter. iHandle must be the value returned from GMW_DS_Range( ) or GMW_DS_Query( ). This fetch command can be issued multiple times, with positive and negative values, to scroll down or up the cursor. Copyright 1999 GoldMine Software Corporation
Page 25
DataStream takes about as much time to read three records as to read 30. For best performance, adjust the number of records requested by GMW_DS_Fetch to return 8K32K packets. The calling application must allocate the memory for a large enough packet buffer, and pass that memory buffer to GMW_DS_Fetch. When the number of records cannot be estimated to allocate a packet buffer, GMW_DS_Fetch can be called twice, once to fetch the data and return a buffer size, and a second time to retrieve the data into the buffer. When GMW_DS_Fetch is first called to get the buffer size, the szBuf and iBufSize parameters must both be 0. The nGetRecs parameter must indicate the number of records to fetch. When GMW_DS_Fetch is then called to retrieve the data that has been fetch by the first call, the nGetRecs parameter must be 0. See DataStream C++ Examples (Example 2) on page 50. GMW_DS_Fetchs Return Packet Explained GMW_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 The packet header record consists of two sections:
First byte can be 0, 3, or 4: 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) The number following the dash (0004 in the sample above) indicates the total number of data records contained in the packet.
Syntax:
GMW_DS_Fetch( <iHandle>, <szBuf>, <iBufSize>, <nGetRecs> ) The Datastream handle returned by GMW_DS_Range or Buffer to hold result packet Size of returned <szBuf> Number of records to fetch.
Parameters: <iHandle> GMW_DS_Query <szBuf> <iBufSize> <nGetRecs>
GMW_DS_Close
Page 26
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>) The Datastream handle returned by GMW_DS_Range or
Parameters: <iHandle> GMW_DS_Query Returns: 1 0 Success Failure
Page 27
GM5S32.DLL - Low-Level access using Work Areas

Introduction
GoldMines GM5S32.DLL provides a complete set of functions that allow low-level access to the database tables. Using these functions, you can:
Open/Close particular data files Append/Delete records Reading and writing data Limiting the scope of data Searching for data Navigating through the database
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.
Page 28
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 GoldMines data files for processing by another application. Syntax: GMW_DB_Open( <szTablename> ) The name of the table to open. You may use a full path if required for dBase tables
Parameters: <szTableName> Returns: >0 0
Success A Work Area handle is returned Failure
GMW_DB_Close
Releases a previously opened file when processing is complete. All previously opened files must be properly closedfailure to do so can result in database errors. Syntax: GMW_DB_Close( <lWorkArea> ) The work area handle of the file opened by the GMW_DB_Open
Parameters: <lWorkArea> function. Returns: 1 0
Success Table Closed Failure
GMW_DB_IsSQL
Used to determine if the table is SQL or dBASE. Syntax: GMW_DB_IsSQL( <lWorkArea> ) The work area handle as returned by GMW_DB_Open
Parameters: <lWorkArea> Returns: 1 0
Table is SQL Table is dBase
Page 29
Creating and Deleting Records

The following functions will allow you to add and delete records from the database.
GMW_DB_Append
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( <lWorkArea>, <szRecID> ) The work area handle as returned by GMW_DB_Open A 20-character buffer to accept the new RecID
Parameters: <lWorkArea> <szRecID> Returns:
RecNo of new record (dBase) RecID of new record is returned in <szRecID> (SQL) 0 failure
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> ) The work area handle as returned by GMW_DB_Open
Parameters: <lWorkArea> Returns: 1 0 Success Failure
Page 30
Reading/Writing Data
The following functions allow you to read and write to the database.
GMW_DB_Read
Queries a data file for the value of a field. Syntax: GMW_DB_Read(l <lWorkArea>, <szField>, <szBuf>, <iBufSize> ) The work area handle of the file opened by the GMW_DB_Open Tthe name of the field to read within the table. The buffer in which the function will return the results. Specifies the size of the buffer.
Parameters: <lWorkArea> function. <szField> <szBuf> <iBufSize> Returns: 1 0 Success Failure
GMW_DB_RecNo
Used to determine either current record number (dBASE), or the RecID (SQL). Syntax: GMW_DB_RecNo( <lWorkArea> ) The work area handle of the file opened by the GMW_DB_Open
Parameters: <lWorkArea> 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 GoldMines 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) The work area handle of the file opened by the GMW_DB_Open Specifies the name of the field to be replaced. Specifies the data to be placed in the field. Indicates if the data is to be appended to the existing data. A value of 1 will append the data. A value of 0 will overwrite the data.
Parameters: <lWorkArea> function. <szField> <szData> <iAddTo> Returns: 1 0 Success Failure
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. Syntax: GMW_DB_Unlock( <lWorkArea> ) The work area handle of the file opened by the GMW_DB_Open
Parameters: <lWorkArea> function. Returns: 1 Success
GoldMine API Specification and Reference 0 Failure
Page 31
Page 32
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>) The work area handle as returned by GMW_DB_Open An xBase filter expression.
Parameters: <lWorkArea> <szFilterExpr> Returns: 1 0 Success 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 names 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>) The work area handle as returned by GMW_DB_Open Minimum or lower value of the range. Maximum or upper value of the range. the index name.
Parameters: <lWorkArea> <szMin> <szMax> <szTag> Returns: 1 0 Success Failure
Page 33
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>) The work area handle of the file opened by the GMW_DB_Open Valid dBase expression. For a record to be found this expression must result as TRUE. Buffer where the return value is stored. The return value will be a record number under dBase or a RecID under SQL. You may pass NULL as the third parameter if you do not want the RecNo/RecID.
Parameters: <lWorkArea> function. <szExpr> <szRecID>
Returns:
>0 0
RecNo (dBase) or RecID (SQL) of matching record No match found
GMW_DB_Seek
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) The work area handle of the file opened by the GMW_DB_Open The value you will seek. This value must match the format of the index expression for the currently active index.
Parameters: <lWorkArea> function. <szParam> Returns: 2 1 0
Exact match not found. Cursor placed at closest match Exact match found No match or Error occurred
GMW_DB_SetOrder
Sets the current index on the table. Syntax: GMW_DB_SetOrder( <lWorkArea>, <Tag> ) The work area handle of the file opened by the GMW_DB_Open The name of the index to activate on the table. For a list of index names, see Database Structures in the GoldMine Reference Manuals or help file.
Parameters: <lWorkArea> function. <szTag>
Returns:
1 0
Index successfully activated Error
Page 34
Navigating the database

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.
GMW_DB_Move
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:
Command TOP BOTTOM SKIP GOTO SEEK SETORDER Parameter Not required Not required number of records to skip Record Number/RecID Search key value Index name Preferred Function Equivalents GMW_DB_Top GMW_DB_Bottom GMW_DB_Skip GMW_DB_Goto GMW_DB_Seek GMW_DB_SetOrder
Syntax:
GMW_DB_Move( <lWorkArea>, <szCommand>, <szParam> ) The work area handle of the file opened by the GMW_DB_Open Tthe command to execute. The scope or value for the command.
Parameters: <lWorkArea> function. <szCommand> <szParam> Returns: 4 3 2 1 0
Cursor at beginning of file (BOF) Cursor at end of file (EOF) Exact match not found. Cursor placed at closest match. Exact match found, Cursor moved, or index successfully activated Error
GMW_DB_Goto
Positions to a specific record in the table. Syntax: GMW_DB_Goto( <lWorkArea>, <szRecNo> ) The work area handle of the file opened by the GMW_DB_Open Specifies where the cursor should be placed, and is either RecNo (dBase) or RecID (SQL)
Parameters: <lWorkArea> function. <szRecNo> Returns: 4 3 2 1 0
Cursor at beginning of file (BOF) Cursor at end of file (EOF) Exact match not found. Cursor placed at closest match. Exact match found, Cursor moved, or index successfully activated Error
Page 35
GMW_DB_Top
Positions to the first record in the table. Syntax: GMW_DB_Top( <lWorkArea> ) The work area handle of the file opened by the GMW_DB_Open
Success. Cursor placed at first record Failure
GMW_DB_Skip
Moves the cursor forward or back in the table. Syntax: GMW_DB_Skip( <lWorkArea>, <nSkip> ) The work area handle of the file opened by the GMW_DB_Open Specifies the number records to skip. This value can be positive to move forward in the table or negative to move backwards.
Parameters: <lWorkArea> function. <nSkip> Returns: 4 3 1 0
Cursor at beginning of file (BOF) Cursor at end of file (EOF) Exact match found, Cursor moved, or index successfully activated Error
GMW_DB_Bottom
Positions to the last record in the table. Syntax: GMW_DB_Bottom( <lWorkArea>) The work area handle of the file opened by the GMW_DB_Open
Cursor positioned at the last record in the file Error
Page 36
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: *szRecID) GMW_DB_QuickSeek(char *szTableName, char *szIndex, char *szSeekValue, char The name of the table to be opened. The index to use for the table. The seek expression to use. Returned by the function. This will be the RecID of the record that is
Parameters: <szTableName> <szIndex> <szSeekValue> <szRecID> found. Returns: 1 0 -1 -2
Success Failure Invalid table 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> ) The name of the table to be opened. The RecID of the record to read from. The Field name to return. The value returned by the function. The length of the returned data.
Parameters: <szTableName> <szRecID> <szField> <szValue> <iLen> Returns: 1 0 -1 -2 -3 -4
Success Failure Invalid Table Invalid RecID RecID not found 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: <iAddTo>) GMW_DB_QuickReplace( <szTableName>, <szRecID>, <szField>, <szValue>,
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. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference <szValue> <iAddTo> (0=default). Returns: 1 0 -1 -2 -3 -4 The value to store in the field. Indicates if the value data is to be appended (1) or replaced
Page 37
Success Failure invalid table Invalid RecID RecID Not Found Invalid Fieldname
Page 38
GM5S32.DLL - Updating Sync Logs

GoldMines 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. Syntax: GMW_UpdateSyncLog( <szTable>, <szRecID>, <szField>, <szAction> ) Specifies the table name (such as Contact1) or the Table ID Specifies the RecID of the updated record: the correct RecID must be passed, and the RecID value must be exactly 15 characters long. Specifies the name of the field that has changed. This parameter is only relevant when the Action parameter is U. szField is ignored when szAction is N or D. Should be N when a new record has been appended, D when a record has been deleted, or U when a field in a record has been updated.
Parameters: <szTable> <szRecID> <szField> <szAction>
Returns:
32 16 8 4 2 1 0
New Tlog Entry removed Deleted Tlog Entry Field Tlog entry updated Field Tlog entry created New Tlog entry update New Tlog entry created 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:
Field Name Type Length
Table ID RecID Field ID Action ID
char char char char
10 15 10 1
Syntax:
GMW_ReadImpTLog( <szFile>, <bDelDone>, <szStatus> ) Specifies the import file name. Specifies to delete the import file when the process has completed. 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.
Parameters: <szFile> <bDelDone> <szStatus>
Returns:
>0
Success. Total number of imported Tlog records. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference 0 Failure
Page 39
GMW_NewRecID
GMW_NewRecID returns a new RecID in the szRecIDBuf. GMW_NewRecID can be called without first calling GMW_LoadBDE. Syntax: GMW_NewRecID( <szRecIDBuf>, <szUser> ) Specifies the application allocated buffer to contain the new RecID. The buffer must be at least 16 characters long. Specifies the GoldMine user name.
Parameters: <szRecID> <szUser> Returns:
pointer to szRecIDBuf
GMW_SyncStamp
Converts Sync Stamp to time format and back. Syntax: GMW_SyncStamp( <szStamp>, <szOutBuf> ) When this string parameter is exactly 17 characters long, formatted as Date:Time in the form of CCYYMMDD:HH:MM:SS, the return string in szOutBuf is in TLog timestamp format, exactly seven characters long. When the szStamp parameter is seven characters long formatted as a TLog timestamp, the return string in szOutBuf is formatted as CCYYMMDD:HH:MM:SS. Result of function. An empty return string indicates an error.
Parameters: <szStamp>
<szOutBuf> Returns: 1 0 Success Failure
Page 40
GM5 COM Object

Introduction
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

<<CoClass>> GMApplication <<G et>> SystemFolder() <<Let>> Syste mFolder() <<G et>> Gold mineFolder() <<Let>> Goldmine Folder() <<G et>> GMUserName() <<Let>> GMUserNa me() <<Let>> GMPassword() <<G et>> CommonFolde r() <<Let>> Com monFolder() <<G et>> SQLUserName() <<Let>> SQ LUserName() <<Let>> SQ LPassword() Login() Logout() NewCon tainer() Exec ute() <<G et>> Lice nseIn fo() NewWorkArea () Creates 0..* <<CoClass>> GMWContainer Enumerates N/V Pairs Next() Skip() Reset() Clone() Item() Copy() CopyFrom() Remove() RemoveAll() Add() <<Get>> Count() Creates <<CoClass>> GMWWorkArea Append() Replace() Delete() Unlock() Read() Top() Bottom() SetOrder() Seek() Skip() Goto() Move() Search() Filter() Range() RecNo() IsSQL() <<CoClass>> GMWLicenseInfo <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> <<Get>> Licensee() LicenseNumber() SiteName() LicensedUsers() LicensedSQLUsers() LicensedGoldSyncSites() IsDemo() IsPrimaryLicense() IsRemoteLicense() IsUSALicense() DLLVersion()
has
<<CoClass>> GMNVEnumerator
Contains
<<CoClass>> GMValueEnumerator Next() Skip() Reset() Clone()
Enumerates multipl e values
<<CoClass>> GMNVPair <<Get>> Item() <<Get>> Name() Add() <<Get>> Count()
Figure 1 - The GM COM API 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 Basics For Each syntax.
Page 41
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.
Properties
SystemFolder This is a string property that contains the location of the LICENSE.DBF file. This property maps to the Goldmine API szSysDir parameter in the call to GMW_LoadBDE. GoldmineFolder This is a string property that contains the location of the CAL.DBF file This property maps to the Goldmine API szGoldDir parameter in the call to GMW_LoadBDE. CommonFolder This is a string property that contains either the location of CONTACT1.DBF, or the BDE alias used to access the database. For example, to access SQL Server, an alias of MSSQL_Goldmine might be configured. The string to access this would be MSSQL: MSSQL_GoldMine: dbo:. GMUserName This is a string property that contains the user name to be used to login to GoldMine. All GoldMine user ids are all upper case, so the GMApplication object will convert this property to uppercase when a login occurs. GMPassword This is a string property that contains the password used to login to GoldMine. This is a write only property. SQLUserName This is a string property that contains the SQL Server user id if the underlying database is SQL server. SQLPassword This is a string property that contains the password for the SQL server account used if the database is SQL server. This is a write only property. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference LicenseInfo This is an object containing all the license information for the current installation.
Page 42
Methods
Login This method Loads the BDE (if it has not already been loaded), and logs the user in using the properties as they have been set. Logout This method logs out the logged in user. NewContainer This method creates a new blank Name/Value pair container object, and returns it. Execute This method takes as parameters a Business Logic Function name (eg WriteContact) and a Container object containing the Name/Value pairs for the transaction. It then executes the transaction, and updates the pairs in the container with the results. NewWorkArea Creates a new work area on the specified table.
The Container class.

This class cannot be created directly, but should always be created using the NewContainer method on the GMApplication class. This class supports collection semantics to enable the client access to the Name/Value pairs stored internally. By behaving like a collection, the Container is simple to use for developers used to the Collection paradigm so prevalent in the VBA/VB/VBS world. The general scenario for use of a Container would be to Create the container, Add a number of Name/Value pairs, Execute a transaction, Read the results out of the Container.
Properties
Count This returns the number of Name/Value pairs in the container. _NewEnum This property is hidden from VB clients. It returns an enumerator into the collection. This can be used from VB using the For Each object in Collection syntax. C++ clients will use this interface as an IEnumVARIANT* to do the enumeration. Add Adds a new entry to the collection. The Add method takes a Name and a Value as parameters, and creates a new NVPair, which it returns. The Value is an optional parameter which defaults to an empty string. If an empty string is passed for the value (or if the optional parameter is left out), the pair is created with no value. This is useful for creating multi value pairs. Remove Removes the pair specified by the name.
Methods
Item This method is the default method for the class. It takes a name as a parameter, and returns the name value pair that corresponds to that name. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference CopyFrom Converts this container into a copy of the container passed in. Copy Makes a copy of this container and returns it.
Page 43
The Name/Value Pair Class

This class encapsulates a single name/value pair. Because a Name/Value pair could have multiple values, this class is modeled as a collection of strings, where each string represents a single value. Because the Item method is the default method, and the default parameter is 1, VB clients will see the first entry in the collection as the Value of the object. When a GMNVPair object is created using the Add method on the container the pair has a single value. If the client wishes this to be a multivalue pair, then Successive calls to Add on the GMNVPair class will append values. These values can be enumerated using the standard collection semantics.
Properties
Count Returns the number of values in this N/V Pair. Name The Name of the N/V Pair _NewEnum An enumerator to enumerate the Values. Invisible to VB clients.
Methods
Add Appends a value to the end. Item Returns the specified value. This takes a long as the index parameter. The index is 1 based. This is the default Method, and the default parameter is 1.
The WorkArea Class

This class encapsulates the Work Area functions in the Low Level API. Each method corresponds to an underlying function, and is simply a thin wrapper around the function.
Methods
Append Adds a new record, and returns the new record ID Replace Replaces a specific field at the current position Delete Deletes the current record Unlock Unlocks after an update or an append has locked the work area Read Reads the contents of the specified field at the current position Top Sets the current position to the top of the work area Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference Bottom Sets the current position to the bottom of the work area SetOrder Sets the current index tag on the table Seek Positions to the first record matching the seek value Skip Skips the specified number of records Goto Moves to the specified record Move Positions the record pointer to a particular record in a data file Search Performs a sequential search on a file
Page 44
Filter Limits access to data in a GoldMine database by creating a subset of records based on expression criteria. Range Activates the index in a table, and set a range of values to limit the scope of data that GoldMine will search RecNo Used to determine either current record number position (dBASE), or the record ID (SQL) IsSQL Used to determine if the table is SQL (1) or dBASE (0).
The LicenseInfo Class

This class encapsulates the License Information of the current server. It is accessed from the Application object as a property.
Properties
Licensee The name of the Licensee LicenseNumber The Master Serial Number SiteName The Undocked Site Name LicensedUsers The number of Licensed Users LicensedSQLUsers The number of Licensed SQL Server Users Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference LicensedGoldSyncSites The number of licensed GoldSync Sites IsDemo Is this a demo install IsPrimaryLicense Is this the primary license IsRemoteLicense Is this a remote license IsUSALicense Is this a US License DLLVersion The DLL Version Number
Page 45
Page 46
Code Examples - GM5S32.DLL

C++
The following C++ files have been provided as part of this package: GM5S32.H - C Header file contining all of the GM5S32.DLL function prototypes.
Function prototypes ////////////////////////// // // gm5s32.h // Purpose : GM5S32.DLL interface #ifndef __GM5S32_H #define __GM5S32_H #ifdef __cplusplus extern "C" { #endif // licensing structure passed to GMW_GetLicenseInfo typedef struct { char szLicensee[60]; // licensee name char szLicNo[20]; // master serial number char szSiteName[20]; // undocked site name long iLicUsers; // licensed users long iSQLUsers; // licensed SQL users long iGSSites; // license GoldSync sites long isDemo; // is demo install long isServerLic; // is primary license ('D' or 'E') long isRemoteLic; // is remote license ('U' or 'S') long isUSALicense; // is USA license (1=US,128/32 // bit, 0=nonUS, 32-bit only) long iDLLVersion; // the DLL version (400822) long long long iReserved1; iReserved2; szReserved[100];
} GMW_LicInfo; // DLL intialization functions int _stdcall GMW_LoadBDE( char *szSysDir, char *szGoldDir, char *szCommonDir, char *szUser =0, char *szPass =0 ); int _stdcall GMW_UnloadBDE(); int _stdcall GMW_SetSQLUserPass( char *szUserName, char *szPassword ); Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference int _stdcall GMW_GetLicenseInfo( GMW_LicInfo *pLic ); long _stdcall GMW_IsUserGroupMember( char *szGroup, char *szUserID );
Page 47
// DataStream functions long _stdcall GMW_DS_Range( char *szTable, char *szTag, char *szTopLimit, char *szBotLimit, char *szFields, char *szFilter ="", char *szFDlm ="\r", char *szRDlm ="\n" ); long _stdcall GMW_DS_Query( char *szSQL, char *szFilter ="", char *szFDlm ="\r", char *szRDlm ="\n" ); long _stdcall GMW_DS_Fetch( long iHandle, char *szBuf, int iBufSize, int nGetRecs ); long _stdcall GMW_DS_Close( long iHandle ); // DataStream SQL query & fetch wrapper long _stdcall GMW_SQLStream( char *szSQL, char *szFilter, int nStartRec, int nGetRecs, char *szBuf, int iBufSize, char *szFDlm ="\r", char *szRDlm ="\n" ); // DBF workarea functions long _stdcall GMW_DB_Open( char *szTableName ); long _stdcall GMW_DB_Close( long pArea ); long _stdcall GMW_DB_Append( long pArea, char* szRecID ); long _stdcall GMW_DB_Replace( long pArea, char* szField, char *szData, int iAddTo ); long _stdcall GMW_DB_Delete( long pArea ); long _stdcall GMW_DB_Unlock( long pArea ); long _stdcall GMW_DB_Read( long pArea, char *szField, char *szBuf, int iBufSize ); long _stdcall GMW_DB_Top ( long pArea ); long _stdcall GMW_DB_Bottom( long pArea ); long _stdcall GMW_DB_SetOrder( long pArea, char *szTag ); long _stdcall GMW_DB_Seek( long pArea, char* szParam );
GoldMine API Specification and Reference long _stdcall GMW_DB_Skip( long pArea, int nSkip =1 ); long _stdcall GMW_DB_Goto( long pArea, char *szRecNo );
Page 48
long _stdcall GMW_DB_Move( long pArea, char *szCommand, char* szParam ); long _stdcall GMW_DB_Search( long pArea, char *szExpr, char *szRecID ); long _stdcall GMW_DB_Filter( long pArea, char *szFilterExpr ); long _stdcall GMW_DB_Range( long pArea, char *szMin, char* szMax, char* szTag ); long _stdcall GMW_DB_RecNo( long pArea, char *szRecID long _stdcall GMW_DB_IsSQL( long pArea ); // Quick one-field access functions // (these are slow -- do not use in loops) long _stdcall GMW_DB_QuickSeek( char *szTableName, char *szIndex, char *szSeekValue, char *szRecID ); long _stdcall GMW_DB_QuickRead( char *szTableName, char *szRecID, char *szField, char *szValue, int iLen ); long _stdcall GMW_DB_QuickReplace( char *szTableName, char *szRecID, char *szField, char *szValue, int iAddTo =0 ); // Sync functions int _stdcall GMW_SyncStamp( char *szStamp, char *szOutBuf ); int _stdcall GMW_UpdateSyncLog( char *szTable, char *szRecID, char *szField, char *szAction ); int _stdcall GMW_ReadImpTLog( char *szFile, int bDelWhenDone, char *szStatus ); char* _stdcall GMW_NewRecID( char *pBuff, char *pUser ); );
// misc functions long _stdcall GMW_UserAccess( long iOption );
struct
GMWnv; Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference typedef GMWnv *HGMNV;
Page 49
// GM5S32.DLL business logic functions long _stdcall GMW_Execute( const char *szFunc, HGMNV hgmnv ); // create, release & copy name value containers HGMNV __stdcall GMW_NV_Create(); HGMNV __stdcall GMW_NV_CreateCopy(HGMNV hgmnv); void __stdcall void __stdcall hgmnvSource); GMW_NV_Delete(HGMNV hgmnv); GMW_NV_Copy(HGMNV hgmnvDestination , HGMNV
// get and set value by name const char* __stdcall GMW_NV_GetValue(HGMNV hgmnv, const char* name, const char* defaultValue); void __stdcall GMW_NV_SetValue(HGMNV hgmnv, const char* name, const char* value); // Check if name exists. returns: 0 failed, 1 success long __stdcall GMW_NV_NameExists(HGMNV hgmnv, const char* name); // remove name(s) void __stdcall GMW_NV_EraseName(HGMNV hgmnv, const char* name); void __stdcall GMW_NV_EraseAll(HGMNV hgmnv); // iterate over name-value list (1 based) long __stdcall GMW_NV_Count(HGMNV hgmnv); const char* __stdcall GMW_NV_GetNameFromIndex(HGMNV hgmnv, long index); const char* __stdcall GMW_NV_GetValueFromIndex(HGMNV hgmnv, long index); void __stdcall GMW_NV_SetStr(HGMNV hgmnv, char dlmName, char dlmVal,const char* pszStr);
#ifdef __cplusplus /* close extern "C" { */ } #endif Copyright 1999 GoldMine Software Corporation
Page 50
#endif // __GM5S32_H Logging In The following example accesses the GM5S32.DLL functions using C++. The DLL is dynamically loaded, and its function addresses are retrieved using the GetProcAddress API. // prototypes typedef int (*fnGMW_LoadBDE) ( char *szSysDir, char *szGoldDir, char *szCommonDir, char *szUser ); typedef int (*fnGMW_UnloadBDE) (); void GM5S32_DLL_Test() { // load the GM5S32.DLL HMODULE hLib = LoadLibrary("GM5S32.DLL"); if( hLib ) { // get proc addresses of GM4S32 functions fnGMW_LoadBDE GMW_LoadBDE = (fnGMW_LoadBDE) GetProcAddress( (HINSTANCE) hLib,"GMW_LoadBDE"); fnGMW_UnloadBDE GMW_UnloadBDE = (fnGMW_UnloadBDE) GetProcAddress((HINSTANCE) hLib,"GMW_UnloadBDE"); // initilize the BDE GMW_LoadBDE( "d:\\gm4", "d:\\gm4", "d:\\gm4\\demo", szUser, szPass ); // do whatever.............. // shut down BDE GMW_UnloadBDE(); // unload the DLL FreeLibrary(hLib); } return; } Creating a Contact with Business Logic Enumerating a Name Value Container DataStream The following DataStream example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved. The first example retrieves a relatively small number of records into a fixed size packet buffer, while the second example retries a large number of records using 100-record packet buffers.
GoldMine API Specification and Reference void DataStreamDLL_Example() { long iHandle = 0; long iOK = 0; // Example 1: // Get a small number of records and use a fixed size buffer // // return all contact names at GoldMine Software // char *szSQL1 = "SELECT Contact FROM Contact1 " "WHERE U_COMPANY LIKE 'GOLDMINE SOFTWARE%' " "ORDER BY U_CONTACT"; // send DataStream SQL Query if( (iHandle = GMW_DS_Query( szSQL1 )) > 0 ) { // allocate buffer for 200 contacts at 40 chars per/name long iBufSize = 200*40 +20;
Page 51
GoldMine API Specification and Reference char *szBuf = new char[iBufSize]; // fetch first 200 records into buffer iOK = GMW_DS_Fetch( iHandle, szBuf, iBufSize, 200 ); // do whatever with the data ODS( szBuf ); // make sure to delete the buffer delete [] szBuf; szBuf = NULL; // close the query iOK = GMW_DS_Close( iHandle ); iHandle = 0; } // // Example 2: // Get a large number of records in 100-record buffers // // return all serial numbers beginning with "123...." // char *szSQL2 = "SELECT ContSupRef, Address1, AccountNo FROM ContSupp " "WHERE RECTYPE = 'P' AND U_CONTACT = 'SERIAL NUMBER' " "AND U_ContSupRef Like '123%' " "ORDER BY U_ContSupRef"; // send DataStream SQL Query if( (iHandle = GMW_DS_Query( szSQL2 )) > 0 ) { char *szBuf = NULL; long iBufSize = -1; // read while the first character of result is 0 while( (szBuf == NULL || szBuf[0] == '0') && iBufSize ) { // fetch 100 records and get the buffer size needed // (set the szBuf and iBufSize parameters to 0 to // fetch the data and retrieve the buffer size needed) if( iBufSize = GMW_DS_Fetch( iHandle, 0, 0, 100 ) ) { // delete old buffer and allocate new buffer delete [] szBuf; szBuf = NULL; szBuf = new char[iBufSize]; // read the data (nGetRecs is 0 since data is already read) iOK = GMW_DS_Fetch( iHandle, szBuf, iBufSize, 0 ); // do whatever with the data ODS( szBuf ); } } // make sure to delete the buffer delete [] szBuf; szBuf = NULL; // close the query iOK = GMW_DS_Close( iHandle ); iHandle = 0; } return; }
Page 52
Low-Level Work Area The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved. The example opens up the Contact1 and ContSupp tables to find a particular contacts phone number and primary e-mail address. Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference // void DB_FuncsDLL_Example() { long iOK = 0; int iBufSize = 100; char szBuf[100], szBuf2[100], szAccNo[20+1]; // // Example1: // Find a Jon's phone number and primary email address // char *szName = "JON V. FERRARA"; // open contact1 and contsupp long iC1 = GMW_DB_Open( "Contact1" ); long iCS = GMW_DB_Open( "ContSupp" );
Page 53
// tables opened ok? if( iC1 && iCS ) { // set the Contact1 index to ContName iOK = GMW_DB_SetOrder( iC1, "ContName" ); // seek Jon's name // if( GMW_DB_Seek( iC1, szName ) == 1 ) // seek exact { // read Jon's phone number iOK = GMW_DB_Read( iC1, "Phone1", szBuf, iBufSize ); ODS( szBuf ); // show phone // read Jon's AccountNo iOK = GMW_DB_Read( iC1, "AccountNo", szAccNo, 20+1 ); // // set range to all contact's email records // wsprintf( szBuf, "%sPE-MAIL ADDRESS", szAccNo ); iOK = GMW_DB_Range( iCS, szBuf, szBuf, "ContSupp" ); // loop through all email records // and find primary one while( iOK && (iOK = GMW_DB_Skip( iCS, 1 )) ) { // read email address from the ContSupRef field // and status from Zip iOK=GMW_DB_Read( iCS,"ContSupRef",szBuf,iBufSize ); iOK=GMW_DB_Read( iCS,"Zip", szBuf2, iBufSize ); // show email address ODS( szBuf ); // primary email has a '1' in the second // char of Zip
GoldMine API Specification and Reference if( szBuf2[1] == '1' ) break; // found primary address!
Page 54
} } // close the tables iOK = GMW_DB_Close( iC1 ); iOK = GMW_DB_Close( iCS ); } return; }
iC1 = 0; iCS = 0;
Visual Basic
In addition to the code examples below, the following VB files have been provided as part of this package: VBExamples.ZIP - This archive contains three example projects and a global module (GMDeclare.BAS) containing all of the GM5S32.DLL function declarations. Function prototypes ' Structure for License function Public Type GMLicInfo Licensee As String * 60 LicNo As String * 20 SiteName As String * 20 LicUsers As Long SQLUsers As Long GSSites As Long IsDemo As Long IsServerLic As Long IsRemoteLic As Long ISUSALic As Long iReserved1 As Long iReserved2 As Long iReserved3 As Long sReserved As String * 100 End Type ' LoadBDE Functions Public Declare Function GMW_LoadBDE Lib "GM5S32.dll" (ByVal sSysDir As String, ByVal sGoldDir As String, ByVal sCommonDir As String, ByVal sUser As String, ByVal sPassword As String) As Long Public Declare Function GMW_UnloadBDE Lib "GM5S32.dll" () As Long Public Declare Function GMW_SetSQLUserPass Lib "GM5S32.dll" (ByVal sUserName As String, ByVal sPassword As String) As Long ' Business logic functions ' Name-Value parameter passing to business logic function GMW_Execute( Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference Public Declare Function GMW_Execute Lib "GM5S32.dll" (ByVal szFunc As String, ByVal GMPtr As Any) As Long
Page 55
Public Declare Function GMW_NV_Create Lib "GM5S32.dll" () As Long Public Declare Function GMW_NV_CreateCopy Lib "GM5S32.dll" (ByVal hgmnv As Long) As Long Public Declare Function GMW_NV_Delete Lib "GM5S32.dll" (ByVal hgmnv As Long) As Long Public Declare Function GMW_NV_Copy Lib "GM5S32.dll" (ByVal hgmnvDestination As Long, ByVal hgmnvSource As Long) As Long Public Declare Function GMW_GetLicenseInfo Lib "GM5S32.dll" (ByRef LicInfo As Any) As Long Public Declare Function GMW_NV_GetValue Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal name As String, ByVal DefaultValue As String) As Long Public Declare Function GMW_NV_SetValue Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal name As String, ByVal Value As String) As Long Public Declare Function GMW_NV_NameExists Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal name As String) As Long Public Declare Function GMW_NV_EraseName Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal name As String) As Long Public Declare Function GMW_NV_EraseAll Lib "GM5S32.dll" (ByVal hgmnv As Long) As Long Public Declare Function GMW_NV_Count Lib "GM5S32.dll" (ByVal hgmnv As Long) As Long Public Declare Function GMW_NV_GetNameFromIndex Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal index As Long) As Long Public Declare Function GMW_NV_GetValueFromIndex Lib "GM5S32.dll" (ByVal hgmnv As Long, ByVal index As Long) As Long ' Low-Level DB funcs Public Declare Function GMW_DB_Open Lib "GM5S32.dll" (ByVal sTableName As String) As Long Public Declare Function GMW_DB_Close Lib "GM5S32.dll" (ByVal lArea As Long) As Long Copyright 1999 GoldMine Software Corporation
Page 56
Public Declare Function GMW_DB_Append Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sRecID As String) As Long Public Declare Function GMW_DB_Replace Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sField As String, ByVal sData As String, ByVal iAddTo As Long) As Long Public Declare Function GMW_DB_Delete Lib "GM5S32.dll" (ByVal lArea As Long) As Long Public Declare Function GMW_DB_UnLock Lib "GM5S32.dll" (ByVal lArea As Long) As Long Public Declare Function GMW_DB_Read Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sField As String, ByVal sbuf As String, ByVal lbufsize As Long) As Long Public Declare Function GMW_DB_Top Lib "GM5S32.dll" (ByVal lArea As Long) As Long Public Declare Function GMW_DB_Bottom Lib "GM5S32.dll" (ByVal lArea As Long) As Long Public Declare Function GMW_DB_SetOrder Lib "GM5S32.dll" (ByVal lArea As Long, ByVal Stag As String) As Long Public Declare Function GMW_DB_Seek Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sParam As String) As Long Public Declare Function GMW_DB_Skip Lib "GM5S32.dll" (ByVal lArea As Long, ByVal lSkip As Long) As Long Public Declare Function GMW_DB_Goto Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sRecNo As String) As Long Public Declare As Long, ByVal Public Declare lArea As Long, Long Function GMW_DB_Move Lib "GM5S32.dll" (ByVal lArea sCommand As String, ByVal sParam As String) As Long Function GMW_DB_Search Lib "GM5S32.dll" (ByVal ByVal sExpr As String, ByVal sRecID As String) As
Public Declare Function GMW_DB_Filter Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sFilterExpr As String) As Long Public Declare Function GMW_DB_Range Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sMin As String, ByVal sMax As String, ByVal Stag As String) As Long Public Declare Function GMW_DB_RecNo Lib "GM5S32.dll" (ByVal lArea As Long, ByVal sRecID As String) As Long Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference Public Declare Function GMW_DB_IsSQL Lib "GM5S32.dll" (ByVal lArea As Long) As Long ' Sync funcs Public Declare Function GMW_NewRecID Lib "GM5S32.dll" (ByVal szRecid As String, ByVal szUser As String) As String
Page 57
Public Declare Function GMW_UpdateSyncLog Lib "GM5S32.dll" (ByVal sTable As String, ByVal sRecID As String, ByVal sField As String, byvalsAction As String) As Long Public Declare Function GMW_ReadImpTLog Lib "GM5S32.dll" (ByVal sFile As String, lDelWhenDone As Long, sStatus As String) As Long Public Declare Function GMW_SyncStamp Lib "GM5S32.dll" (sStamp As String, sOutBuf As String) As Long ' Datastream funcs Public Declare Function GMW_DS_Query Lib "GM5S32.dll" (ByVal sSQL As String, ByVal sFilter As String, ByVal sFDlm As String, ByVal sRDlm As String) As Long Public Declare Function GMW_DS_Range Lib "GM5S32.dll" (ByVal sTable As String, ByVal Stag As String, ByVal sTopLimit As String, ByVal sBotLimit As String, ByVal sFields As String, ByVal sFilter As String, ByVal sFDlm As String, ByVal sRDlm As String) As Long Public Declare Function GMW_DS_Fetch Lib "GM5S32.dll" (ByVal iHandle As Long, ByVal sbuf As String, ByVal iBufSize As Long, ByVal iGetRecs As Long) As Long Public Declare Function GMW_DS_Close Lib "GM5S32.dll" (ByVal iHandle As Long) As Long Public Declare Function GMW_IsUserGroupMember Lib "GM5S32.DLL" (ByVal szGroup As String, ByVal szUserID As String) As Long
' Misc WinAPI funcs used by VB with the GM5S32.DLL Public Declare Sub CopyMemory Lib "kernel32" Alias "RtlMoveMemory" (Destination As Any, Source As Any, ByVal Length As Long) Public Declare Function lstrlen Lib "kernel32" Alias "lstrlenA" (ByVal lpString As String) As Long ' ' ' NOTE! All GM5S32 Funcs that return a string pointer should be converted using ' the following function. For example: ' Copyright 1999 GoldMine Software Corporation
Page 58
' sResult = PtrToStr(GMW_NV_GetValue(lGMPtr, "OutPut", "")) ' Public Function PtrToStr(ByVal lpsz As Long) As String Dim strOut As String Dim lngStrLen As Long lngStrLen = lstrlen(ByVal lpsz) ' If returning larger packets, you may have to ' increase this value lngStrLen = 64000 If (lngStrLen > 0) Then strOut = String$(lngStrLen, vbNullChar) Call CopyMemory(ByVal strOut, ByVal lpsz, lngStrLen) lngStrLen = lstrlen(strOut) PtrToStr = Left(strOut, lngStrLen) Else PtrToStr = "" End If strOut = "" End Function Logging In Dim lResult As Long lResult = GMW_LoadBDE("c:\gm5\", "c:\gm5\gmbase\", "c:\gm5\demo\", "MASTER", "ACCESS") If lResult <> 1 Then MsgBox "Unable to Load BDE" Creating a Contact The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved. Dim lGMPtr As Long, _ sGMnvm As String, _ sGMvle As String, _ lResult As Long '//Create NV and pass pointer value to a variable lGMPtr = GMW_NV_Create() '//Fill Variables with Nulls sGMnvm = String$(100, Chr(0)) sGMvle = String$(100, Chr(0)) Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference '//Set Name Values lResult = GMW_NV_SetValue(lGMPtr, lResult = GMW_NV_SetValue(lGMPtr, lResult = GMW_NV_SetValue(lGMPtr, lResult = GMW_NV_SetValue(lGMPtr, lResult = GMW_NV_SetValue(lGMPtr,
Page 59
"Company", "GoldMine Software") "Contact", "Calvin Luttrell") "Phone1", "(310)555-1212") "Email", "calvin@gm.com") "WebSite", "www.gm.com")
'//Execute Buisness Logic Function lResult = GMW_Execute("WriteContact", lGMPtr) Enumerating a Container The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved '//Get count from NV for loop lCount = GMW_NV_Count(lGMPtr) For i = 1 To lCount '//Get name from NV txttemp1.Text = GMW_NV_GetNameFromIndex(lGMPtr, i) '//Get value from NV txttemp2.Text = GMW_NV_GetValueFromIndex(lGMPtr, i) '//Display in list box sResult = txttemp1.Text + "=" + txttemp2.Text List1.AddItem sResult Next DataStream The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved sFilter = " '" + UCase$(txtMatchValue.Text) + "' $ UPPER(ContSupRef)" iHandle = GMW_DS_Range("ContSupp", "ContSPFD", "PE-MAIL ADDRESS", "PE-MAIL ADDRESS~", "ContSupRef;", sFilter, " ", Chr(13) + Chr(10)) If iHandle > 0 Then Do 'The initial fetch will tell us how much to allocate the 'buffer for a 50 record packet sBuf = String$(1, 0) iBufSize = GMW_DS_Fetch(iHandle, sBuf, 0, 50) 'Now, we actually grab some data sBuf = String$(iBufSize + 1, 0) 'NOTE: You must initialize
Page 60
'strings to the 'proper size before using. lRes = GMW_DS_Fetch(iHandle, sBuf, iBufSize, 0) 'Check if more data is available or not If Left(sBuf, 1) = "3" Then bEOF = True Else bEOF = False End If 'Add the results to a multi-line text box for display txtResults.Text = txtResults.Text + Mid(sBuf, 14, iBufSize) Loop until bEOF Else MsgBox ("Error: Invalid DS Handle!") End If Low-Level WorkArea The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved. The example opens up the CONTACT1 and CONTSUPP tables to find a particular contacts phone number and primary e-mail address. The Contact name is stored in a VB Text box. Dim lC1WA As Long Dim lC2WA As Long Dim lCSWA As Long Dim lRes As Long Dim sAccNo As String Dim sBuf1 As String Dim sBuf2 As String 'Initialization lblEmail.Caption = "" lblPrevresult.Caption = "" lblCompany.Caption = "" lblPhone.Caption = "" sAccNo = String$(21, 0) 'Open data files lC1WA = GMW_DB_Open("Contact1") lC2WA = GMW_DB_Open("Contact2") lCSWA = GMW_DB_Open("ContSupp") 'If all files are opened OK... If (lC1WA And lC2WA And lCSWA) Then 'Set the index order Res = GMW_DB_SetOrder(lC1WA, "ContName") 'Perform the seek If GMW_DB_Seek(lC1WA, UCase$(txtContactName.Text)) = 1 Then 'Get the AccountNo for the matching record lRes = GMW_DB_Read(lC1WA, "AccountNo", sAccNo, 21) ' Get the Phone and Company fields from Contact1 'Pre-allocate string buffer sBuf1 = String$(100, 0) sBuf2 = String$(100, 0) Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference 'Get the field data lRes = GMW_DB_Read(lC1WA, "Company", sBuf2, 100) lRes = GMW_DB_Read(lC1WA, "Phone1", sBuf1, 100) 'Update the display labels lblCompany.Caption = Trim(sBuf2) lblPhone.Caption = Trim(sBuf1)
Page 61
' Get the Previous result field from Contact2 'Set the index order lRes = GMW_DB_SetOrder(lC2WA, "Contact2") 'Perform the seek If GMW_DB_Seek(lC2WA, sAccNo) = 1 Then 'Pre-allocate string buffer sBuf1 = String$(100, 0) 'Get the field data lRes = GMW_DB_Read(lC2WA, "PREVRESULT", sBuf1, 100) 'Display the field data lblPrevresult.Caption = sBuf1 End If ' Get the e-mail address from ContSupp 'Pre-allocate string buffer sBuf1 = String$(100, 0) 'Initialize the range limits sBuf1 = Left(sAccNo + Space$(20), 20) + "PE-MAIL ADDRESS" 'Set the range and go top lRes = GMW_DB_Range(lCSWA, sBuf1, sBuf1, "ContSupp") lRes = GMW_DB_Top(lCSWA) 'Loop until a primary e-mail is found Do While (lRes = 1) 'Pre-allocate string buffers sBuf1 = String$(100, 0) sBuf2 = String$(100, 0) 'Get the field data lRes = GMW_DB_Read(lCSWA, "ContSupRef", sBuf1, 100) lRes = GMW_DB_Read(lCSWA, "Zip", sBuf2, 100) 'Check if primary e-mail address If Mid$(sBuf2, 2, 1) = "1" Then 'Update the label lblEmail.Caption = Trim(sBuf1) Exit Do 'all done End If 'Skip to next record lRes = GMW_DB_Skip(lCSWA, 1) Loop Else 'Notify user of problem MsgBox ("Could not locate the specified contact.") End If Else 'All tables could not be opened. MsgBox ("Could not open the data files.") Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference 'Exit program Unload Me End If
Page 62
Delphi
In addition to the code examples below, the following Delphi files have been provided as part of this package: DelphiExamples.ZIP - This archive contains two example projects and a unit (GM5S32.PAS) containing all of the GM5S32.DLL function declarations. Please note that this document only covers the Business Logic functions. More documentation can be found in the GoldMine m anuals. Function prototypes Type TGMW_LicInfo = record Licensee: array [0..59] LicNo: array [0..19] of SiteName: array [0..19] LicUsers, SQLUsers, GSSites, IsDemo, IsServerLic, IsRemoteLic, IsUSALic, DLLVersion, Reserved1, Reserved2:longint; Reserved: array [0..99] end; Type hgmnv = pointer; // GM5S32.DLL intialization functions function GMW_LoadBDE(sSysDir, sGoldDir, sCommonDir, sUser, sPassword: Pchar): integer; stdcall; external 'GM5S32.DLL'; function GMW_UnloadBDE: integer; stdcall; external 'GM5S32.DLL';
of char; char; of char;
of char;
function GMW_SetSQLUserPass(sUserName, sPassword: PChar):integer; stdcall; external 'GM5S32.DLL'; function GMW_GetLicenseInfo( pGMW_LicInfo: pointer):integer; stdcall; external 'GM5S32.DLL'; // GM5S32.DLL Sync functions Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference function GMW_UpdateSyncLog(sTable, sRecID, sField, cAction: PChar):integer; stdcall; external 'GM5S32.DLL';
Page 63
function GMW_ReadImpTLog(sFile: PChar; bDelWhenDone: integer; sStatus: PChar): integer; stdcall; external 'GM5S32.DLL'; procedure GMW_NewRecID(sRecID, sUser: PChar); stdcall; external 'GM5S32.DLL'; procedure GMW_SyncStamp(sStamp, sOutBuf: PChar); stdcall; external 'GM5S32.DLL'; // GM5S32.DLL DataStream functions function GMW_DS_Range(sTable, sTag, sTopLimit, sBotLimit, sFields, sFilter, sFDlm, sRDlm: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DS_Query(sSQL, sFilter, sFDlm, sRDlm: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DS_Fetch(iHandle: longint; sBuf: Pchar; iBufSize, iGetRecs: integer): longint; stdcall; external 'GM5S32.DLL'; function GMW_DS_Close(iHandle: longint):longint; stdcall; external 'GM5S32.DLL'; // GM5S32.DLL DBF workarea functions function GMW_DB_Open(sTable: Pchar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Close(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Append(lArea: Longint; sRecID: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Replace(lArea: Longint; sField, sData: PChar; iAddTo: integer): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Delete(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Unlock(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Read(lArea: Longint; sField, sBuf: PChar; iBufSize: integer): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Top(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; Copyright 1999 GoldMine Software Corporation
Page 64
function GMW_DB_Bottom(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_SetOrder(lArea: Longint; sTag: Pchar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Seek(lArea: Longint; sParam: PChar): longint; stdcall; external'GM5S32.DLL'; function GMW_DB_Skip(lArea: Longint; iSkip: integer): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Goto(lArea: Longint; sRecNo: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Move(lArea: Longint; sCommand, sParam: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Search(lArea: Longint; sExpr, sRecID: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Filter(lArea: Longint; sFilterExpr: Pchar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_Range(lArea: Longint; sMin, sMax, sTag: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_RecNo(lArea: Longint; sRecID: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_IsSQL(lArea: Longint): longint; stdcall; external 'GM5S32.DLL'; // GM5S32.DLL Quick one-field access functions function GMW_DB_QuickSeek(sTableName, sIndex, sSeekValue, sRecID: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_QuickRead(sTableName, sRecID, sField, sValue: Pchar; iLen: integer): longint; stdcall; external 'GM5S32.DLL'; function GMW_DB_QuickReplace(sTableName, sRecID, sField, sValue: Pchar; iAddTo: integer): longint; stdcall; external 'GM5S32.DLL'; // GM5S32.DLL Misc functions function GMW_IsUserGroupMember( szGroup, szUserID: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_UserAccess(Option: longint): longint; stdcall; external 'GM5S32.DLL'; Copyright 1999 GoldMine Software Corporation
Page 65
function GMW_CalAccess(RecType, UserID, Number1: PChar): longint; stdcall; external 'GM5S32.DLL'; function GMW_HistAccess(RecType, UserID: PChar): longint; stdcall; external 'GM5S32.DLL'; // GM5S32.DLL business logic functions function GMW_Execute(Func: Pchar; PGMNV: hgmnv ): longint; stdcall; external 'GM5S32.DLL'; // create, release & copy name value containers function GMW_NV_Create: pointer; stdcall; external 'GM5S32.DLL'; function GMW_NV_CreateCopy(PGMNV: hgmnv): pointer; stdcall; external 'GM5S32.DLL'; procedure GMW_NV_Delete(PGMNV: hgmnv); stdcall; external 'GM5S32.DLL'; procedure GMW_NV_Copy(Destination, Source: hgmnv); stdcall; external 'GM5S32.DLL'; // get and set value by name function GMW_NV_GetValue(PGMNV: hgmnv; Name, DefaultValue: PChar): PChar; stdcall; external 'GM5S32.DLL'; procedure GMW_NV_SetValue(PGMNV: hgmnv; Name, Value: PChar); stdcall; external 'GM5S32.DLL'; // Check if name exists. returns: 0 failed, 1 success function GMW_NV_NameExists(PGMNV: hgmnv; Name: PChar): longint; stdcall;external 'GM5S32.DLL'; // remove name(s) procedure GMW_NV_EraseName(PGMNV: hgmnv; Name: PChar); stdcall; external 'GM5S32.DLL'; procedure GMW_NV_EraseAll(PGMNV: hgmnv); stdcall; external 'GM5S32.DLL'; // iterate over name-value list (1 based) function GMW_NV_Count(PGMNV: hgmnv): longint; stdcall; external 'GM5S32.DLL'; function GMW_NV_GetNameFromIndex(PGMNV: hgmnv; Index: longint): PChar; stdcall; external 'GM5S32.DLL';
Page 66
function GMW_NV_GetValueFromIndex(PGMNV: hgmnv; Index: longint): PChar; stdcall; external 'GM5S32.DLL'; // Set a series of values in one shot procedure GMW_NV_SetStr(PGMNV: hgmnv; dlmName, dlmVal: Char; StringVal: PChar); stdcall; external 'GM5S32.DLL'; Logging In The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved // Login to GM5 iRet := GMW_LoadBDE('C:\GM5', 'C:\GM5\GMBASE', 'C:\GM5\DEMO', 'NELSON' , ''); if iRet < 1 then ShowMessage('LoadBDE Failed. Err: '+IntToStr(iRet)); Creating a Contact The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved // Create a new NV container pGMNV := GMW_NV_Create; // Test if NV is valid If pGMNV <> nil then begin // Load the NVs to create the contact record GMW_NV_SetValue(pGMNV, 'Company', 'GoldMine Software'); GMW_NV_SetValue(pGMNV, 'Contact', 'Nelson Fernandez'); GMW_NV_SetValue(pGMNV, 'Phone1', '(310)555-1212'); GMW_NV_SetValue(pGMNV, 'Email', 'nelson@gm.com'); GMW_NV_SetValue(pGMNV, 'WebSite', 'www.gm.com'); // Exec the WriteContact function if GMW_Execute('WriteContact', pGMNV) > 0 then begin ShowMessage('Contact record was created. AccountNO=' + GMW_NV_GetValue(pGMNV, 'AccountNo', '') ); //Remove the pGMNV GMW_NV_Delete(pGMNV); end else // Display error ShowMessage('WriteContact Failed.');; end else Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference // Display Error ShowMessage('Could not create NV container.');
Page 67
Enumerating a Container The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved // Determine the number of returned values lCount := GMW_NV_Count(pGMNV); // If > 0 then iterate through the list If lCount > 0 then For i := 1 to lCount do // Add to the results memo control mResults.Text := mResults.Text + GMW_NV_GetNameFromIndex(pGMNV,i)+'='+ GMW_NV_GetValueFromIndex(pGMNV, i)+#13+#10;
DataStream The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved iHandle:=GMW_DS_RANGE('Contsupp', 'Contspfd', 'PE-MAIL ADDRESS', 'PE-MAIL ADDRESS~', 'ContSupRef;', PChar('''' + UpperCase(cebMatchValue.Text)+''' $ Upper(ContSupRef)'), '', #13+#10); If iHandle > 0 then Begin bDone :=FALSE Repeat //Get Buffer Size iBufSize:=GMW_DS_Fetch(iHandle,NIL, 0, FETCH_SIZE); //Allocate Buffer Memory pcBuffer:=AllocMem(iBufSize); //Fetch Data lres:=GMW_DS_Fetch(iHandle, pcBuffer, iBufSize, 0); if lres>0 then //Fetch Successfully? begin //Get results sResults:=sResults + Copy(StrPas(pcBuffer),12,iBufSize-12); FreeMem(pcBuffer, iBufSize); //Free buffer memory
GoldMine API Specification and Reference if Copy(sHeader,1,1)<>'3' bDone:=TRUE else bDone:=FALSE; end; until bDone lres:=GMW_DS_Close(iHandle); end; then
Page 68 //End of File in GM?
Low-Level Work Area The following example assumes that GM5S32.DLL has already been loaded, and the function addresses have been retrieved. The example opens up the CONTACT1 and CONTSUPP tables to find a particular contacts phone number and primary e-mail address. Var lRes, lC1WA, lC2WA, lCSWA: longint; aAccNo: array[0..20] of char; aValue1: array[0..100] of char; aValue2: array[0..100] of char; begin // Open files lC1WA := GMW_DB_Open('Contact1'); lC2WA := GMW_DB_Open('Contact2'); lCSWA := GMW_DB_Open('Contsupp'); // Make sure all files were opened OK if (lC1WA>0) and (lC2WA>0) and (lCSWA>0) then begin // Set the index order lRes := GMW_DB_SetOrder(lC1WA, 'ContName'); // Perform the seek If GMW_DB_Seek(lC1WA, PChar(UpperCase(cebSearchValue.Text)) )=1 then begin // Read the AccountNo GMW_DB_Read(lC1WA, 'AccountNo', aAccNo, 21); // Get the field data lRes := GMW_DB_Read(lC1WA, 'Company', aValue1, 100); //Display the results clCompany.Caption := StrPas(aValue1); //Init the range limit string StrPCopy(aValue1, Copy(StrPas(aAccNo),1,20)+'PE-MAIL ADDRESS'); // Set the range and go to Top lRes := GMW_DB_Range(lCSWA, aValue1, aValue1, 'Contsupp'); lRes := GMW_DB_Top(lCSWA); // Loop through records.. While lRes = 1 do begin //Read the field data... lRes := GMW_DB_Read(lCSWA, 'ContSupRef', aValue1, 100); lRes := GMW_DB_Read(lCSWA, 'ZIP', aValue2, 100);
Page 69
end;
if aValue2[1] = '1' then begin clEmail.Caption := aValue1; Exit; end; lRes := GMW_DB_Skip(lCSWA, 1); end; end else // Notify user of problem ShowMessage('Could not locate the specified contact!'); end else // Notify user of problem ShowMEssage('Could not open all data files'); GMW_UnLoadBDE;
Page 70
Code Examples - GM5 COM Object

In addition to the code examples below, the following files have been provided as part of this package: GM5COM.ZIP - This archive contains two example projects - one in VBScript and one in JScript - and the GMCOMAPI.DLL.
C++
Logging In IGMApplicationPtr spGoldmine; HRX hResult = spGoldmine.CreateInstance (__uuidof (GMApplication)); spGoldmine->PutCommonFolder ("MSSQL: MSSQL_GoldMine: dbo:"); spGoldmine->PutSystemFolder ("c:\\\\Program Files\\Goldmine"); spGoldmine->PutGoldmineFolder ("c:\\\\Program Files\\Goldmine\\GMBase"); spGoldmine->PutGMUserName("NigelB"); spGoldmine->PutSQLUserName("sa"); spGoldmine->Login(); // Create a new container IGMWContainerPtr spContainer = spGoldmine->NewContainer (); Creating a Contact // Add a Contact IGMWContainerPtr spContact = spGoldmine->NewContainer (); spContact->Add spContact->Add spContact->Add spContact->Add spContact->Add spContact->Add ("Contact", "Nelson"); ("Company", "GoldMine"); ("Phone1", "(310)454-6801"); ("Email", "nelson@gm.com"); ("WebSite", "www.gm.com"); ("Comments", "this is a contact2 field");
spGoldmine->Execute ("WriteContact", spContact); EnumerateContainer (spContact); // get RecID and AccountNo of new record IGMNVPairPtr spRecId = spContact->Item ("RecID"); _bstr_t strRecId; if (spRecId != NULL) { strRecId = spRecId->Item(1); Copyright 1999 GoldMine Software Corporation
Page 71
} IGMNVPairPtr spAccountNumber = spContact->Item ("AccountNo"); _bstr_t strAccountNo; if (spAccountNumber != NULL) { strAccountNo = spAccountNumber->Item (1); } Enumerating a Container void EnumerateContainer (IGMWContainerPtr spContainer) { std::cout << "Enumerating ......\r\n---------------------" << std::endl; IEnumVARIANTPtr spEnumerator = spContainer->Get_NewEnum (); _variant_t vaPair; while (spEnumerator->Next (1, &vaPair, NULL) == S_OK) { IGMNVPairPtr spPair = vaPair; vaPair.Clear (); _bstr_t strName = spPair->GetName (); std::cout << "Name : " << (LPCSTR)strName << " Value(s) :"; IEnumVARIANTPtr spValueEnumerator = spPair->Get_NewEnum (); _variant_t vaValue; while (spValueEnumerator->Next (1, &vaValue, NULL) == S_OK) { _bstr_t strValue = vaValue; std::cout << " [" << (LPCSTR)strValue << "]"; vaValue.Clear (); } std::cout << std::endl; } }
VB/VBScript
Logging In ' Assume some error handling function called HandleError: On Error Resume Next ' Set up the database connection, and the logon stuff Dim objGoldmine Set objGoldmine = WScript.CreateObject ("GMComAPI.Application") If Error.Number <> 0 Then HandleError objGoldmine.CommonFolder = "MSSQL: MSSQL_GoldMine: dbo:" objGoldmine.SystemFolder = "c:\\\\Program Files\\Goldmine" objGoldmine.GoldmineFolder = "c:\\\\Program Files\\Goldmine\\GMBase" Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference objGoldmine.GMUserName = "NigelB" objGoldmine.SQLUserName = "sa" objGoldmine.Login If Error.Number <> 0 Then HandleError ' Create a container Dim objContainer Set objContainer = objGoldmine.NewContainer If Error.Number <> 0 Then HandleError Creating a Contact ' Add a Contact Dim objContact Set objContact = objGoldmine.NewContainer objContact.Add objContact.Add objContact.Add objContact.Add objContact.Add objContact.Add "Contact", "Nelson" "Company", "GoldMine" "Phone1", "310454-6801" "Email", "nelson@gm.com" "WebSite", "www.gm.com" "Comments", "this is a contact2 field"
Page 72
objGoldmine.Execute "WriteContact", objContact EnumerateContainer objContact ' get RecID and AccountNo of new record Dim sRecId sRecId = objContact ("RecID") Dim sAccountNo sAccountNo = objContact ("AccountNo") Enumerating a Container Sub EnumerateContainer (objContainer) For Each objPair in objContainer Dim strPair strPair = "Name : " strPair = strPair + objPair.Name + ", Values : " For Each strValue in objPair strPair = strPair + " [" + strValue + "]" Next WScript.Echo strPair Next End Sub
JScript
Page 73
Logging In try { // Set up the database connection, and the logon stuff var objGoldmine = WScript.CreateObject ("GMComAPI.Application"); objGoldmine.CommonFolder = "MSSQL: MSSQL_GoldMine: dbo:" objGoldmine.SystemFolder = "c:\\\\Program Files\\Goldmine"; objGoldmine.GoldmineFolder = "c:\\\\Program Files\\Goldmine\\GMBase"; objGoldmine.GMUserName = "NigelB"; objGoldmine.SQLUserName = "sa"; objGoldmine.Login(); // Create a container var objContainer = objGoldmine.NewContainer (); } catch (error) { WScript.Echo ("Exception Caught"); WScript.Echo (error.description); } Creating a Contact // Add a Contact var objContact = objGoldmine.NewContainer (); objContact.Add objContact.Add objContact.Add objContact.Add objContact.Add objContact.Add ("Contact", Nelson); ("Company", "GoldMine"); ("Phone1", "(310)454-6801"); ("Email", "nelson@gm.com"); ("WebSite", "www.gm.com"); ("Comments", "this is a contact2 field");
objGoldmine.Execute ("WriteContact", objContact); EnumerateContainer (objContact); // get RecID and AccountNo of new record var sRecId = objContact("RecID")(1); var sAccountNo = objContact ("AccountNo")(1); Enumerating a Container function EnumerateContainer (objContainer) { var enumNVPairs = new Enumerator(objContainer); for (; !enumNVPairs.atEnd(); enumNVPairs.moveNext()) { Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference var objPair = enumNVPairs.item(); var strPair = "Name : "; strPair = strPair + objPair.Name + ", Value(s) : "; var enumValues = new Enumerator(objPair); for (; !enumValues.atEnd(); enumValues.moveNext()) { var objValue = enumValues.item(); strPair = strPair + " [" + objValue + "]"; } WScript.Echo (strPair); } }
Page 74
WorkArea / LicenseInfo try { var objGoldmine = WScript.CreateObject ("GMComAPI.Application"); //objGoldmine.CommonFolder = "c:\\\\Program Files\\Goldmine\\Demo"; objGoldmine.CommonFolder = "MSSQL: MSSQL_GoldMine: dbo:" objGoldmine.SystemFolder = "c:\\\\Program Files\\Goldmine"; objGoldmine.GoldmineFolder = "c:\\\\Program Files\\Goldmine\\GMBase"; objGoldmine.GMUserName = "NigelB"; objGoldmine.Login(); // Display license info. WScript.Echo (objGoldmine.LicenseInfo.Licensee); WScript.Echo (objGoldmine.LicenseInfo.LicenseNumber); WScript.Echo (objGoldmine.LicenseInfo.SiteName); WScript.Echo (objGoldmine.LicenseInfo.LicensedUsers); WScript.Echo (objGoldmine.LicenseInfo.LicensedSQLUsers); WScript.Echo (objGoldmine.LicenseInfo.LicensedGoldSyncSites); WScript.Echo (objGoldmine.LicenseInfo.IsDemo); WScript.Echo (objGoldmine.LicenseInfo.IsPrimaryLicense); WScript.Echo (objGoldmine.LicenseInfo.IsRemoteLicense); WScript.Echo (objGoldmine.LicenseInfo.IsUSALicense); WScript.Echo (objGoldmine.LicenseInfo.DLLVersion);
// Find Jon's phone number and primary email address
// open contact1 and contsupp var objContact1 = objGoldmine.NewWorkArea ("Contact1"); Copyright 1999 GoldMine Software Corporation
GoldMine API Specification and Reference var objContSupp = objGoldmine.NewWorkArea ("ContSupp"); // set the Contact1 index tag to ContName objContact1.SetOrder ("ContName"); // seek Jon's name // if (objContact1.Seek ("JON V. FERRARA") == 1) { WScript.Echo (objContact1.Read ("Contact")); // read Jon's phone number var strPhoneNumber = objContact1.Read ("Phone1"); WScript.Echo (strPhoneNumber); // read Jon's AccountNo var strAccountNo = objContact1.Read ("AccountNo"); // // set range to all contact's email records // var strRange = strAccountNo + "PE-MAIL ADDRESS"; objContSupp.Range (strRange, strRange, "ContSupp");
Page 75
var bNotFoundYet = true; // loop through all the email records for primary address while (objContSupp.Skip(1) == 1 && bNotFoundYet) { // read email address from the ContSupRef field // and status from Zip var strContSupRef = objContSupp.Read ("ContSupRef"); var strZip = objContSupp.Read ("Zip"); // show email address WScript.Echo (strContSupRef); // primary email has a '1' in the second char of Zip bNotFoundYet = (strZip.charAt(1) != '1') } } } catch (error) { WScript.Echo ("Exception Caught"); WScript.Echo (error.description); } Copyright 1999 GoldMine Software Corporation
Page 76
Delphi
Logging in var GMApp: GMApplication; GMContact: GMWContainer; begin try GMApp := coGMApplication.Create; GMApp.SystemFolder := 'C:\GOLDMINE'; GMApp.GoldMineFolder := 'C:\GOLDMINE'; GMApp.CommonFolder := 'C:\GOLDMINE\DEMO'; GMApp.GMUserName := 'NELSON'; GMApp.GMPassword := ''; GMApp.Login; // Create a container GMContact := GMApp.NewContainer; except On E:Exception do ShowMessage('Exception! '+E.Message); end; Creating a contact // Add a contact GMContact.Add('Contact', 'Nelson'); GMContact.Add('Company','GoldMine Software'); GMContact.Add('Phone1','(310)454-6801'); GMContact.Add('Email','nelson@gm.com'); GMContact.Add('Website','www.gm.com'); GMContact.Add('Comments','This is a contact2 field'); GMApp.Execute('WriteContact', GMContact); EnumerateContainer(GMContact); sRecID := GMContact.Item('RecID').Item(1); sAccountNo := GMContact.Item('AccountNo').Item(1); Enumerating a container

Goldmine5 Advanced Programming Interface

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Goldmine5 Advanced Programming Interface

Transféré par

Droits d'auteur :

Formats disponibles

GoldMine Application Programming Interface

Specification and Reference Copyright1999 GoldMine Software Corporation

GoldMine API Specification and Reference

BUSINESS LOGIC EXPLAINED..............................................................................................................................6

GoldMine API Specification and Reference

GM5S32.DLL DataStream Functions..................................................................................................23

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

Code Examples - GM5S32.DLL ............................................................................................................46

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

Business Logic Explained

GoldMine API Specification and Reference

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

GM5S32.DLL - Loading and Logging In

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

GM5S32.DLL - Name/Value Functions

Example: pGMNV := GMW_NV_Create; Returns: Pointer to a new NV container.

Example: pGMNV2 := GMW_NV_CreateCopy(pGMNV); Return: Pointer to a new NV container.

Pointer to the destination container. Pointer to the source container.

Example: GMW_NV_Copy(pGMNV2, pGMNV); Return: n/a

GoldMine API Specification and Reference Example: GMW_NV_Delete(pGMNV); Return: n/a

Example: GMW_NV_SetValue(pGMNV, Phone1, (310)555-1212); Return: n/a

Example: GMW_NV_EraseName(pGMNV, Phone1) Return: n/a

Example: GMW_NV_EraseAll(pGMNV); Return: n/a

The name stored at <Index> within the container.

GoldMine API Specification and Reference

Example: GMW_Execute(WriteContact, pGMNV); Returns: 0 failure >0 success

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

Business Logic Methods

GoldMine API Specification and Reference

The GMW_Execute function will return the same value as UserCount.

The GMW_Execute function will return the same value as UserGroupsCount.

GoldMine API Specification and Reference

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

GM5S32.DLL Security Information Functions

Parameters: <szRecType> <szUserID> <szNumber1> Returns: 1 0

GoldMine API Specification and Reference

Parameters: <szRecType> <szUserID> Returns: 1 0

Parameters: <szGroup> <szUserID> Returns: 1 0

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

GM5S32.DLL DataStream Functions

Advantages of using DataStream

DataStream Record Selection

Copyright 1999 GoldMine Software Corporation

Parameters: <szTable> <szTag> <szTopLimit> expression.) <szBotLimit> <szFields>

Succesful handle Failure.

Succesful handle Failure. Invalid SQL Query/Timeout

GoldMine API Specification and Reference

Parameters: <iHandle> GMW_DS_Query <szBuf> <iBufSize> <nGetRecs>

GoldMine API Specification and Reference

Parameters: <iHandle> GMW_DS_Query Returns: 1 0 Success Failure

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference

GM5S32.DLL - Low-Level access using Work Areas

Copyright 1999 GoldMine Software Corporation

GoldMine API Specification and Reference