TDM Windows Application Programming Interface
From ICISWiki
Contents |
DLL Architecture
INTRODUCTION
ICIS applications can be written in any computer language under a WINDOWS 32-bit operating system. They must only access the ICIS databases through the ICIS DLL functions. Programs, which access the database directly or through any other system, may be useful for loading data, but are not portable to other users and so, are not part of the ICIS system. Any applications, which have potential value for other users, should only use the DLL.
Conventions of ICIS Application Development
Most ICIS applications are expected to be WINDOWS 95, 32-bit programs but they could be WINDOWS NT, Windows 2000 or 32-bit console applications. The restriction to 32 bit operating systems is due to requirements of the ICIS DLL and the ODBC drivers it uses. This is not regarded as a serious restriction since ICIS will at least require a computer with a CD drive, and most of these are capable of running a 32-bit operating system. Apart from this restriction applications can be written in any computer language which can access the ICIS DLL. FORTRAN 90, Delphi PASCAL, Visual Basic, and C++ have been used to access the DLL so far. The first function of any ICIS application is to establish the ODBC data connections for the current session. To do this it must read the ODBC data source names from an INI file. The default file is called ICIS.INI. An application initially looks for ICIS.INI in the WINDOWS %TEMP% directory (the name of this directory is stored in the environment variable temp), unless a parameter is passed together when an application is called. The parameter to use a different INI file should contain the full pathname of the INI file to use. The structure of ICIS.INI files is defined in 5.3.1, but new applications may require new sections in the file. These sections should be headed by the application name and will be ignored by other applications. Since several users and projects may wish to access different data sources on the same computer a system of replacing ICIS.INI for each session has been established through the LAUNCHER application (5.3). The second function of any application is to identify the user and verify his or her access privileges.
Data Source Names and the INI file
Access to ICIS databases is provided through the ICIS DLL described in this chapter. Functions in this DLL use ODBC to access the data in the Central and Local databases. These must therefore be defined as ODBC data sources before ICIS applications will operate. Steps to set up the sources are described in 5.2.3b. The ICIS DLL obtains information from an initialization file. This file must exist before applications will run, the application passes the name of the INI file to the DLL, but for general applications this name should be ICIS.INI.
Return values for ICIS DLL functions
Most DLL functions return a long integer value which are: GMS_SUCCESS if the function call was successful, GMS_ERROR if the function call results in an error, GMS_NO_DATA if no data is found in the databases relevant to a particular call or GMS_NOACCESS if the ICIS user does not have access to the particular function being called. Some functions return other values to indicate different events. These are described in the function descriptions. Note: When making DLL function calls, always initialize character arguments to null prior to calling the function. If this is not done each and every time, errors may occur or you may accidentally filter your results.
GMS FUNCTIONS return value
| Return Code | Value |
|---|---|
| GMS_NO_DATA | 0 |
| GMS_SUCCESS | 1 |
| GMS_ERROR | -1 |
| GMS_NO_ACCESS | -2 |
| GMS_INVALID_PASSWORD | -3 |
| GMS_INVALID_USER | -4 |
| GMS_NAME_EXISTS | -5 |
| GMS_NOT_FOUND | -6 |
| GMS_MORE_DATA | -7 |
| GMS_READ_ONLY | -8 |
| GMS_INVALID_INSTALLATION | -9 |
| GMS_INVALID_DBSTRUCTURE | -10 |
ICIS Data Structures
Introduction
Several compound structures are used to pass information between the DLL and the application. Users may specify their own names for elements in the structures, but not their order data types. However we recommend using the field names supplied to ensure uniformity across applications.
The structures are defined in the following tables. The data type “long” is a 4-byte signed integer, the type “double” is an 8-byte real and the type “single” is a 4-byte real or ‘float’ data type. Character or string elements are denoted char [n] where n is the length of the element in bytes. All character variables are NULL terminated strings so one byte will be used for the NULL character.
The size of elements in the structures is larger than the space allocated to corresponding fields in the database. This facilitates data transfer to the DLL by accommodating the NULL termination character for character variables and by ensuring data alignment in most programming languages. However, care must be taken that data passed to the database through the structures is not too large for the database fields.
ICIS DATA TYPES
| Data Type | Size in bytes |
|---|---|
| Double | 8 |
| single or float | 4 |
| Long | 4 |
| char[n] (including null character) | n |
GMS DATA STRUCTURES
GMS_Germplasm structure (in order of declaration)
| Element name | Type | Database Field Name |
|---|---|---|
| GERMPLASM_ID | long | GERMPLASM_ID |
| METHOD | long | METHOD_NO |
| NO_PROGENITORS | long | NO_PROGENITORS |
| PROGENITOR_ID1 | long | PROGENITOR_ID1 |
| PROGENITOR_ID2 | long | PROGENITOR_ID2 |
| USER | long | GERMPLASM_USER_ID |
| LOCAL_GID | long | LOCAL_GERMPLASM_ID |
| LOCATION | long | LOCATION_NO |
| DATE | long | GERMPLASM_DATE |
| REFERENCE | long | GERMPLASM_REFERENCE |
| REPLACE | long | GERMPLASM_RPLCE |
GMS_NameData structure
| Element name | Type | Database Field Name |
|---|---|---|
| NID | long | NAME_IDENTIFIER |
| GERMPLASM | long | GERMPLASM_ID |
| TYPE | long | NAME_TYPE |
| STATUS | long | NAME_STATUS |
| USER | long | NAME_USER_ID |
| LOCATION | long | NAME_LOCATION_NO |
| DATE | long NAME_DATE | |
| REFERENCE | long | NAME_REFERENCE |
GMS_Attribute structure
| Element name | Type | Database Field Name |
|---|---|---|
| AID | long | Attribute identifier |
| GERMPLASM | long | GERMPLASM_ID |
| TYPE | long | ATTRIBUTE_TYPE |
| USER | long | ATTRIBUTE_USER_ID |
| LOCATION | long | ATTRIBUTE_LOCATION_NO |
| DATE | long | ATTRIBUTE_DATE |
| REFERENCE | long | NAME_REFERENCE |
GMS_Method structure
| Element name | Type | Database Field Name |
|---|---|---|
| METHOD_ID | long | METHOD_ID |
| REFERENCE | long | METHOD_REFERENCE |
| NO_PROGENITORS | long | NO_PROG_REQUIRED |
| NO_MATERNAL | long | NO_FEMALE_PARENTS |
| ATTRIBUTE | long | METHOD_ATTRIBUTE |
| TYPE | char[4] | METHOD_TYPE |
| CODE | char[12] | METHOD_CODE |
| NAME | char[52] | METHOD_NAME |
| GROUP | char[4] | METHOD_GROUP |
| GENEQ | long | GENETIC_EQUIVALENCE |
| MUID | long | METHOD_USER |
| LMID | long | LOCAL_METHOD_ID |
| MDATE | long | METHOD_DATE |
GMS_UDField structure
| Element name | Type | Database Field Name |
|---|---|---|
| UDFIELD_ID | long | USER_FIELD_NO |
| TABLE | char[28] | USER_FIELD_TABLE |
| TYPE | char[16] | USER_FIELD_TYPE |
| CODE | char[12] | USER_FIELD_CODE |
| NAME | char[52] | USER_FIELD_NAME |
| FORMAT | char[256] | USER_FIELD_FMT |
| LFLDNO | long | LOCAL_FIELD_NO |
| FUID | long | FIELD_USER_ID |
| FDATE | long | FIELD_DATE |
GMS_Changes Structure
| Element name | Type | Database Field Name |
|---|---|---|
| CID | long | CID |
| CRECORD | long | CRECORD |
| CFROM | long | CFROM |
| CTO | long | CTO |
| CDATE | long | CDATE |
| CTIME | long | CTIME |
| CUID | long | CUID |
| CREF | long | CREF |
| CTABLE | char[16] | CTABLE |
| CFIELD | char[16] | CFIELD |
| CGROUP | char[20] | CGROUP |
GMS_User structure
| Element name | Type | Database Field Name |
|---|---|---|
| USER_ID | long | USER_ID |
| INSTALLATION | long | INSTALLATION |
| STATUS | integer | USER_STATUS |
| ACCESS | long | USER_ACCESS |
| TYPE | char[32] | USER_TYPE |
| NAME | char[32] | USER_NAME |
| PASSWORD | char[12] | USER_PASSWORD |
| PERSON | long | PERSON_ID |
| ASSIGN_DATE | long | ASSIGN_DATE |
| CLOSE_DATE | long | CLOSE_DATE |
GMS_Installation Structure
| Element name | Type | Database Field Name |
|---|---|---|
| INSTALLATION | long | INSTALLATION_NO |
| ADMINISTRATOR | long | ADMIN_USER_ID |
| UDATE | long | UPDATE_DATE |
| UGID | long | UPDATE_GID |
| ULOCN | long | UPDATE_LOCN |
| UMETHN | long | UPDATE_METHN |
| UFLDNO | long | UPDATE_FLDNO |
| UREFNO | long | UPDATE_REFNO |
| UPID | long | UPDATE_PID |
LIST DATA STRUCTURE
GMS_ListName Structure
| Element name | Type | Database Field Name |
|---|---|---|
| LISTID | long | LISTID |
| LISTNAME | char[48] | LISTNAME |
| LISTDATE | long | LISTDATE |
| LISTTYPE | char[8] | LISTTYPE |
| LISTUID | long | LISTUID |
| LISTDESC | char[80] | LISTDESC |
| LISTSTATUS | long | LIST_STATUS |
| LISTHIER | long | LIST_HIERARCHY |
GMS_ListData Structure
| Element name | Type | Database Field Name |
|---|---|---|
| LISTID | Long | LISTID |
| GID | Long | GID |
| ENTRYID | Long | ENTRYID |
| ENTRYCD | char[48] | ENTRYCD |
| SOURCE | char[48] | SOURCE |
| DESIG | char[164] | DESIG |
DLL Functions for Access Control
Access to the different subsystems of ICIS is through a pair of open and close commands. Before any functions associated to the subsystem can be called, the open access command must executed first. However, access to the ICIS applications is based on the right granted to the current user of the installation as specified in the USERS and INSTLN tables. This right is checked and verified through the open access function of GMS subsystem.
GENEALOGY MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS
- GMS_openDatabase
- GMS_openDatabase reads the initialization file identified by the value of argument szIniFile. The data source names, DBMS user IDs and DBMS passwords are read from this file and the associated databases opened. GMS_openDatabase does not check ICIS User IDs or passwords, but logs the user as GUEST with password GUEST with read-only access to the central and local database. To obtain full access to either database, use GMS_openDatabase2. The format of the INI file is described in 5.2.3b, and the convention is to set szIniFile to ‘ICIS.INI’, which should exist in the default windows %TEMP% directory (6.1.1). It is not necessary to follow this convention for specific applications.
- Syntax
- long GMS_openDatabase(szIniFile)
- Arguments
Argument Type Use Description szIniFile char * Input Pointer to NULL terminated string containing the name of an existing initialization file. If an INI file other than %TEMP%\ICIS.INI is used, it should be passed as a parameter to the application including the full pathname.
- Returns
- GMS_SUCCESS, GMS_ERRORor GMS_NOACCESS
- Comments
- The function returns GMS_ERROR if the one or both GMS databases are not opened successfully. No data sources are connected unless all are found and opened.
- GMS_openDatabase2
- GMS_openDatabase2 reads the initialization file identified by the value of argument szIniFile. There are two levels of access control to ICIS databases. First, the database management system may have a system of user IDs and passwords to control opening the database. Secondly, GMS has a table of user IDs, access privileges, and passwords controlling access to the ICIS fundamental functions. The data source names, database user IDs and database passwords are read from the initialization file szIniFile. The ICIS user name of the current user is passed in szUserName and the ICIS password in szPassword. These must be obtained by the application, and one short cut to this is to read them from the INI fil. The function returns the USER_ID of the current user in argument userID.
- Syntax
- long GMS_openDatabase2(szIniFile, szUserName, szPassword, userID)
- Arguments
Argument Type Use Description szIniFile char * input Pointer to NULL terminated string containing the name of an existing initialization file. The file must exist and be present in the Windows subdirectory. szUserName char * input Pointer to NULL terminated string containing the user name szPassword char * input Pointer to NULL terminated string containing the password of the user userID long * output Pointer to a long integer to contain the User ID corresponding to szUserName or –32678 for a guest user.
- Returns
- GMS_SUCCESS, GMS_ERROR GMS_NO_ACCESS, GMS_INVALID_PASSWORD, GMS_INVALID_USER, or GMS_INVALID_INSTALLATION .
- Comments
- The function returns GMS_INVALID_USER if szUserName is not found. If the szPassword is incorrect it returns GMS_INVALID_PASSWORD. If the user’s installation (USERS.INSTALID) is zero (database administrators only) then the function will allow write access to any local database. Otherwise, the function checks that the local installation (INSTLN.INSTALID) is the same as the user’s installation (USERS.INSTALID). If the user’s installation is not zero and does not match the current local database, the function restricts the user to read only access and returns GMS_READ_ONLY.
- If the local installation (INSTLN.INSTALID) is negative (new installation) then no further checks are made, but if it is positive (existing installation) then the function checks that the local installation fields are identical to the central fields for the matching installation. If not, the function returns GMS_INVALID_INSTALLATION.
- The function also checks the security setting specified in the SECURITY key of the ICIS.INI file. If the security setting is 1, the user and password in the INI file is used to open the database and is checked against . If the security setting is 2, access is allowed only to users with USTATUS = 2 and the password is encrypted to have access to ICIS database. . If the security setting is 3, access is allowed only to users with USTAUS = 3. Password is encrypted to have access to ICIS database and user name is encrypted to have access to central GMS Database. If the security setting is 4, access is allowed only to users with USTATUS = 4; password is encrypted to have access to RDBMS database and to ICIS DLL.
- The function returns GMS_ERROR if the one or both GMS databases are not opened successfully, or cause by any internal error.
- GMS_closeDatabase
- GMS_closeDatabase closes the connection to both Central and Local databases. Frees up all allocated memory used by the databases and DLL.
- Syntax (Procedure)
- GMS_closeDatabase
- Arguments
- No arguments
- Returns
- No return value
- GMS_commitData
- GMS_commitData will permanently write all changes to the database made by calling add or change functions.
- Syntax
- GMS_commitData No arguments, No returns
- Comment
- Caution should be observed in using this function because it clears the cache used by the SQL driver and clears all SQL transactions. Hence if it is called between a FIND_FIRST and FIND_NEXT sequence in a search, a ‘function sequence error’ will occur on the next search call with fOpt set to FIND_NEXT.
DATA MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS
- DMS_openDatabase
- DMS_openDatabase is the primary function that establishes connection to the DMS databases through the initialization file identified by the argument szInifile. Data source names, DBMS user IDs and pass words needed to connect are read from this file.
- Syntax
- long DMS_openDatabase(szInifile)
- Arguments
Argument Type Use Description szInifile Char * Input Pointer to a NULL terminated string containing the name of an existing initialization file. This file must reside in the default WINDOWS directory.
- Returns
- DMS_SUCCESS(1), DMS_ERROR(-1)
- DMS_closeDatabase
- DMS_closeDatabase closes connection to both Central and Local DMS databases. The function also frees up allocated memory of handlers associated with it.
- Syntax (Procedure)
- void DMS_closeDatabase()
- Arguments
- No arguments
- Returns
- No return value
INVENTORY MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS
- IMS_OpenDatabase
- IMS_OpenDatabase is the primary function that establishes a connection to the inventory database through the initialisation file identified by the argument szInifile. Data source names, DBMS user IDs and passwords are read from this file.
- Syntax
- long IMS_OpenDatabase(szInifile)
- Arguments
Argument Type Use Description szInifile Char Input Pointer to a NULL terminated string containing the name of an existing initialisation file. This file must reside in the default WINDOWS directory.
- Returns
- IMS_SUCCESS(1), IMS_ERROR(-1)
- IMS_CloseDatabase
- IMS_closeDatabase closes connection to the inventory database. The function also frees up allocated memory used by the DLL.
- Syntax
- void IMS_closeDatabase()
- Arguments
- No arguments
- Returns
- No return value
USER AND INSTALLATION
- GMS_getUser
- GMS_getUser will retrieve user information. The first argument is a pointer to a GMS_User structure (6.1.2g). If the USER_ID element is not zero when the function is called then it returns the details for the corresponding user. If it is zero then a user name must be supplied in the NAME element and the function returns details for the first user with the specified name if fOpt = FIND_FIRST or for the next available user with that name if fOpt = FIND_NEXT. Any call which fails to get user information returns GMS_NO_DATA.
- Syntax
- long GMS_getUser(user, fOpt)
- Arguments
Argument Type Use Description User GMS_User* input/output Address of a GMS_User structure fOpt Long input Either FIND_FIRST or FIND_NEXT
- Returns
- GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA
- Comments
- The principle of using GMS_getUser is almost the same as GMS_getAttribute. If there is a problem accessing the database, the function will return GMS_ERROR.
- GMS_getInstallation
- GMS_getInstallation will retrieve installation information.
- Syntax
- long GMS_getInstallation(instln,szDesc,nszDesc)
- Arguments
Argument Type Use Description instln GMS_Installation* input/ output Address of a GMS_Installation structure to contain the installation parameters. szDesc char* output Address of a character variable to contain the installation description nszDesc Long input Maximum data size szDesc can hold (including the null terminator).
- Returns
- GMS_ERROR, GMS_NO_DATA , GMS_SUCCESS
- Comments
- If the instno field of instln structure is zero then the function will return the current installation record from the local database. Otherwise, it will return the installation record corresponding to the value of the instno field. The function returns GMS_ERROR if there is no local INSTALLATION table or if the installation record corresponding to INSTNO field is not found in the central database. Otherwise, it returns GMS_SUCCESS .
- GMS_addUser
- GMS_addUser adds a new user to the local USERS table. Details of the reference must be stored in appropriate elements of the user parameter. The next available user number will be returned in the USERID element. New data is not committed to the local database until the function GMS_commitData (6.8.1) has been called, and uncommitted data can be deleted from the buffer with the GMS_rollbackData function (6.8.2)
- Syntax
- long GMS_addUser(user,szEname,security)
- Arguments
Argument Type Use Description user GMS_USERS * input/output Address of a GMS_BIBREFS structure szEname Char * output Address of NULL terminated string to place the encrypted user name security long input The level of security
- Returns
- GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS
GMS DLL FUNCTIONS
SEARCH FUNCTIONS
- GMS_findName
- GMS_findName searches all names in the NAMES tables for the search string szNameSrch. If fOpt is FIND_FIRST the function stores the name details of the first match of the germplasm record that has not been replaced in structure nameData and the NAME value in szName. The germplasm details of the matched record are retrieved to the structure germData.. If fOpt is FIND_NEXT it stores the succeeding non-replaced match.
- Syntax
- long GMS_findName(szNameSrch, nameData, germData, szName, nszName, fOpt)
- Arguments
Argument Type Use Description SzNameSrch char * input Address of NULL terminated string containing the name search NameData GMS_NameData* input/ output Address of a GMS_NameData structure to contain the name data GermData GMS_Germplasm* output Address of a GMS_Germplasm Structure to contain Germplasm data for the retrieved germplasm SzName char * output Address of NULL terminated string to place the NAME NszName long input Maximum length of szName Fopt long input Either FIND_FIRST or FIND_NEXT
- Returns
- GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA
- Comments
- The target name can contain wildcards within the 128 characters of the string. ‘_’ match any character and a terminal ‘%’ matches any trailing characters. On the first call to this function, fOpt should have a value of FIND_FIRST then call the function with fOpt set to FIND_NEXT repeatedly until it returns GMS_NO_DATA to find subsequent matching names.
- The function updates the name record based on the modification stored in the CHANGES table.
- Returns
- GMS_ERROR if any internal ODBC function call fails.
- GMS_findName2
- GMS_findName2 searches for string matches to any of three forms of a specified name. The forms of the name are the specified string, the string with all spaces removed and with name standardization applied (3.1.3, see also the GMS_standardName function 6.9.8). The function returns name and germplasm data for search matches. If the STATUS field of the NameData argument is non-zero then only names of the specified status are returned.
- Note
- This routine calls GMS_applyChanges (6.4.10) internally to update the germplasm record.
- The function updates the name record based on the modification stored in the CHANGES table.
- Syntax
- long GMS_findName2 (szNameSrch, nameData, germData, szName, nszName, fOpt)
- Arguments
- As for GMS_findName except that a new argument Germ is included:
Argument Type Use Description szNameSrch char * input Address of NULL terminated string containing the name search NameData GMS_NameData* input/ output Address of a GMS_NameData structure to contain the name data GermData GMS_Germplasm* output Address of a GMS_Germplasm Structure to contain Germplasm data for the retrieved germplasm SzName char * output Address of NULL terminated string to place the NAME NszName long input Maximum length of szName Fopt long input Either FIND_FIRST or FIND_NEXT
- Comments
- This function works like GMS_findName but searches for matches to the supplied name szNameSrch with any internal spaces removed and after applying the name standardization algorithm (3.1.3 and 6.9.8). Wildcards characters should appear within the first 128 characters of the strings with spaces removed and after name standardization, otherwise they will not be recognized as wildcards.
- The function updates the name record based on the modification stored in the CHANGES table.
- GMS_findName3
- GMS_findName3 searches for a string in the NAMES table, both as specified and with any spaces removed, and returns name and germplasm data for search matches. A value in TYPE or STATUS or LOCATION is specified, only those records matching the combination of values are returned. Otherwise, it functions like GMS_findName.
- Note
- This routine calls GMS_applyChanges (6.4.10) internally to update the germplasm record before returning.
- Syntax
- long GMS_findName3 (szNameSrch, nameData, germData, szName, nszName, fOpt)
- Arguments
- As for GMS_findName except that a new argument GermData is included:
Argument Type Use Description GermData GMS_Germplasm* output Address of a GMS_Germplasm Structure to contain Germplasm data for the retrieved germplasm
- Comments
- This function works like GMS_findName but also returns the germplasm record and also searches for matches to the supplied name szNameSrch with any internal spaces removed but does not apply the name standardization algorithm.
- The function updates the name record based on the modification stored in the CHANGES table.
- Also see GMS_findName comments.
- GMS_ERROR if any internal ODBC function call fails.
- GMS_getDerivativeNeighbor
- GMS_getDerivativeNeighbor retrieves the germplasms within the derivative neighborhood of the given GID, m-step backward and n-step forward
- Syntax
- long GMS_getDerivativeNeighbor (gid, MStep,NStep,idList,idLstSz, blnDH)
- Arguments
Argument Type Use Description gid long input The GID of the target germplasm MStep long input Number of step backward within the generation history from the level of the target germplasm NStep long input Number of step forward within the generation history from the level of the target germplasm idList long * output Array that will contain the germplasm within the specified level of derivative neighborhood idLstSz long * input/output As input, it is the maximum length of idList and as output, it is the number of germplasms retrieved if lower thatn the maximum length blnDH long input 1 if Double Haploid germplasm is to be excluded as part of derivative neighborhood
- GMS_getMgmntNeighbor
- GMS_getMgmntNeighbor retrieves the management neighbors of the given management group germplasm
- Syntax
- long GMS_getMgmntNeighbor (mgid, data, name, szName, nszName, fopt)
- Arguments
Argument Type Use Description mgid long input The GID of the root of the management group data GMS_Germplasm* output The germplasm record of the management neighbor name GMS_NameData* output The name record of the management neighbor szName Char* output Array of characters for the preferred name of the management neighbor nszName long input length of the szName fopt long input 0 if getting the first record, 1 for succeeding record
