TDM Windows Application Programming Interface 5.4

From ICISWiki

Contents 1 DLL Architecture 1.1 INTRODUCTION 1.1.1 Conventions of ICIS Application Development 1.1.2 Data Source Names and the INI file 1.1.3 Return values for ICIS DLL functions 2 ICIS Data Structures 2.1 Introduction 2.2 GMS DATA STRUCTURES 2.2.1 GMS_Germplasm structure (in order of declaration) 2.2.2 GMS_NameData structure 2.2.3 GMS_Attribute structure 2.2.4 GMS_Method structure 2.2.5 GMS_UDField structure 2.2.6 GMS_Changes Structure 2.2.7 GMS_User structure 2.2.8 GMS_Installation Structure 2.3 LIST DATA STRUCTURE 2.3.1 GMS_ListName Structure 2.3.2 GMS_ListData Structure 2.4 LMS Data Structure 2.4.1 GMS_Location structure 2.5 DMS DATA STRUCTURE 2.5.1 DMS_STUDY Structure 2.5.2 DMS_FACTOR Structure 2.5.3 DMS_VARIATE Structure 2.5.4 DMS_DATAN Structure 2.5.5 DMS_DATAC Structure 2.5.6 DMS_LEVELC Structure 2.5.7 DMS_LEVELN Structure 2.5.8 EFFECT Structure 2.5.9 DMS_VEFFECT 2.5.10 DMS_OINDEX Structure 2.5.11 DMS_TRAIT Structure 2.5.12 DMS_SCALE Structure 2.5.13 DMS_TMETHOD Structure 2.5.14 DMS_SCALECON 2.5.15 DMS_SCALEDIS 2.5.16 DMS_NumVALUE Structure 2.5.17 DMS_CharVALUE Structure 2.5.18 Source 2.5.19 DMS_DMSATTR 2.6 IMS DATA STRUCTURES 2.6.1 IMS_LOT Structure 2.6.2 IMS_TRANSACTION Structure 2.7 BIBREF DATA STRUCTURE 2.8 GEMS DATA STRUCTURE 2.8.1 GEMS_INFO structure 2.8.2 GEMS_MARKER_DETECTOR structure 2.8.3 GEMS_MV structure 2.8.4 GEMS_NAME structure 2.8.5 GEMS_COMPONENT structure 2.8.6 GEMS_PD_COMP structure 2.8.7 GEMS_PROP structure 2.8.8 GEMS_PD structure 2.8.9 GEMS_CONDITION structure 2.8.10 PD_COMP_INFO structure 2.8.11 GEMS_SCALE structure 2.8.12 GEMS_METHOD structure 2.8.13 PROP_INFO structure 2.8.14 GEMS_LOCUS structure 2.9 SUPPORTING TABLES 2.9.1 SUP_PERSONS structure 2.9.2 SUP_INSTITUTE structure 3 DLL Functions for Access Control 3.1 GENEALOGY MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS 3.1.1 GMS_openDatabase 3.1.2 GMS_openDatabase2 3.1.3 GMS_closeDatabase 3.1.4 GMS_commitData 3.2 DATA MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS 3.2.1 DMS_openDatabase 3.2.2 DMS_closeDatabase 3.2.3 DMS_commitData 3.3 INVENTORY MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS 3.3.1 IMS_OpenDatabase 3.3.2 IMS_CloseDatabase 3.3.3 IMS_commitData 3.4 GENE MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS 3.4.1 GEMS_openDatabase 3.4.2 GEMS_closeDatabase 3.4.3 GEMS_commitData 3.5 USER AND INSTALLATION 3.5.1 GMS_getUser 3.5.2 GMS_getInstallation 3.5.3 GMS_addUser 4 GMS DLL FUNCTIONS 4.1 SEARCH FUNCTIONS 4.1.1 GMS_findName 4.1.2 GMS_findName2 4.1.3 GMS_findName3 4.1.4 GMS_findDescendant 4.1.5 GMS_findGermplasm 4.1.6 GMS_findCIDSID 4.2 GMS DATA RETRIEVAL functions 4.2.1 GMS_getGermplasmRecord 4.2.2 GMS_getGermplasm 4.2.3 GMS_getGermplasm2 4.2.4 GMS_getGermplasm3 4.2.5 GMS_getProgenitorID 4.2.6 GMS_getNameRecord 4.2.7 GMS_getName 4.2.8 GMS_getAttribute 4.2.9 GMS_getMethod 4.2.10 GMS_applyChanges 4.3 Functions to add data to the local database 4.3.1 GMS_addGermplasm 4.3.2 GMS_addName 4.3.3 GMS_addAttribute 4.3.4 GMS_addChanges 4.4 Functions to correct LOCAL GMS records 4.4.1 GMS_setGermplasm 4.4.2 GMS_setProgenitorID 4.4.3 GMS_setPreferredName 4.4.4 GMS_setPreferredAbbr 4.4.5 GMS_setName 4.5 BASIC GMS FUNCTIONS 4.5.1 GMS_generateTree 4.5.1.1 Code Example: 4.5.1.2 CODEEXAMPLE OUTPUT 4.5.2 GMS_crossExpansion: 4.5.3 GMS_listNames 4.5.4 GMS_computeGenerationNo 4.5.5 GMS_getDerivativeNeighbor 4.5.6 GMS_getMgmntNeighbor 5 LIST DLL FUNCTIONS 5.1 FUNCTIONS ASSOCIATED TO LISTNMS TABLE 5.1.1 GMS_getListName 5.1.2 GMS_findListName 5.1.3 GMS_setListName 5.1.4 GMS_addListName 5.1.5 GMS_deleteListName 5.1.6 GMS_getListByStatus 5.2 FUNCTIONS ASSOCIATED WITH LISTDATA TABLE 5.2.1 GMS_getListData 5.2.2 GMS_findListData 5.2.3 GMS_setListData 5.2.4 GMS_addListData 5.2.5 GMS_deleteListData 6 USER DEFINED FIELDS AND CONSTANTS FUNCTIONS 6.1 GMS_getUDField 6.2 GMS_getUDField2 6.3 GMS_findUDField 7 DMS DLL FUNCTIONS 7.1 INTRODUCTION 7.2 ADD FUNCTIONS 7.2.1 DMS_addStudy 7.2.2 DMS_addFactor 7.2.3 DMS_addVariate 7.2.4 DMS_addLevelN 7.2.5 DMS_addLevelC 7.2.6 DMS_addDataN 7.2.7 DMS_addDataC 7.2.8 DMS_addObsunit 7.2.9 DMS_addOindex 7.2.10 0 DMS_addAttr 7.2.11 DMS_addTrait 7.2.12 DMS_addScale 7.2.13 DMS_addTmethod 7.2.14 DMS_addEffect 7.2.15 DMS_addVEffect 7.3 DMS FIND FUNCTIONS 7.3.1 DMS_findStudy 7.3.2 DMS_findFactor 7.3.3 DMS_findVariate 7.3.4 DMS_findLevelN 7.3.5 DMS_findLevelC 7.3.6 DMS_findLabelC 7.3.7 DMS_findLabelN 7.3.8 DMS_findStOunit 7.3.9 DMS_findStEffect 7.4 DMS GENERAL QUERY FUNCTIONS 7.4.1 DMS_searchLevelN 7.4.2 DMS_searchDataN 7.4.3 DMS_searchLevelC 7.4.4 DMS_searchDataC 7.5 QUERY THROUGH OBSERVATION UNIT 7.5.1 DMS_defineOunitDN 7.5.2 DMS_defineOunitDC 7.5.3 DMS_defineOunitLN 7.5.4 DMS_defineOunitLC 7.5.5 DMS_extractOunitDN 7.5.6 DMS_extractOunitDC 7.5.7 DMS_extractOunitLN 7.5.8 DMS_extractOunitLC 7.5.9 DMS_describeOunit 7.5.10 DMS_describeEffectOunit 7.6 DMS ACCESS FUNCTIONS 7.6.1 DMS_getStudy 7.6.2 DMS_getObsunit 7.6.3 DMS_getLevelC 7.6.4 DMS_getLabelC 7.6.5 DMS_getAllLevelC 7.6.6 DMS_getAllLabelC 7.6.7 DMS_getLevelN 7.6.8 DMS_getLabelN 7.6.9 DMS_getAllLevelN 7.6.10 0DMS_getAllLabelN 7.6.11 DMS_getDataC 7.6.12 DMS_getDataN 7.6.13 DMS_getTrait 7.6.14 DMS_getScale 7.6.15 DMS_getScaleCon 7.6.16 DMS_getScaleDis2 7.6.17 DMS_getScaleTab 7.6.18 DMS_getTmethod 7.6.19 DMS_getOunitLevelN 7.6.20 DMS_getOunitLevelC 7.6.21 DMS_getEffectOunit 7.6.22 DMS_getEffectRecord 7.6.23 DMS_getEffectRecordV 7.6.24 DMS_getEffect 7.6.25 DMS_getFactorEffect 7.6.26 DMS_getFactor 7.6.27 Long DMS_getFactor( factor, fOpt) 7.6.28 DMS_getFactorLabel 7.6.29 DMS_getVariate 7.6.30 DMS_getDMSAttr 7.7 DMS UPDATE FUNCTIONS 7.7.1 DMS_updateDataC 7.7.2 DMS_updateDataN 7.8 DMS DELETE FUNCTION 7.8.1 DMS_deleteStudy 7.9 MISCELLANEOUS FUNCTIONS 7.9.1 DMS_existCombination 7.9.2 DMS_existEffect 7.9.3 DMS_minOunitid 7.9.4 DMS_deleteStudy 7.9.5 DMS_deleteDataC 7.9.6 DMS_deleteDataN 8 IMS DLL FUNCTIONS 8.1 ADD Functions 8.1.1 IMS_addLot 8.1.2 IMS_addTransaction 8.2 DATA RETRIEVAL FUNCTIONS 8.2.1 IMS_findLotRecord 8.2.2 IMS_findTransactionRecord 8.2.3 IMS_getTransactionReserve 8.2.4 IMS_getTransactionDeposit 8.2.5 IMS_getReserveByPerson 8.2.6 IMS_getDepositByPerson 8.2.7 IMS_getBalanceOfLot 8.3 UPDATE FUNCTIONS 8.3.1 IMS_setTransaction 8.3.2 IMS_setLot 8.4 REPORT FUNCTIONS 8.4.1 IMS_reportAllTransaction 8.4.2 IMS_reportMaterialDist 8.4.3 IMS_reportByRequestor 8.4.4 IMS_reportBalance 8.4.5 IMS_reportEmptyShelves 8.4.6 IMS_reportDormantEntries 8.4.7 IMS_reportMinimumAmount 8.4.8 IMS_reportLotByEntity 8.4.9 IMS_reportLotByEntityGIDFrom 8.4.10 IMS_reportLotByEntityGIDRange 8.5 MISCELLANEOUS 8.5.1 IMS_closeLot 8.5.2 IMS_calculateBalance 9 LMS DLL FUNCTIONS 9.1 GMS_findLocation 9.2 GMS_getLocation 9.3 GMS_getLocation2 9.4 GMS_addLocation 10 BIBREF DLL FUNCTIONS 10.1 GMS_getBibrefs 10.2 GMS_addBibrefs 11 GEMS DLL FUNCTIONS 11.1 ADD FUNCTIONS 11.1.1 GEMS_addGEMSName 11.1.2 GEMS_addComponent 11.1.3 GEMS_addMD 11.1.4 GEMS_addMV 11.1.5 GEMS_addLocus 11.1.6 GEMS_addPD 11.1.7 GEMS_addPdComp 11.1.8 GEMS_addProp 11.1.9 GEMS_addScale 11.1.10 GEMS_addMethod 11.2 GET FUNCTIONS 11.2.1 GEMS_getGemsMID 11.2.2 GEMS_getGemsMVID 11.2.3 GEMS_getNameID 11.2.4 GEMS_getProtocolID 11.2.5 GEMS_getPdComp 11.2.6 GEMS_findPID 11.2.7 GEMS_findPdid 11.2.8 GEMS_findPropID 11.2.9 GEMS_findScale 11.2.10 GEMS_findMethod

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	GID
METHOD	long	METHNO
NO_PROGENITORS	long	GNPGS
PROGENITOR_ID1	long	GPID1
PROGENITOR_ID2	long	GPID2
USER	long	GERMUID
LOCAL_GID	long	LGID
LOCATION	long	LOCNO
DATE	long	GDATE
REFERENCE	long	GREF
REPLACE	long	GRPLCE
MANAGEMENT_GID	long	MGID

GMS_NameData structure

Element name	Type	Database Field Name
NAME_IDENTIFIER	long	NNID
GERMPLASM_ID	long	GID
NAME_TYPE	long	NTYPE
STATUS	long	NSTATUS
USER	long	NUID
LOCATION	long	NLOCNO
DATE	long	NDATE
REFERENCE	long	NREF

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	FLDNO
TABLE	char[28]	FTABLE
TYPE	char[16]	FTYPE
CODE	char[12]	FCODE
NAME	char[52]	FNAME
FORMAT	char[256]	FFMT
LFLDNO	long	LFLDNO
FUID	long	FUID
FDATE	long	FDATE
SCALEID	long	SCALEID

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
LRECID	Long	LRECID
ENTRYCD	char[48]	ENTRYCD
SOURCE	char[48]	SOURCE
DESIG	char[256]	DESIG
GRPNAME	char[256]	GRPNAME
ENTRYID	Long	ENTRYID

LMS Data Structure

GMS_Location structure

Element name	Type	Database Field Name (Table 4.3.1)
LOCATION_ID	long	LOCATION_ID
TYPE	long	LTYPE
NLLP	long	NLLP
PREFERRED_NAME	char[64]	PREFERRED_NAME
ABBREVIATION	char[12]	ABBREVIATION
SUBNAT_LEVEL3	long	SUBNAT_LEVEL3
SUBNAT_LEVEL2	long	SUBNAT_LEVEL2
SUBNAT_LEVEL1	long	SUBNAT_LEVEL1
COUNTRY	long	COUNTRY_CODE
REPLACE	long	LOCATION_REPLACE

DMS DATA STRUCTURE

DMS_STUDY Structure

Element Name	Type	Database Field Name
STUDYID	Long	STUDYID
STUDY_NAME	Char[52]	SNAME
PROGRAM_KEY	Long	PMKEY
TITLE	Char[256]	TITLE
INVESTIGATOR_ID	Long	INVESTID
STUDY_TYPE	Char[2]	STYPE
START_DATE	Long	SDATE
END_DATE	Long	EDATE
USERID	Long	USERID

DMS_FACTOR Structure

Element Name	Type	Database Field Name
LABELID	Long	LABELID
FACTORID	Long	FACTORID
FACTOR_NAME	Char[52]	FNAME
STUDYID	Long	STUDYID
TRAITID	Long	TRAITID
SCALEID	Long	SCALEID
METHOD_ID	Long	TMETHID
LEVEL_TYPE	Char[2]	LTYPE

DMS_VARIATE Structure

Element Name	Type	Database Field Name
VARIATID	Long	VARIATID
VARIATE_NAME	Char[52]	VNAME
VARIATE_TYPE	Char[4]	VTYPE
STUDYID	Long	STUDYID
TRAITID	Long	TRAITID
SCALEID	Long	SCALEID
METHOD_ID	Long	TMETHID
DATA_TYPE	Char[2]	DTYPE

DMS_DATAN Structure

Element Name	Type	Database Field Name
OBSERVATION_UNIT	Long	OUNITID
VARIATID	Long	VARIATID
DATA_VALUE	Double	DVALUE

DMS_DATAC Structure

Element Name	Type	Database Field Name
OBSERVATION_UNIT	Long	OUNITID
VARIATID	Long	VARIATID
DATA_VALUE	Char[256]	DVALUE

DMS_LEVELC Structure

Element Name	Type	Database Field Name
LABELID	Long	LABELID
FACTORID	Long	FACTORID
LEVELNO	Long	LEVELNO
LEVEL_VALUE	Char[256]	LVALUE

DMS_LEVELN Structure

Element Name	Type	Database Field Name
LABELID	Long	LABELID
FACTORID	Long	FACTORID
LEVELNO	Long	LEVELNO
LEVEL_VALUE	Double	LVALUE

EFFECT Structure

Element Name	Type	Database Field Name
REPRESENTATION_NO	Long	REPRESNO
FACTORID	Long	FACTORID
EFFECTID	Long	EFFECTID

DMS_VEFFECT

Element Name	Type	Database Field Name
REPRESENTATION_NO	Long	REPRESNO
VARIATID	Long	VARIATID

DMS_OINDEX Structure

Element Name	Type	Database Field Name
OUNITID	Long	OUNITID
FACTORID	Long	FACTORID
LEVELNO	Long	LEVELNO

DMS_TRAIT Structure

Element Name	Type	Database Field Name
TID	Long	TID
TRAITID	Long	TRAITID
TRAIT_NAME	Char[52]	TRNAME
TRAIT_ABBR	Char[8]	TRABBR
TR_NAME_STAT	Long	TNSTAT
SCALEID	Long	SCALEID
METHOD_ID	Long	TMETHID

DMS_SCALE Structure

Element Name	Type	Database Field Name
SCALEID	Long	SCALEID
TRAITID	Long	TRAITID
SCALE_NAME	Char[32]	SCNAME
SCALE_TYPE	Char[2]	SCTYPE

DMS_TMETHOD Structure

Element Name	Type	Database Field Name
METHOD_ID	Long	TMETHID
TRAITID	Long	TRAITID
METHOD_NAME	Char[52]	TMNAME
METHOD_ABBR	Char[8]	TMABBR

DMS_SCALECON

Element Name	Type	Database Field Name
SCALEID	Long	SCALEID
SLEVEL	Long	SLEVEL
ELEVEL	Long	ELEVEL

DMS_SCALEDIS

Element Name	Type	Database Field Name
SCALEID	Long	SCALEI
VALUE	Char[24]	VALUE
VALDESC	Char[256]	VALDESC

DMS_NumVALUE Structure

Element Name	Type
ounitid	Long
traitid	Long
scaleid	Long
tmethid	Long
nvalue	Double

DMS_CharVALUE Structure

Element Name	Type
ounitid	Long
traitid	Long
scaleid	Long
tmethid	Long
cvalue	Char[256]

Source

Element Name	Type
factorid	Long
levelno	Long

DMS_DMSATTR

Element Name	Type	Database Field Name
ATTRIBUTE_ID	Long	DMSATID
ATTRIBUTE_TYPE	Long	DMSATYPE
TABLE_NAME	Long	DMSATAB
RECORDID_IN_TABLE	Long	DMSATREC

IMS DATA STRUCTURES

IMS_LOT Structure

Element Name	Type	Database Field Name
LOTID	Long	LOTID
LOTUSER	long	USERID
ETYPE	Char[16]	ETYPE
EID	Long	EID
LOCID	Long	LOCID
SCALE	Long	SCALEID
STATUS	Long	STATUS
SOURCEID	Long	SOURCEID
COMMENTS	Char[256]	COMMENTS

IMS_TRANSACTION Structure

Element Name	Type	Database Field Name
TRNID	Long	TRNID
TRNUSER	Long	USERID
LOTID	Long	LOTID
TRNDATE	Long	TRNDATE
TRNSTAT	Long	TRNSTAT
CMTDATE	Long	CMTDATE
COMMENTS	Char[256]	COMMENTS
TRNQTY	Double	TRNQTY
PREVAMOUNT	Double	PREVAMOUNT
SOURCETYPE	Char[12]	SOURCETYPE
SOURCEID	Long	SOURCEID
RECORDID	Long	RECORDID

BIBREF DATA STRUCTURE

Element name	Type	Database Field Name (Table 3.8.4)
REFID	long	REFID
PUBTYPE	long	PUBLICATION_TYPE
PUBDATE	long	PUBLICATION_DATE
AUTHORS	Char[100]	AUTHOR_NAME
EDITORS	Char[100]	EDITOR_NAME
ANALYT	Char[255]	ANALYT
MONOG	Char[255]	MONOG
SERIES	Char[255]	SERIES
VOLUME	Char[10]	VOLUME
ISSUE	Char[10]	ISSUE
PAGECOL	Char[25]	PAGECOL
PUBLISH	Char[50]	PUBLISH
PUBCITY	Char[30]	PUBCITY
PUBCNTRY	Char[75]	PUBCNTRY

GEMS DATA STRUCTURE

GEMS_INFO structure

Element name	Type	Database Field Name
GOBJID	LONG	GOBJID
GNVAL	CHAR[256]	GNVAL
GOBJTYPE	CHAR[256]	GOBJTYPE
MARKERID	LONG	MARKERID

GEMS_MARKER_DETECTOR structure

Element name	Type	Database Field Name
MDID	LONG	MDID
MATYPE	CHAR[256]	MATYPE
FPRIMER	CHAR[256]	FPRIMER
RPRIMER	CHAR[256]	RPRIMER
LMID	LONG	MARKERID
MAUID	LONG	MAUID
MAREF	LONG	MAREF
MINALLELE	LONG	MINALLELE
MAXALLELE	LONG	MAXALLELE

GEMS_MV structure

Element name	Type	Database Field Name
MVID	LONG	MVID
MARKERID	LONG	MARKERID
MVTYPE	LONG	MVTYPE
MWT	DOUBLE	MWT
MDID	LONG	MDID
LMVID	LONG	LMVID
MVUID	LONG	MVUID
MVREF	LONG	MVREF

GEMS_NAME structure

Element name	Type	Database Field Name
GNID	LONG	GNID
GOBJID	LONG	GOBJID
GOBJTYPE	CHAR[256]	GOBJTYPE
GNTYPE	LONG	GNTYPE
GNSTAT	LONG	GNSTAT
GNUID	LONG	GNUID
GNVAL	CHAR(256)	GNVAL
GNLOCN	LONG	GNLOCN
GNDATE	LONG	GNDATE
GNREF	LONG	GNREF

GEMS_COMPONENT structure

Element name	Type	Database Field Name
CID	LONG	CID
CONDID	LONG	CONDID
COMID	LONG	COMID
COMVAL	CHAR(256])	GNTYPE
PID	LONG	PID
COMTYPE	CHAR(256)	COMTYPE
COMGRP	CHAR(256)	COMGRP
COMUID	LONG	COMUID
COMREF	LONG	COMREF

GEMS_PD_COMP structure

Element name	Type	Database Field Name
PD_COMP	LONG	PD_COMP
PDID	LONG	PDID
CID	LONG	CID

GEMS_PROP structure

Element name	Type	Database Field Name
PID	LONG	PID
PROPID	LONG	PROPID
PROPNAME	CHAR(256)	PROPNAME
SCALEID	LONG	SCALEID
METHID	LONG	METHID
PROPGRP	CHAR(256)	PROPGRP

GEMS_PD structure

Element name	Type	Database Field Name
PDID	LONG	PDID
CONDID	LONG	CONDID
MDID	LONG	MDID

GEMS_CONDITION structure

Element name	Type	Database Field Name
CONID	LONG	CONID
CONDNAME	CHAR(256)	CONDNAME

PD_COMP_INFO structure

Element name	Type	Database Field Name
CID	LONG	CID
CONDITION	LONG	CONDITION
PDID	LONG	PDID

GEMS_SCALE structure

Element name	Type	Database Field Name
SCALEID	LONG	SCALEID
SCNAME	CHAR(256)	SCNAME
PROPID	LONG	PROPID
SCTYPE	CHAR(256)	SCTYPE

GEMS_METHOD structure

Element name	Type	Database Field Name
METHID	LONG	METHID
MNAME	CHAR(256)	MNAME
MABBR	CHAR(256)	MABBR
MDESC	CHAR(256)	MDESC

PROP_INFO structure

Element name	Type	Database Field Name
PID	LONG	PID
MNAME	CHAR(256)	MNAME
SNAME	CHAR(256)	SNAME
PNAME	CHAR(256)	PNAME
PGRPNAME	CHAR(256)	PGRPNAME

GEMS_LOCUS structure

Element name	Type	Database Field Name
LOCUSID	LONG	LOCUSID
CHROMOSOME	CHAR(256)	CHROMOSOME
POSITION	CHAR(256)	POSITION

SUPPORTING TABLES

SUP_PERSONS structure

Element name	Type	Database Field Name
PERSONID	LONG	PERSONID
FNAME	CHAR[24]	FNAME
LNAME	CHAR[52]	LNAME
IONAME	CHAR[16]	IONAME
INSTITID	long	INSTITID
PTITLE	CHAR[28]	PTITLE
PONAME	char[52]	PONAME
PLANGU	LONG	PLANGU
PPHONE	CHAR[24]	PPHONE
PEXTENT	CHAR[24]	PEXTENT
PFAX	CHAR[24]	PFAX
PEMAIL	CHAR[44]	PEMAIL
PROLE	LONG	PROLE
SPERSON	LONG	SPERSON
EPERSON	LONG	EPERSON
PSTATUS	LONG	PSTATUS
CONTACT	CHAR[256]	CONTACT

SUP_INSTITUTE structure

Element name	Type	Database Field Name
INSTITID	LONG	INSTITID
PINSID	LONG	PINSID
INSNAME	CHAR[152]	INSNAME
INSACR	CHAR[24]	INSACR
INSTYPE	LONG	INSTYPE
STREET	char[128]	STREET
POSTBOX	CHAR[28]	POSTBOX
CITY	CHAR[36]	CITY
STATEID	LONG	STATEID
CPOSTAL	CHAR[12]	CPOSTAL
CNTRYID	LONG	CNTRYID
APHONE	char[28]	APHONE
AFAX	CHAR[28]	AFAX
AEMAIL	CHAR[44]	AEMAIL
WEBURL	CHAR[64]	WEBURL
SINS	LONG	SINS
EINS	LONG	EINS
ICHANGE	LONG	ICHANGE

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

DMS_commitData

DMS_commitData will permanently write all changes to the database made by calling add or change functions.

Syntax

DMS_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.

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

IMS_commitData

IMS_commitData will permanently write all changes to the IMS database made by calling add or change functions.

Syntax

IMS_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.

GENE MANAGEMENT SYSTEM DATABASE ACCESS FUNCTIONS

GEMS_openDatabase

GEMS_openDatabase establishes connection to the GEMS database using the information specified in the initialization file identified by the argument szInifile. The information read from this file are Data source names, DBMS user IDs and pass words needed to connect.

Syntax

long GEMS_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)

GEMS_closeDatabase

GEMS_closeDatabase closes connection to GEMS database. The function also frees up allocated memory of handlers associated with it.

Syntax (Procedure)

void GEMS_closeDatabase()

Arguments

No arguments

Returns

No return value

GEMS_commitData

GEMS_commitData will permanently write all changes to the GEMS database made by calling add or change functions.

Syntax

GEMS_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.

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 (see also the GMS_standardName function ). 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 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_findDescendant

GMS_findDescendant searches the GPID1 and GPID2 fields of the GERMPLASM Table and the PID field of the OTHER PROGENITORS Table for the given gid. After a successful call to the function, descendant will contain the germplasm record of a derivative or offspring of the target germplasm and progNo will contain the number of the progenitor that matches GID.

Note

This routine calls GMS_applyChanges (6.4.10) internally to update the germplasm record before returning.

Syntax

long GMS_findDescendant(gid, descendant, progNo, fOpt);

Arguments

Argument	Type	Use	Description
Gid	long	input	GID for which descendants are sought
descendant	GMS-germplasm*	output	Pointer to a Germplasm record which will contain the germplasm data for a descendant of GID
progNo	long*	output	Number of the progenitor which matches GID
fOpt	long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Note

GMS_findDescendant checks whether progenitor progNo has been changed through a local attribute before returning a value and it checks for progenitors which have been changed to gid by local change attributes.

GMS_findGermplasm

GMS_findGermplasm will retrieve germplasm records for all germplasm matching specified criteria. The first argument of GMS_findGermplasm is a pointer to a GMS_Germplasm structure. All elements of the structure must be set to valid values or zeros before calling the function with parameter fOpt=FIND_FIRST. This sets a search template restricting the search to records with fields matching the valid values. The first match is returned if fOpt = FIND_FIRST and the next matching location is returned if fOpt = FIND_NEXT

Syntax

long GMS_findGermplasm(germData, fOpt)

Arguments

Argument	Type	Use	Description
germData	GMS_Germplasm *	Input/ output	Enters with the name-string to search, returns with the location details of the next match
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GMS_findCIDSID

GMS_findCIDSID searches for ICIS GID, CIMMYT CID and SID depending on the given parameters. If CID and/or SID codes are given, it retrieves the corresponding GID. If GID is given, CID and SID are returned. FIND_FIRST and FIND_NEXT are valid find options if CID is the input parameter. If CID and SID are provided, the find option should be FIND_SPECIFIC=2. If GID is the input parameter, FIND_FIRST option is used.

Syntax

long GMS_findCIDSID(CID,SID,GID, fOpt)

Arguments

Argument	Type	Use	Description
CID	long	Input/ output	The CID to search if input parameter or the CID returned by the function if GID is given.
SID	long	Input/ output	The SID to search if input parameter together with CID or the SID returned by the function if GID or CID is given.
GID	long	Input/ output	The GID to search if input parameter or the GID returned by the function if CID and/or SID are given.
fOpt	long	input	Either FIND_FIRST(0) or FIND_NEXT(1) if CID is given; FIND_FIRST(0) if GID is given; FIND_SPECIFIC(2) if CID and SID are given.

Note:

If the GERMPLSM table being accessed does not have CID and SID, the function returns GMS_INVALID_DBSTRUCTURE;

GMS DATA RETRIEVAL functions

GMS_getGermplasmRecord

GMS_getGermplasmRecord retrieves data from the GERMPLASM table with GERMPLASM_ID equal to gid in structure germData. The user must check the return status and the REPLACE field of germData for replaced or deleted germplasm and take appropriate action. No check is made in the local database for change or replace attributes. These can be applied by calling GMS_applyChanges (6.4.10).

Syntax

long GMS_getGermplasmRecord (gid, germData)

Arguments

Argument	Type	Use	Description
gid	long	input	The GERMPLASM_ID to search
germData	GMS_Germplasm *	output	Address of a GMS_Germplasm record

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The GERMPLASM tables will be searched for the record with GERMPLASM_ID equal to gid. It is not possible for the search to have multiple results because the GERMPLASM_ID is unique across the two data sources (Central and Local GMS). It returns GMS_NO_DATA if there is no GERMPLASM record with GERMPLASM_ID (gid). If the record has been deleted or replaced (GRPLCE=gid for deleted, GRPLCE= <replacement gid> for replace) the function returns the deleted or replaced germplasm record and GMS_NO_DATA. It returns GMS_ERROR if any internal ODBC function call fails.

GMS_getGermplasm

GMS_getGermplasm retrieves data from the GERMPLASM table with GERMPLASM_ID equal to gid in structure germData.

Syntax

long GMS_getGermplasm (gid, germData)

Arguments

Argument	Type	Use	Description
gid	long	input	The GERMPLASM_ID to search
germData	GMS_Germplasm *	output	Address of a GMS_Germplasm record

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Note

This routine calls GMS_applyChanges (6.4.10) internally to update the germplasm record before returning.

Comments

See GMS_getGermplasmRecord comments.

GMS_getGermplasm2

GMS_getGermplasm2 retrieves all data from the GERMPLASM table and data for the preferred name from the NAMES table for germplasm gid or for its replacement if it is replaced. The function does not return data if germplasm gid is deleted. The germplasm data is returned in argument germData, the name data in argument nameData and the preferred name in szName. With GMS_getGermplasm2 the user only needs to check the return status for deleted germplasm.

Note

GMS_getGermplasm2 checks the local CHANGES table for any replace or change attributes by calling GMS_applyChanges internally. If it finds them it applies the specified deletion, replacement or change before returning the data. This means that a local user can specify changes to central records and all applications that use this function will show the effect of those changes.

The function updates the name record based on the modification stored in the CHANGES table.

Syntax

long GMS_getGermplasm2 (gid, germData, nameData, szName, nszName)

Arguments

Argument	Type	Use	Description
gid	long	input	The GERMPLASM_ID to search
germData	GMS_Germplasm *	output	Address of a GMS_Germplasm record
nameData	GMS_NameData*	output	Address of a GMS_NameData structure to contain details of the preferred name.
szName	char*	output	Address of a string variable to contain the preferred name as a null terminated string
nszName	long	input	Maximum length of the szName

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

If germplasm gid has been deleted (GRPLCE=GID), GMS_getGermplasm2 sets the GERMPLASM_ID element of argument germData to zero and returns GMS_NO_DATA. If the germplasm gid has been replaced (GRPLCE= <replacement gid>) the function returns data for the replaced germplasm and not germplasm GID. In this case the GERMPLASM_ID element of germData will have a different value to gid. The routine also checks the local ATTRIBUTES table for any change or replacement attributes for the germplasm record and if it finds then the function applies the changes. If there is an ODBC error the function returns GMS_ERROR.

GMS_getGermplasm3

GMS_getGermplasm3 works exactly like GMS_getGermplasm2 but with additional return argument for the abbreviation.

Note

See GMS_getGermplasm2 note.

Syntax

long GMS_getGermplasm3 (gid, germData, nameData, szName, nszName, szAbbreviation)

Arguments

Argument	Type	Use	Description
gid	long	input	The GERMPLASM_ID to search
germData	GMS_Germplasm *	output	Address of a GMS_Germplasm record
nameData	GMS_NameData*	output	Address of a GMS_NameData structure to contain details of the preferred name.
szName	char*	output	Address of a string variable to contain the preferred name as a null terminated string
nszName	long	input	Maximum length of the szName
szAbbreviation	char*	output	Address of a string variable to contain the preferred abbreviation name as a null terminated string

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

GMS_getGermplasm3 does not specify the length of the szAbbreviation for the routine expects it to be at least 9 bytes in length (>=9).

See GMS_getGermplasm2 comments.

GMS_getProgenitorID

GMS_getProgenitorID retrieves the GERMPLASM_ID of iProgen^th progenitor of germplasm with GERMPLASM_ID gid in variable pGid.

Syntax

long GMS_getProgenitorID( gid, iProgent, pGid)

Arguments

Argument	Type	Use	Description
gid	long	input	The GERMPLASM_ID to search
iProgen	long	input	No of the parent whose ID is required
pGid	long *	output	Address of a long integer variable to contain the GERMPLASM_ID of the iProgenth progenitor

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

Returns GMS_NO_DATA when there is no iProgen^th progenitor. Returns GMS_ERROR if any internal ODBC function call fails.

Although GMS_getProgenitorID can be called with iProgen equal to 1 or 2 it is usually not necessary as the germplasm data containing these parent IDs is often already available, and if not it is still more efficient to call it from the GMS_getGermplasm function. The routine checks the local ATTRIBUTES table for any changes in iProgen^th progenitor.

See GMS_getGermplasm2 comments.

GMS_getNameRecord

GMS_getNameRecord retrieves data from the NAMES table for the given nid in structure nameData. The user must check the return NSTAT field of nameData for deleted name and take appropriate action.

Syntax

long GMS_getNameRecord (nameData,szName,nszName)

Arguments

Argument	Type	Use	Description
nameData	GMS_Name *	Input/output	Address of a GMS_Name record
szName	Char *	output	Address of a string variable to contain the name as a null terminated string
nszNamr	long	input	The length of the szName string.

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GMS_getName

GMS_getName will retrieve all names associated with germplasm having specified germplasm ID and name STATUS or name TYPE. GMS_getName requires that the target germplasm ID is stored in the GERMPLASM element of the nameData argument (6.1.2b) and the STATUS and TYPE elements should be set to zero or a desired value before calling the function. If TYPE and STATUS are zero, the function will retrieve all names of the target germplasm. If STATUS is non zero only names with matching status values are returned. If STATUS is zero and TYPE is non zero then only names with matching TYPE are returned. If fOpt equals FIND_FIRST the function returns the Name with the lowest value of TYPE. Subsequent calls with fOpt equal to FIND_NEXT return names in order of value of TYPE. Any call that fails to find a name returns GMS_NO_DATA.

Syntax

long GMS_getName(nameData, szName, nszName, fOpt)

Arguments

Argument	Type	Use	Description
nameData	GMS_NameData*	input/output	Address of a GMS_NameData record
szName	char *	output	Address of NULL terminated string containing the NAME
nszName	long	input	Maximum size of szName in bytes
fOpt	long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The germplasm ID and, if required, the name type of the germplasm for which names are required must be loaded into the GERMPLASM and TYPE elements of the GMS_NameData argument if fOpt=FIND_FIRST. On return this argument contains all the other relevant fields for the returned name. If no name is found the argument szName will contain a NULL string. If the function is called with bad parameters or there was a problem accessing the database, the function will return GMS_ERROR. GMS_getName returns name data for deleted or replaced germplasm without warning.

GMS_getAttribute

GMS_getAttribute will retrieve all attributes associated with germplasm having specified germplasm ID and attribute TYPE. GMS_getAttribute requires the germplasm ID and attribute type are stored in the GERMPLASM and TYPE fields of the attribute argument before calling the function. If TYPE is zero the function will retrieve all attributes of a germplasm regardless of attribute type. If fOpt equals FIND_FIRST the function returns the attribute with the lowest value of attribute TYPE. Subsequent calls with fOpt equal to FIND_NEXT return attributes in order of TYPE value. Any call that fails to find an attribute returns GMS_NO_DATA.

Syntax

long GMS_getAttribute(attribute, szAVal, nszAVal, fOpt)

Arguments

Argument	Type	Use	Description
attribute	GMS_Attribute*	input/output	Address of a GMS_Attribute record
szAVal	char *	output	Address of NULL terminated string to place the attribute value
nszAVal	Long	input	Length/Size of szAVal
fOpt	Long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The principle of using GMS_getAttribute is almost the same as GMS_getName. The only difference is that the first argument is GMS_Attribute structure and the ATTRIBUTE table is searched. If the function is called with bad parameters or there was a problem accessing the database, the function will return GMS_ERROR. GMS_getAttribute returns attribute data for deleted or replaced germplasm without warning.

GMS_getMethod

GMS_getMethod retrieves details of a method from the METHODS table. The first argument of GMS_getMethod is a pointer to a GMS_Method structure (6.1.2d). If the METHOD_ID element is not zero when the function is called then the details for the corresponding method are retrieved. If it is zero then the function returns details for the first method if fOpt = FIND_FIRST or for the next available method if fOpt = FIND_NEXT. Any call which fails to find a method information returns GMS_NO_DATA.

Syntax

long GMS_getMethod(method, szMDesc,nszMDesc, fOpt)

Arguments

Argument	Type	Use	Description
method	GMS_Method*	input/ output	Address of a GMS_Method structure to contain method details
szMDesc	char *	output	Address of a string variable to contain the NULL terminated method description
nszMDesc	Long	input	Maximum size of szMDesc in bytes
fOpt	Long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The principle of using GMS_getMethod is almost the same as GMS_getAttribute. If the function is called and there was a problem accessing the database, the function will return GMS_ERROR. If szMDesc is NULL and cMDesc is zero then GMS_getMethod will not retrieve the method description.

GMS_applyChanges

GMS_applyChanges returns the germplasm record after applying the changes as recorded in the local attributes table. This allows a local user to register changes to central germplasm and have those changes reflected immediately in all analysis applications that use the DLL. The changes are checked and physically made in the central database at update.

Syntax

long GMS_applyChanges(germData)

Arguments

Argument	Type	Use	Description
GermData	GMS_Germplasm *	input/ output	Address of a GMS_Germplasm record

Returns

GMS_ERROR,GMS_SUCCESS

Comments

GMS_applyChanges searches the local ATTRIBUTS table where GID matches germData.gid and ATYPE value is either REPLACE (101) or CHANGE(102). GMS_applyChanges first looks for REPLACE attributes and gets the replacement germplasm. Next it looks for CHANGE attributes and applies the changes in chronological order with the most recent change last. GMS_applyChanges is called internally for central germplasm (positive gids) by the following routines before returning the germplasm data: GMS_getGermplasm2, GMS_getGermplasm3, GMS_getDescendant, GMS_findName, GMS_findName2, and GMS_findName3 GMS_findPreferredName.

Functions to add data to the local database

GMS_addGermplasm

GMS_addGermplasm will add new germplasm and name information to the GMS database according to the information in the arguments. If the germplasm is produced by a generative method with more than 2 progenitors then germplasm IDs for progenitors after the second are contained in array argument aPID.

The GERMPLASM_ID field of the germData argument and the GERMPLASM field of the nameData argument must be zero on input, and will be set to the new germplasm ID value on exit.

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_addGermplasm( germData, nameData, szPName, aPID)

Arguments

Argument	Type	Use	Description
germData	GMS_Germplasm *	input/ output	Address of a GMS_Germplasm record
nameData	GMS_NameData *	input/ output	Address of a GMS_NameData record
szPName	char *	input	Address of NULL terminated string which contains the PREFERRED_NAME
aPID	long *	input	Address of an array of Parent GIDs. NULL if the number of progenitors is less than or equal to two.

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_ACCESS

Comments

The following fields of the germData structure should be properly populated with valid values before calling the function:

• METHOD – number of method used corresponding to METHOD_ID on the METHODS table;

• NO_PROGENITORS - for a derivative process or the number of parents for a generative process;

• PROGENITOR_ID1 - Group ID for a derivative process or the ID of the first parent (usually the female) for a generative process. (Zero if unknown);

• PROGENITOR_ID2 - Source ID for a derivative process or the ID of the second parent for a generative process. (Zero if unknown);

• LOCATION - Location ID for the breeding or collection location (Zero if unknown);

• DATE - Date as YYYMMDD ( 0 if unknown);

• REFERENCE – reference number (missing id unknown).

The elements GERMPLASM_ID, USER and REPLACE will be populated by the function.

The string szPname may not be NULL and the following fields of the Name structure should be populated with valid values before calling the function:

• TYPE – name type number from the UDFIELDS table;

• STATUS - name status (preferred or not) and data storage mode (Table 3.8.3).

• LOCATION – name location number, often the same as LOCATION in Germ;

• DATE - date the germplasm was named, same form as DATE in Germ;

• REFERENCE - if there is one available.

The GERMPLASM and USER elements of Name will be populated by the function.

GMS_addName

GMS_addName adds new name szPName for germplasm specified by the GERMPLASM field in the nameData structure.

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_addName(nameData, szPName)

Arguments

Argument	Type	Use	Description
nameData	GMS_NameData *	input	Address of a GMS_NameData record
szPName	Char *	input	Address of NULL terminated string to place the name

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The string szPname may not be NULL and the following fields of the Name structure should be properly populated with valid values before calling the function:

• GERMPLASM – valid germplasm ID

• TYPE - the type of name;

• STATUS - name status (preferred or not) and data storage type;

• LOCATION

• DATE

• REFERENCE - if there is one available.

GMS_addAttribute

GMS_addAttribute adds new attribute with value szAVal for germplasm defined by the GERMPLASM_ID field in the attribute structure.

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_addAttribute(attribute, szAVal)

Arguments

Argument	Type	Use	Description
attribute	GMS_Attribute *	input/ output	Address of a GMS_Attribute structure
szAVal	char *	input	Address of NULL terminated string to place the value of the attribute

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The string szAVal should not be a NULL string and the following fields of the attribute structure should be properly populated with values before calling the function:

• GERMPLASM – valid germplasm ID

• TYPE - the type number of the attribute (from the UDFLDS Table);

• LOCATION

• DATE

• REFERENCE - if there is one available.

GMS_addChanges

GMS_addChanges adds one record to the local CHANGES table specifying a change made to germplasm data.

Syntax

long GMS_addChanges (changeData,szDesc)

Arguments

Argument	Type	Use	Description
changeData	GMS_Changes *	Input/output	Address of a GMS_Changes structure
szDesc	char *	Input	Description of the change

Returns

GMS_SUCCESS, GMS_ERROR

Comment

The fields CTABLE, CFIELD, CRECORD, CFROM, CTO and CGROUP should be properly initialized. The routine will automatically assign values to CID, CUID, CDATE, and CTIME fields.

Functions to correct LOCAL GMS records

GMS_setGermplasm

GMS_setGermplasm changes the value of any field in the local GERMPLASM table except the PREFERRED_NAME, NAME_EXTENSION and ABBREVIATION fields. Only the central database administrator can change field values in the Central database. However, a local user can request such changes by adding SETGERM attributes for central germplasm records to the local attributes table.

Syntax

long GMS_setGermplasm(germData)

Arguments

Argument	Type	Use	Description
germData	GMS_Germplasm*	Input	Pointer to a GMS-Germplasm structure containing correct values for all fields whether they are to be changed or not.

Returns

GMS_SUCCESS, GMS_ERROR

Comments

This function can be used to correct certain fields in the local GERMPLASM table. A call with positive GID will result in a GMS_ERROR return.

GMS_setProgenitorID

GMS_setProgenitorID changes the value of a progenitor ID for germplasm GID in the local GMS database. If argument iProgen has value 1 or 2, the value is changed on the germplasm record, otherwise it is changed in the PROGENITORS table.

Syntax

long GMS_setProgenitorID(gid, iProgen,pGid)

Arguments

Argument	Type	Use	Description
gid	long	input	GID of germplasm for which progenitor ID is to be set
iProgen	long	input	Progenitor number to be set
pGid	long	input	GID to be stored as iProgenth progenitor of germplasm GID

Returns

GMS_SUCCESS, GMS_ERROR

Comments

This function can be used to change the value of a progenitor ID either to another valid GID or to zero that indicates missing information on the progenitor. If iProgen is 1 or 2 the value could be changed with the GMS_setGermplasm function, but GMS_setProgenitorID also works, and is the only way to change the value if iProgen >2. If gid is positive the function returns GMS_ERROR.

GMS_setPreferredName

GMS_setPreferredName sets an existing, ASCII name as the preferred name of a germplasm and resets the name_status of the current preferred name to zero.

Syntax

long GMS_setPreferredName (nameData,szPName)

Arguments

Argument	Type	Use	Description
nameData	GMS_NameData*	input	Pointer to a GMS_NameData structure containing the name data of the existing name which is to be set as the preferred name
szPName	char*	input	Pointer to a character variable containing the null terminated existing name to be set as the preferred name

Returns

GMS_SUCCESS , GMS_ERROR

Comments

The new preferred name must exist on the NAMES table before the call to GMS-setPreferredName. The GERMPLASM_ID, NAME_USER, NVAL and NEXT fields should uniquely index the proposed preferred name. It must be an ASCII name, and not the current preferred name i.e. it must have NAME_STATUS 0 or 2. Any other value results in an error return, GMS_ERROR. If the proposed preferred name is already the preferred abbreviation then it is re-set as the preferred name. The NAME_STATUS of the existing preferred name is changed to 0 on the NAMES table. If the GERMPLASM_ID field of the nameData argument is positive the function returns GMS_ERROR.

GMS_setPreferredAbbr

GMS_setPreferredAbbr sets an existing, ASCII name as the preferred abbreviation of a germplasm.

Syntax

long GMS_setPreferredAbbr(namedata,szName)

Arguments

Argument	Type	Use	Description
namedata	GMS_NameData*	input	Pointer to a GMS_NameData structure containing the name data of the existing name which is to be set as the preferred abbreviation
szName	char*	input	Pointer to a character variable containing the null terminated existing name to be set as the preferred abbreviation

Returns

GMS_SUCCESS , GMS_ERROR

Comments

The proposed preferred abbreviation must exist on the NAMES table before the call to GMS_setPreferredAbbr. The GERMPLASM_ID, NAME_USER and NVAL fields should uniquely index the proposed preferred abbreviation. It must be an ASCII name of less than eight characters and it may not be the current preferred name or preferred abbreviation i.e. it must have NAME_STATUS 0. Failure of these conditions results in an error return, GMS_ERROR . The NAME_STATUS of any existing preferred abbreviation is changed to 0 on the NAMES table. If the GERMPLASM_ID field of the namedata argument is positive the function returns GMS_ERROR.

GMS_setName

GMS_setName changes the value of any field in the local NAMES given the NID.

Syntax

long GMS_setName(nameData,szName,nszName)

Arguments

Argument	Type	Use	Description
nameData	GMS_NameData *	input	Pointer to a GMS-NameData structure containing correct values for all fields whether they are to be changed or not.
szName	Char *	input	Address of NULL terminated string to place the name
nszName	Long	input	Maximum size of the szName string

Returns

GMS_SUCCESS, GMS_ERROR

Comments

This function can be used to correct certain fields in the local NAMES table. A call with positive NID will result in a GMS_ERROR return.

4.4.4 GMS_setAttribute

GMS_setAttribute changes the value of any field in the local ATTRIBUT table given the AID.

Syntax

long GMS_setAttribute(attrData,szAval)

Arguments

Argument	Type	Use	Description
attrData	GMS_Attribute*	input	Pointer to a GMS_Attribute structure containing correct values for all fields whether they are to be changed or not.
szAval	Char *	input	Address of NULL terminated string to contain the attribute value

Returns

GMS_SUCCESS, GMS_ERROR

Comments

This function can be used to correct certain fields in the local ATTRIBUT table. If an attribute is to be deleted, change the ATYPE = 999.

BASIC GMS FUNCTIONS

GMS_generateTree

GMS_generateTree retrieves preferred names and GIDs from the GERMPLASM table for all generative progenitors in the pedigree of germplasm gid down to a specified number of levels or until no further progenitors are known.

Syntax:

long GMS_generateTree(gid,level,szBuffer,bufsz,aID,naID)

Arguments

Argument	Type	Use	Description
gid	long	input	Progenitor ID from which the tree will generate (as the root)
level	long	input	Desired maximum level of the tree
szBuffer	char *	output	Points to a buffer that receives a string representing the genealogical tree. The buffer is filled with one or more null-terminated strings (representing one line on the screen); the last string is followed by a second null character.
nszBuffer	long	input	Specifies the size, in characters, of the buffer pointed to by the szBuffer parameter.
aID	long *	output	Contains array of GIDs corresponding to the germplasm on each line of szBuffer
naID	long	input	Maximum number of entries in aID

Returns

GMS_SUCCESS ,GMS_ERROR or GMS_MORE_DATA

Comments

szBuffer of size nszBuffer should be large enough to hold the whole generated tree. The routine will return GMS_MORE_DATA if the szBuffer does not contain the entire generated tree. Test the result for either GMS_SUCCESS or GMS_MORE_DATA. Argument aID returns with the list of GIDs corresponding to each line of the tree so that extra information can be extracted from the database and displayed on the tree as required. If there are more lines (entries) in the tree than spaces in aID (naID) then GMS_generateTree returns GMS_MORE_DATA.

The tree is displayed horizontally. A line starting with > indicates that the entry on the line above is a derivative of the entry on the current line. A line starting with + indicated that the entry on the current line is a generative progenitor of the entry above the +. Female progenitors are listed above male progenitors. ** following an entry name indicates that that entry has already been expanded in the current tree. < following an entry indicates that there is further pedigree information available on that entry.

Code Example:

The following code will display the generated tree:

CODEEXAMPLE OUTPUT

	char *p;				IR8
	p = szBuffer;				> IR8
			while (*p!=’\0’)			+--- PETA
				{ // dump to the console		| > PETA
			printf("s \n",p);			| +---CINA
				p = p + strlen(p)+1;		| +---LATISAIL
	}					+--- DEE-GEO-WOO-GEN

GMS_crossExpansion:

GMS_crossExpansion interrogates the GMS recursively to generate a Purdey cross expansion for germplasm gid. The expansion terminates after level generations or whenever a progenitor has a name of type ntype. The cross expansion is returned in argument szBuffer, and the list of GIDs for elements in the cross expansion (from left to right) is returned in array aID.

Syntax

long GMS_crossExpansion(gid,level,ntype,szBuffer,nszBuffer,aID,naID)

Arguments

Argument	Type	Use	Description
gid	long	input	germplasm id
level	long	input	level of expansion
ntype	Long	Input	Name type (i.e., 7-preferred name, 6-preferred abbreviation, etc.)
szBuffer	char *	output	pointer to null terminated string containing the cross expansion string generated
nszBuffer	long	input	maximum data size szBuffer can hold (including the null terminator).
Aid	long *	output	an array of long integer containing the list of germplasm id
naID	long	input	maximum size of the idList

Returns

GMS_ERROR, GMS_SUCCESS, GMS_MORE_DATA ,GMS_NO_DATA

Comments

Progenitor’s preferred name is the default name used when ntype is zero. A generation is taken to be a generative process involving only derivative progenitors or a sequence of generative processes with the last one involving only derivative progenitors. Thus a series of back crosses is one generation (back to the original single cross) and a triple cross or double cross generation involves two generative steps.

If the input parameter ntype is specified (>0) the expansion is built from progenitors having names of the specified type or preferred names of progenitors level generations back in the pedigree, whichever occurs first.

Generative progenitors with one parent (mutations) are represented as <parent> /. And ones with more than two parents as <parent1>/[<parent2>,<parent3>, …]. GMS_crossExpansion will not expand parents other than the first one.

The routine returns GMS_MORE_DATA if either the szBuffer or idList is not large enough to hold the data. If the routine encounters a missing group ID in any source expansion of that branch it terminates with the name of that source. If it encounters a missing progenitor ID in any cross before level generations it places a query ’?’ in the cross expansion at that point and terminates expansion of that branch.

GMS_listNames

GMS_listNames searches the database for all names of germplasm gid and returns them in a null delimited test string.

Syntax

long GMS_listNames(gid,szBuffer,nszBuffer)

Arguments

Argument	type	Use	Description
gid	long	input	germplasm id
szBuffer	char *	output	pointer to null terminated string containing the list of Names
nszBuffer	long	input	maximum data size szBuffer can hold (including the null terminator).

Returns

GMS_ERROR, GMS_SUCCESS, GMS_MORE_DATA ,GMS_NO_DATA

Comments

Names in szBuffer are separated by null characters and the whole list is terminated with two null characters. The function only searches the central database when gid is positive, but it always searches the local database. The preferred name (NSTAT = 1) is placed first in the list.

GMS_computeGenerationNo

GMS_computeGenerationNo traces pedigrees through derivative and management generations and returns statistics indicating the number of each type of generation advance - derivative or management, and the last generation at which seed was harvested from a single plant or at which chromosome doubling was carried. GMS_computeGenerationNo also returns the type of method used in the last generation and/or the type of generative method most recently used. If the last generative method is a backcross, GMS_computeGenerationNo returns the number of crosses to the recurrent parent.

Syntax:

long GMS_computeGenerationNo(gid,LSPS,NGEN,MAN,NBC,LDM,MCR)

Arguments

Argument	Type	Use	Description
gid	long	input	Germplasm ID from which the generation number will be computed
LSPS	long *	output	Number of derivative generations from the cross to the last single plant selection or single seed descent (zero for F1s)
NGEN	long *	output	Total number of generations from the cross (1 for F1s)
MAN	long*	output	Number of management generations
NBC	long *	output	Backcross dosage (zero for other cross types)
LDM	Long *	output	ICIS method code for the last derivative method (zero for F1s)
MCR	long *	output	ICIS method code for the last generative method

Returns

GMS_SUCCESS ,GMS_ERROR or GMS_NO_DATA

Comments

NGEN and LSPS return with zero if there is an unknown source (GPID2=0) in any generation after the cross. This should usually be interpreted as complete inbreeding for self pollinating crops and as F1s for open pollinating species. If there are no unknown sources NGEN returns the number of derivative generations from the cross to the current generation, counting 1 for the cross and ignoring any management generations. If a double haploid method is used (method numbers 202 or 502 in Annex 2.2.b then LSPS returns minus the number of the derivative generation after the cross when this occurred otherwise LSPS returns the derivative generation number after the cross where the last single plant selection (method numbers 205, 504 in Annex 2.2.b) or single seed descent occurred (method numbers 208, 505 in Annex 2.2.b) or zero of none of these methods occur.

MAN returns the number of generations where management methods (MTYPE=’MAN’ in the METHODS Table) have been used between the group source and the current generation. NBC returns the number of crosses to a recurrent parent if the crossing method is backcross (method numbers 107 or 4 in Annex 2.2.b) otherwise NBC=0.

Code Example:

I4=GMS_computeGenerationNo(GID,LSPS,NGEN,MAN,NBC,LDM,MCR)

WRITE(0,130) LSPS,NGEN,MAN,NBC,LDM,MCR

130 FORMAT(6I8)

For IR 80000-B-B-S-B-B-B-B-B where B stands for bulk and S stands for single plant selection, this gives:

3 9 0 0 204 101

Notice that IR 80000 labels the F1, IR 80000-B labels the plot of F2s, IR 80000-B-B labels the plot of F3s and IR 80000-B-B-S represents the F4 seed from one F3 plant and labels the F4 row, ie IR 80000-B-B-S is an F3 derived F4.

GMS_getDerivativeNeighbor

GMS_getDerivativeNeighbor retrieves all germplasm in 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 than the maximum length
blnDH	long	input	1 if Double Haploid germplasm is to be excluded as part of derivative neighborhood

Note:

• Double Haploid option is not yet working very well
• Lines with derivative or management methods (GNPGS < 0) are considered.
• The algorithm is a recursion which is called n+m times

Algorithm:

1. Determine the root of the required neighborhood which is either the germplasm m backward step within the generation history of the specified target GID or its group germplasm if m is greater than generation level of the target GID
2. Starting from the root, get the immediate derived lines
3. For each retrieved line, get the succeeding derived lines
4. Repeat the 3rd step (n+m-2) times

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

LIST DLL FUNCTIONS

The GMS_openDatabase function mentioned in Section 3.1 should be called first before calling any functions mentioned in this section. The different data structures used by the functions are discussed in section 2.

FUNCTIONS ASSOCIATED TO LISTNMS TABLE

GMS_getListName

GMS_getListName retrieves a specific record from LISTNMS table for a particular value of listid field of GMS_ListName structure. To retrieve all records in the table initialize listid to zero, fOpt to FIND_FIRST for the first call and FIND_NEXT for the succeeding calls.

Syntax

long GMS_getListName(listName, fOpt)

Arguments

Argument	Type	Use	Description
listName	GMS_ListName *	input/output	Address of a GMS_ListName structure to contain the list name for the retrieved record
FOpt	long	output	either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_NO_DATA, GMS_ERROR

GMS_findListName

GMS_findListName retrieves records from LISTNMS table where the list name matches the given string szLName. Set fOpt to FIND_FIRST for the first call and FIND_NEXT for the succeeding calls.

Syntax

long GMS_getListName(szLName,listName, fOpt)

Arguments

Argument	Type	Use	Description
szLName	String	input	Address of NULL terminated string containing the name to search
listName	GMS_ListName *	input/output	Address of a GMS_ListName structure to contain the list name for the retrieved record
FOpt	long	output	either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_NO_DATA, GMS_ERROR

GMS_setListName

GMS_setListName changes the value of all the fields in the local LISTNMS table except the LISTID field for a given listid.

Syntax

long GMS_setListName(listName)

Arguments

Argument	Type	Use	Description
listName	GMS_ListName *	input	Address of a GMS_ListName structure

Returns

GMS_SUCCESS, GMS_ERROR

GMS_addListName

GMS_addListName adds one record to the LISTNMS table assigning value automatically to LISTID field.

Syntax

long GMS_addListName(listName)

Arguments

Argument	Type	Use	Description
listName	GMS_ListName *	input	Address of a GMS_ListName structure

Returns

GMS_SUCCESS, GMS_ERROR

GMS_deleteListName

GMS_deleteListName deletes one record from the LISTNMS table for a given listid.

Syntax

long GMS_deleteListName(listid)

Arguments

Argument	Type	Use	Description
listid	Long	input	value of LISTID of which LISTNAME record to delete

Returns

GMS_SUCCESS, GMS_ERROR

GMS_getListByStatus

GMS_getListByStatus retrieves records from LISTNMS table for the given list status in the GMS_ListName structure. Set fOpt to FIND_FIRST for the first call and FIND_NEXT for the succeeding calls.

Syntax

long GMS_getListByStatus(listName, fOpt)

Arguments

Argument	Type	Use	Description
listName	GMS_ListName *	input/output	Address of a GMS_ListName structure to contain the list name for the retrieved record
FOpt	Long	output	either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_NO_DATA, GMS_ERROR

FUNCTIONS ASSOCIATED WITH LISTDATA TABLE

GMS_getListData

GMS_getListData retrieves records from the LISTDATA table for given listid and gid or listid and entryid values specified in the LISTID, GID and ENTRYID fields of the GMS_ListData structure. A valid listid value must be specified, but the gid and entryid may be zero in which case all entries for the specified list will be retrieved. If gid is non zero, entryid must be zero and entries with specified listid and gid will be retrieved. If entryid is non zero, gid must be zero and the entry with the specified listid and entryid will be retrieved. fOpt should be set equal to FIND_FIRST on the first call, and FIND_NEXT in the succeeding calls. (If entryid is specified, fOpt should be FIND_FIRST since there can only be one result record.) Search parameters are set when fOpt is FIND_FIRST, and input values in the ListData argument are ignored when fOpt is FIND_NEXT.

Syntax

long GMS_getListData(listData, fOpt)

Arguments

Argument	Type	Use	Description
listData	GMS_ListData *	input/output	Address of a GMS_ListData structure
fOpt	long	output	either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR

GMS_findListData

GMS_findListData retrieves all records from the LISTDATA table for given gid value specified in the GID field of the GMS_ListData structure. fOpt should be set equal to FIND_FIRST on the first call, and FIND_NEXT in the succeeding calls. Search parameters are set when fOpt is FIND_FIRST, and input values in the ListData argument are ignored when fOpt is FIND_NEXT.

Syntax

long GMS_getListData(listData, fOpt)

Arguments

Argument	Type	Use	Description
listData	GMS_ListData *	input/output	Address of a GMS_ListData structure
fOpt	long	output	either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR

GMS_setListData

GMS_setListData changes the value of fields in the local LISTDATA table for given listid and lrecid fields of GMS_ListData structure. (Note the LISTID and LRECID fields cannot be changed.)

Syntax

long GMS_setListData(listData)

Arguments

Argument	Type	Use	Description
listData	GMS_ListData *	input	Address of a GMS_ListData structure

Returns

GMS_SUCCESS, GMS_ERROR

GMS_addListData

GMS_addListData adds one record to the LISTDATA table assigning value automatically to ENTRYID field.

Syntax

long GMS_addListData(listData)

Arguments

Argument	Type	Use	Description
listData	GMS_ListData *	input	Address of a GMS_ListData structure

Returns

GMS_SUCCESS, GMS_ERROR

GMS_deleteListData

GMS_deleteListData deletes records from the LISTDATA table for a given listid or, listid and lrecid. If lrecid is zero the function will delete all records where listid=LISTID, otherwise delete record where listid=LISTID and entryid=ENTRYID.

Syntax

long GMS_deleteListData(listid, lrecid)

Arguments

Argument	Type	Use	Description
listid	Long	input	value of LISTID of which LISTDATA record to delete
lrecid	Long	input	value of LRECID, if LRECID is not zero, with the condition above applied of which LISTDATA record to delete

Returns

GMS_SUCCESS, GMS_ERROR

USER DEFINED FIELDS AND CONSTANTS FUNCTIONS

GMS_getUDField

GMS_getUDField will retrieve details of any user-defined field from the UDFLDS table. The first argument of GMS_getUDField is a pointer to a GMS_UDField structure. If the FLDNO is not zero when the function is called then it returns the details for the corresponding user defined field. If it is zero then the function returns details for the first user defined field if fOpt = FIND_FIRST or for the next available user defined field if fOpt = FIND_NEXT. Any call which fails to get user defined field information returns GMS_NO_DATA.

Syntax

long GMS_getUDField(UDField, szFDesc, nszFDesc, fOpt)

Arguments

Argument	Type	Use	Description
UDField	GMS_UDField*	input/ output	Address of a GMS_UDField structure
szFDesc	char *	output	Address of a string variable to contain the field description as a NULL terminated string
nszFDesc	Long	input	Maximum size of szFDesc
fOpt	Long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The principle of using GMS_getUDField is almost the same as GMS_getAttribute. If the function is called and there was a problem accessing the database, the function will return GMS_ERROR.

GMS_getUDField2

GMS_getUDField2 will retrieve the allowable constant values for a column (FTYPE) of an ICIS table (FTABLE). The first argument is a pointer to a GMS_UDField structure where FTABLE and FTYPE are given. If fopt is FIND_FIRST (0), the function retrieves the first matched record. If fopt is FIND_NEXT (1), details about the succeeding matched record is retreived .Any call which fails to get user defined field information returns GMS_NO_DATA.

Syntax

long GMS_getUDField2(UDField, szFDesc, nszFDesc, fOpt)

Arguments

Argument	Type	Use	Description
UDField	GMS_UDField*	input/ output	Address of a GMS_UDField structure
szFDesc	char *	output	Address of a string variable to contain the field description as a NULL terminated string
nszFDesc	Long	input	Maximum size of szFDesc
fOpt	Long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GMS_findUDField

GMS_findUDField searches for UDFLDS record with name matching the string FNAME. The first argument is a pointer to a GMS_UDField structure where FNAME is given. If fopt is FIND_FIRST (0), the function retrieves the first matched record. If fopt is FIND_NEXT (1), details about the succeeding matched record is retreived .Any call which fails to get user defined field information returns GMS_NO_DATA.

Syntax

long GMS_findUDField(UDField, szFDesc, nszFDesc, fOpt)

Arguments

Argument	Type	Use	Description
UDField	GMS_UDField*	input/ output	Address of a GMS_UDField structure
szFDesc	char *	output	Address of a string variable to contain the field description as a NULL terminated string
nszFDesc	Long	input	Maximum size of szFDesc
fOpt	Long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

DMS DLL FUNCTIONS

INTRODUCTION

The DMS_openDatabase function mentioned should be called first before calling any functions mentioned in this section. The different data structures used by the functions are discussed in section IV.I.2.

ADD FUNCTIONS

DMS_addStudy

DMS_addStudy adds new study record in the DMS database according to the information in the STUDY argument. STUDYID is automatically assigned by the function. The name of the study should be unique. If a study with similar name already exists in the database, the function returns DMS_EXIST (-5).

Syntax

long DMS_addStudy(STUDY, szObjective)

Arguments

Argument	Type	Use	Description
STUDY	DMS_STUDY	Input	Address of the DMS_STUDY structure that contains the information to be added to the database.
szObjective	Char*	Input	The pointer to a null terminated string containing the objective of the Study

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_ERROR(-1)

DMS_addFactor

DMS_addFactor adds new factor of a given study (STUDYID) according to the information in the FACTOR argument. FACTORID is automatically assigned by the function. Factor name should be unique within a study. Hence, if a factor with similar name exists in the given study, the function returns DMS_EXIST (-5). If the STUDYID does not exist in the database, DMS_INVALID_ID (-9) is returned.

Syntax

long DMS_addFactor(FACTOR)

Arguments

Argument	Type	Use	Description
FACTOR	DMS_FACTOR	Input	Address of the DMS_FACTOR structure that contains the information to be added to the database .

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_INVALID_ID(-9),DMS_ERROR(-1)

DMS_addVariate

DMS_addVariate adds new variate of a given study (STUDYID) according to the information in the VARIATE argument. VARIATID is automatically assigned by the function. Variate name should be unique within the study. Hence, if a variate with similar name exists in the given study, the function returns DMS_EXIST (-5). If the STUDYID does not exist in the database, DMS_INVALID_ID (-9) is returned.

Syntax

long DMS_addVariate(VARIATE)

Arguments

Argument	Type	Use	Description
VARIATE	DMS_VARIATE	Input	Address of the DMS_VARIATE structure that contains the information to be added to the database .

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_INVALID_ID(-9),DMS_ERROR(-1)

DMS_addLevelN

DMS_addLevelN adds new level of a particular factor (FACTORID) having numeric type according to the information in the LEVELN argument. LEVELNO is assigned by the function and it is unique within a factor. If there is a level of similar value for that factor, DMS_EXIST is returned by the function. If the FACTORID does not exist in the database, DMS_INVALID_ID (-9) is returned.

Syntax

long DMS_addLevelN(LEVELN)

Arguments

Argument	Type	Use	Description
LEVELN	DMS_LEVELN	Input	Address of the DMS_LEVELN structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_INVALID_ID(-9),DMS_ERROR(-1)

DMS_addLevelC

DMS_addLevelC adds new level of a particular factor (FACTORID) having character type according to the information in the LEVELC argument. The LEVELNO is assigned by the function and it is unique within a factor. If there is a level of similar value for that factor, DMS_EXIST is returned by the function. If the FACTORID does not exist in the database, DMS_INVALID_ID (-9) is returned.

Syntax

long DMS_addLevelC(LEVELC)

Arguments

Argument	Type	Use	Description
LEVELC	DMS_LEVELC	Input	Address of the DMS_LEVELC structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_INVALID_ID(-9),DMS_ERROR(-1)

DMS_addDataN

DMS_addDataN adds new data value for a particular variate of numeric type according to the information in the DATAN argument. If either OUNITID or VARIATID does not exist in the database, the function returned DMS_INVALID_ID (-9).

Syntax

long DMS_addDataN(DATAN);

Arguments

Argument	Type	Use	Description
DATAN	DMS_DATAN	Input	Address of the DMS_DATAN structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_INVALID_ID(-9), DMS_ERROR(-1)

DMS_addDataC

DMS_addDataC adds new data value for a particular variate of character type according to the information in the DATAC argument. If either OUNITID or VARIATID does not exist in the database, the function returned DMS_INVALID_ID (-9).

Syntax

long DMS_addDataC(DATAC);

Arguments

Argument	Type	Use	Description
DATAC	DMS_DATAC	Input	Address of the DMS_DATAC structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_INVALID_ID(-9), DMS_ERROR(-1)

DMS_addObsunit

DMS_addObsUnit creates new observation unit for a given study. The information required by the function is the STUDYID. A new observation unit (OUNITID) is assigned by the function. If STUDYID is non-existing, DMS_EXIST (-5) is returned.

Syntax

long DMS_addObsunit(OBS);

Arguments

Argument	Type	Use	Description
OBS	DMS_OBSUNIT	Input	Address of the DMS_OBSUNIT structure that contains the information to be added to the database .

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_ERROR(-1)

DMS_addOindex

DMS_addOindex adds new factor level defining an observation unit. OUNITID, FACTORID and LEVELNO should all be existing in the database or else the function returns DMS_INVALID_ID (-9).

Syntax

long DMS_addOindex(OINDEX)

Arguments

Argument	Type	Use	Description
OINDEX	DMS_OINDEX	Input	Address of the DMS_OINDEX structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_INVALID_ID(-9), DMS_ERROR(-1)

0 DMS_addAttr

DMS_addAttr adds new attribute associated to either the STUDY,FACTOR or VARIATE table.to the DMSATTR table.

Syntax

long DMS_addAttr(Attr)

Arguments

Argument	Type	Use	Description
Attr	DMS_ATTR	Input	Address of the DMS_DMSATTR structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_addTrait

DMS_addTrait adds new trait according to the information in the TRAIT argument with trait name being unique. TRAITID is automatically assigned by the function.

Syntax

long DMS_addTrait(Trait,szObj)

Arguments

Argument	Type	Use	Description
Trait	DMS_TRAIT	Input	Address of the DMS_TRAIT structure that contains the information to be added to the database.
szObj	Char*	Input	Address of a null terminated string that contains the objective of the Study.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_addScale

DMS_addScale adds new scale for a triat according to the information in the SCALE argument with scale name being unique within the trait. SCALEID is automatically assigned by the function.

Syntax

long DMS_addScale(Scale)

Arguments

Argument	Type	Use	Description
Scale	DMS_SCALE	Input	Address of the DMS_SCALE structure that contains the information to be added to the database.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_addTmethod

DMS_addTmethod adds new method for a trait according to the information in the TMETH argument with method name being unique within the trait. TMETHID is automatically assigned by the function.

Syntax

long DMS_addTmethod(Tmeth,szDesc)

Arguments

Argument	Type	Use	Description
Tmeth	DMS_TMETHOD	Input	Address of the DMS_TMETHOD structure that contains the information to be added to the database.
szDesc	Char*	Input	Address of a null terminated string that contains the description of the method.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_addEffect

DMS_addEffect adds new representation of an effect by appending the list of factors that defines the representation to the EFFECT table.

Syntax

long DMS_addEffect (lstfactor, nfactor, represno, effectid)

Arguments

Argument	Type	Use	Description
lstfactor	long*	Input	Address of a list of factors that defines the representation of an effect
nfactor	long	Input	The number of factors in the list.
represno	Long*	Output	The assigned number of the representation
effectid	Char*	Input	Address of a null terminated string that contains the description of the method.

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_INVALID_ID(-9),DMS_ERROR(-1)

DMS_addVEffect

DMS_addVEffect adds a variate of an effect representation to the VEFFECT table.

Syntax

long DMS_addVEffect (veffect))

Arguments

Argument	Type	Use	Description
veffect	DMS_VEFFECT	Input	Address of the DMS_VEFFECT structure to contain the representation number and the variate id.

Returns

DMS_SUCCESS(1), DMS_EXIST(-5), DMS_ERROR(-1)

DMS FIND FUNCTIONS

The find functions search the DMS database based on a give name or value.

DMS_findStudy

DMS_findStudy searches for study with name matching the string szStudy. If fopt is FIND_FIRST (0), the function stores the study details of the first matched record. If fopt is FIND_NEXT (1), details about the succeeding matched record is retreived .

Syntax

Long DMS_findStudy(szStudy, STUDY, fopt)

Arguments

Argument	Type	Use	Description
szStudy	Char*	Input	Address of NULL terminated string containing the string to be matched
STUDY	DMS_STUDY	Output	Address of the DMS_STUDY structure to contain the study data of the retrieved record.
fopt	Long	Input	Either FIND_FIRST(0) or FIND_NEXT(1)

Returns

DMS_SUCCESS(1), DMS_NO_DATA(0), DMS_ERROR(-1)

DMS_findFactor

DMS_findFactor searches for factor with name matching szName. If STUDYID is zero, the function looks for all factors having the matched name; otherwise, the function considers factor names within the given study. If fopt is FIND_FIRST (0), the function stores the factor details of the first matched record. If fopt is FIND_NEXT, details about the succeeding matched record is stored..

Syntax

long DMS_findFactor(szName, FACTOR, fopt)

Arguments

Argument	Type	Use	Description
szName	Char*	Input	Address of NULL terminated string containing the string to be matched
FACTOR	DMS_FACTOR	Output	Address of the DMS_FACTOR structure to contain the data of the retrieved record.
fopt	Long	Input	Either FIND_FIRST(0) or FIND_NEXT(1)

Returns

DMS_SUCCESS(1), DMS_NO_DATA(0), DMS_ERROR(-1)

DMS_findVariate

DMS_findVariate searches for variate with name matching szName. If STUDYID is zero, the function looks for all variates having the matched name; otherwise, the function considers variates within the given study. If fopt is FIND_FIRST (0), the function stores the variate details of the first matched record. If fopt is FIND_NEXT, details about the succeeding matched record is stored..

Syntax

long DMS_findVariate(szName, VARIATE, fopt)

Arguments

Argument	Type	Use	Description
szName	Char*	Input	Address of NULL terminated string containing the string to be matched
VARIATE	DMS_VARIATE	Output	Address of the DMS_VARIATE structure to contain the variate data of the retrieved record.
fopt	Long	Input	Either FIND_FIRST(0) or FIND_NEXT(1)

Returns

DMS_SUCCESS(1), DMS_NO_DATA(0), DMS_ERROR(-1)

DMS_findLevelN

DMS_findLevelN returns the LEVELNO of numeric value equal to LVALUE under the factor identified by LABELID.

Syntax

long DMS_findLevelN(LevN)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN FACTORID LABELID LEVELNO LEVEL_VALUE	Output Output Input Output Input	Address of the DMS_LEVELN structure to contain the given factor identification number and the level value, and the retrieved LEVELNO.

DMS_findLevelC

DMS_findLevelC returns the LEVELNO of character value equal to LVALUE under the factor identified by LABELID.

Syntax

long DMS_findLevelC(LevC)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC LABELID FACTORID LEVELNO LEVEL_VALUE	Output Output Input Output Input	Address of the DMS_LEVELC structure to contain the given factor identification and the character level value, and the retrieved LEVELNO .

DMS_findLabelC

DMS_findLabelC searches for character label value equal to LVALUE identified by LABELID, FACTORID and LEVELNO.

Syntax

long DMS_findLabelC(LevC)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC FACTORID LEVELNO LEVEL_VALUE	Output Input Output Input	Address of the DMS_LEVELC structure to contain the given label, factor and level number identification and the character label value.

DMS_findLabelN

DMS_findLabelN searches for numeric label value equal to LVALUE identified by LABELID, FACTORID and LEVELNO.

Syntax

long DMS_findLabelN(LevN)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN FACTORID LABELID LEVELNO LEVEL_VALUE	Output Input Input Output Input	Address of the DMS_LEVELN structure to contain the given factor identification number and the level value, and the retrieved LEVELNO.

DMS_findStOunit

DMS_findStOunit finds the observation unit that contains the global factors particularly the study factor. The input argument StuChar should have the trait id of the Study factor and name of the study stored in CVALUE element.

Syntax

long DMS_findStOunit(StuChar, fopt)

Arguments

Argument	Type	Use	Description
StuChar	DMS_CharVALUE Ounitid traitid scaleid tmethid cvalue	Output/ Input Output Input Input	Address of the DMS_CharVALUE structure to contain the study trait id and the study name, and the retrieved OUNITID .
fopt	Long	Input	Either FIND_FIRST(0) or FIND_NEXT(1)

DMS_findStEffect

DMS_findStEffect finds the effect representation that is defined by the global factors particularly the study factor. The input argument StuChar should have be the TRAITID of the Study factor and a particular study name stored in CVALUE.

Syntax

long DMS_findStEffect( studyid, represno)

Arguments

Argument	Type	Use	Description
Studyid	Long	Input	The id of the given study.
Represno	Long*	Output	The number of the representation defined by the global factors.

DMS GENERAL QUERY FUNCTIONS

DMS_searchLevelN

DMS_searchLevelN searches for the numeric level values of any factor belonging to a specific trait. If scaleid is non-zero, the function will only extract level data expressed by the given scale. If tmethid is non-zero, then level data measured through the given method will be retrieved. If scaleid and tmethid are both zero, all level values of the trait will be extracted.

Syntax

Long DMS_searchLevelN( traitid, scaleid, tmethid, ounitid, flevelN, fopt)

Arguments

Argument	Type	Use	Description
traitid	Long	Input	The identification no. of the trait you want to get.
scaleid	Long	Input	The identification no. of the trait’s scale.
tmethid	Long	Input	The identification no. of the trait’s method.
ounitid	Long	Output	The observation unit having value for the specified trait.
flevelN	double	Output	The level value of the trait of numeric type.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR (-1), DMS_NO_DATA (0)

DMS_searchDataN

DMS_searchDataN searches for all numeric values of any variable belonging to a specified trait. If scaleid is non-zero, the function will extract data expressed by the given scale. If tmethid is non-zero, then data observed by the given method will be retrieved. If scaleid and tmethid are both zero, all data values of the trait will be extracted.

Syntax

Long DMS_searchDataN( traitid, scaleid, tmethid, ounitid, dvalueN, fopt)

Arguments

Argument	Type	Use	Description
traitid	Long	Input	The identification no. of the trait you want to get .
scaleid	Long	Input	The identification no. of the trait’s scale.
tmethid	Long	Input	The identification no. of the trait’s method .
Ountid	Long	Output	The observation unit having value for the specified trait.
dvalueN	Double	Output	The data value of the trait of numeric type.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR (-1), DMS_NO_DATA (0)

DMS_searchLevelC

DMS_searchLevelC searches for all character level values of any factor belonging to a specific trait. If scaleid is non-zero, the function will extract level data expressed by the given scale. If tmethid is non-zero, then factor level applied through the given method will be retrieved. If scaleid and tmethid are both zero, all level values of the trait will be extracted.

Syntax

Long DMS_searchLevelC( traitid, scaleid, tmethid, ounitid , flevelC, fopt)

Arguments

Argument	Type	Use	Description
tratid	Long	Input	The identification no. of the trait you want to get.
scaleid	Long	Input	The identification no. of the trait’s scale.
tmethid	Long	Input	The identification no. of the trait’s method.
Ounit	Long	Output	The observation unit having value for the specified trait.
flevelC	Char[255]	Output	The level value of the trait of character type.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR (-1), DMS_NO_DATA (0)

DMS_searchDataC

DMS_searchDataN searches for all character values of any variable belonging to a specified trait. If scaleid is non-zero, then the function will only extract data expressed by the given scale. If tmethid is non-zero, then data values which are observed through the given method will be retrieved. If scaleid and tmethid are both zero, all data values of the trait will be extracted.

Syntax

Long DMS_searchDataC(traitid, scaleid, tmethid, ounitid, dvalueC, fopt)

Arguments

Argument	Type	Use	Description
Traitid	Long	Input	The identification no. of the trait you want to get.
Scaleid	Long	Input	The identification no. of the trait’s scale.
Tmethid	Long	Input	The identification no. of the trait’s method.
Ounitid	Long	Output	The observation unit having value for the specified trait.
dvalueC	Char[255]	Output	The data value of the trait of character type.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR (-1), DMS_NO_DATA (0)

QUERY THROUGH OBSERVATION UNIT

DMS_defineOunitDN

DMS_defineOunitDN retrieves the trait and the character data value describing a given observation unit. The trait value is searched from the DATA_N table. The function outputs the trait, the scale for expressing it, the method for measuring it and its value.

Syntax

Long DMS_defineOunitDN(NumValue,fopt)

Arguments

Argument	Type	Use	Description
NumValue	DMS_NumVALUE .ounitid .traitid .scaleid .tmethid .nvalue	Input/ Output Input Output	The observation unit being described. The numeric value of the factor level which is one of those that defines the observation unit, together with its traitid, scaleid, and tmethid
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_defineOunitDC

DMS_defineOunitDN retrieves the trait and the character data value describing a given observation unit. The trait value is searched from the DATA_C table. The function outputs the trait, the scale for expressing it, the method for measuring it and its value.

Syntax

Long DMS_defineOunitDC(CharValue,fopt)

Arguments

Argument	Type	Use	Description
CharValue	DMS_CharVALUE .ounitid .traitid .scaleid .tmethid .cvalue	Input/ Output Input Output	The observation unit being described. The numeric value of the factor level which is one of those that defines the observation unit, together with its traitid, scaleid, and tmethid
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_defineOunitLN

DMS_defineOunitLN retrieves the trait and the numeric level value describing the specified observation unit. . The function outputs the factor trait, the scale for expressing it, the method for measuring it and its value.

Syntax

Long DMS_defineOunitLN(NumValue,fopt)

Arguments

Argument	Type	Use	Description
NumValue	DMS_NumVALUE .ounitid .traitid .scaleid .tmethid .nvalue	Input/ Output Input Output	The observation unit being described. The numeric value of the factor level which is one of those that defines the observation unit, together with its traitid, scaleid, and tmethid
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_defineOunitLC

DMS_defineOunitLC retrieves the trait and the character level value describing the given observation unit. . The function outputs the factor trait, the scale for expressing it, the method for measuring it and its value.

Syntax

Long DMS_defineOunitLC(CharValue,fopt)

Arguments

Argument	Type	Use	Description
CharValue	DMS_CharVALUE .ounitid .traitid .scaleid .tmethid .cvalue	Input/ Output Input Output	The observation unit being described. The numeric value of the factor level which is one of those that defines the observation unit, together with its traitid, scaleid, and tmethid
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_extractOunitDN

DMS_extractOunitDN extracts the observation unit from a given studyid having trait value associated to the specified dblValue. The trait value can be equal, greater than, less than, greater than or equal or less than or equal to the dblValue depending on the specified operator. The trait is represented by the traitid, expressed by scaleid and measured by tmethid. The trait value is searched from the DATA_N table. The function returns DMS_ERROR if no observation unit found.

Syntax

Long DMS_extractOunitDN (studyid,dblValue,NumValue,operator,fopt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input
dblValue	Double	Input	The value to compare.
NumValue	DMS_NumVALUE .ounitid .traitid .scaleid .tmethid .nvalue	Input/ Output Output Input Input Input Output	The identification no. of the trait you want to get. The observation unit where the trait is observed. The identification no. of the trait. The identification no. of the scale used in expressing the trait. The identification no. of the method used in measuring the trait. The retrieved numeric data value.
operator	Long	Input	Can be any of the following: DMS_EQ(0),DMS_GT(1),DMS_LT(2), DMS_GTE(3),DMS_LTE(4)
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_extractOunitDC

DMS_extractOunitDC extracts the observation unit from a given studyid having trait value equal to the specified cvalue. The trait is represented by the traitid, expressed by scaleid and measured by tmethid. The trait value is searched from the DATA_C table.. The function returns DMS_ERROR if no observation unit found.

Syntax

Long DMS_extractOunitDC (studyid,szValue,CharValue,fopt)

Arguments

Argument	Type	Use	Description
CharValue	DMS_CharVALUE .ounitid .traitid .scaleid .tmethid .cvalue	Input/ Output Output Input Input Input Input	The identification no. of the trait you want to get. The observation unit where the trait is observed. The identification no. of the trait. The identification no. of the scale used in expressing the trait. The identification no. of the method used in measuring the trait. The character data value to be compared.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_extractOunitLN

DMS_extractOunitLN extracts the observation unit from a given studyid having trait value associated to the specified dblValue. The trait value can be equal, greater than, less than, greater than and equal or less than and equal to the dblValue depending on the specified operator. The trait is represented by the traitid, expressed by scaleid and measured by tmethid. The trait value is searched from the LEVEL_N table... The function returns DMS_ERROR if no observation unit found.

Syntax

Long DMS_extractOunitLN(studyid,dblValue,NumValue,operator,fopt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input
dblValue	Double	Input	The value to compare.
NumValue	DMS_NumVALUE .ounitid .traitid .scaleid .tmethid .nvalue	Input/ Output Output Input Input Input Output	The identification no. of the trait you want to get. The observation unit where the trait is observed. The identification no. of the trait. The identification no. of the scale used in expressing the trait. The identification no. of the method used in measuring the trait. The numeric data value to be compared.
operator	Long	Input	Can be any of the following: DMS_EQ(0),DMS_GT(1),DMS_LT(2), DMS_GTE(3),DMS_LTE(4)
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_extractOunitLC

DMS_extractOunitLC extracts the observation unit from a given studyid having trait value equal to the specified szValue. The trait is represented by the traitid, expressed by scaleid and measured by tmethid. The trait value is searched from the LEVEL_C table.. The function returns DMS_ERROR if no observation unit found.

Syntax

Long DMS_extractOunitLC (studyid,cvalue,CharValue,fopt)

Arguments

Argument	Type	Use	Description
CharValue	DMS_CharVALUE .ounitid .traitid .scaleid .tmethid .cvalue	Input/ Output Output Input Input Input Input	The identification no. of the trait you want to get. The observation unit where the trait is observed. The identification no. of the trait. The identification no. of the scale used in expressing the trait. The identification no. of the method used in measuring the trait. The character data value to be compared.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_describeOunit

DMS_describeOunit returns an array of factor ids and level numbers that defines a specific observation unit.

Syntax

Long DMS_describeOunit (ounitid, arrLev, nArr, fopt)

Arguments

Argument	Type	Use	Description
ounitid	Long	Input	The number of the observation unit.
arrLev	*source	Output	The address of the first element of the array that will contain the factor ids and level numbers
nArr	Long	Input/ Output	As input, the maximum allowable number of element of the array and as output the number of retrieved factors.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_describeEffectOunit

DMS_describeEffectOunit returns an array of factor ids and level numbers that defines a specific observation unit of a given representation.

Syntax

Long DMS_describeEffectOunit (ounitid,represno, arrLev, nArr, fopt)

Arguments

Argument	Type	Use	Description
ounitid	Long	Input	The number of the observation unit.
represno	Long	Input	The number of the effect representation.
arrLev	*source	Output	The address of the first element of the array that will contain the factor ids and level numbers.
nArr	Long	Input/ Output	As input, the maximum allowable number of element of the array and as output the number of retrieved factors.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS ACCESS FUNCTIONS

These functions searches the DMS based on the key ids of the DMS tables.

DMS_getStudy

DMS_getStudy retrieves details of a Study. The first argument of the function is a pointer to DMS_STUDY structure. If the STUDYID element is not zero then the details for the corresponding study is retrieved. If it is zero, the function returns the details for the first study if fOpt = FIND_FIRST (0) or for the next available study if fOpt = FIND_NEXT(1). The objective of the study is placed in a separate argument szObj. Any call which fails to find a study returns DMS_NO_DATA.

Syntax

Long DMS_getStudy(STUDY, szSObj, cSObj, fopt)

Arguments

Argument	Type	Use	Description
STUDY	DMS_STUDY	Input/Output	Address of a DMS_STUDY structure.
szSObj	Char *	Output	Address of a NULL terminated string to place the trait description.
cSObj	Long	Input	Maximum size of szTDesc.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getObsunit

DMS_getObsunit retrieves the observation unit of a study. The first argument of the fucntion is the study id and the next argument is a pointer to DMS_OBSUNIT structure. The functions gets the first found observation unit if fOpt = FIND_FIRST (0) or for the next available observation unit if fOpt = FIND_NEXT(1). Any call which fails to find an observation unit returns DMS_NO_DATA.

Syntax

Long DMS_getObsunit(studyid,Obs, fopt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input	The study where to retrieve the observation unit.
Obs	DMS_OBS	Output	Address of a DMS_OBSUNIT structure.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getLevelC

DMS_getLevelC retrieves the value of a specific level of a character factor. The argument of the function is a pointer to DMS_LEVELC structure which contains the label id, factor id and the level no that identify the factor value. If the function fails to find a character factor value, it returns DMS_NO_DATA.

Syntax

Long DMS_getLevelC(LevC)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC	Input/Output	The address of the DMS_LEVELC structure.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getLabelC

DMS_getLabelC retrieves the label ids and its associated values for a given level of a factor. The parameters passed to the function are the factor id and level number stored in the DMS_LEVELC structure, which will also contain the returned label id and value.

Syntax

Long DMS_getLabelC(LevC, fopt)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC	Input/Output	The address of the DMS_LEVELC structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getAllLevelC

DMS_getAllLevelC retrieves the levels and values of a given character label or factor. The argument of the function is a pointer to DMS_LEVELC structure, which contains the label id. The level number and the character value of the label are returned to the LEVELNO and LEVEL_VALUE elements of the data structure. If the function does not find any character factor value, it returns DMS_NO_DATA.

Syntax

Long DMS_getAllLevelC(LevC, fopt)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC	Input/Output	The address of the DMS_LEVELC structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getAllLabelC

DMS_getAllLabelC retrieves the labels and factor values of a given factorid from the LEVEL_C table. The argument of the function is a pointer to DMS_LEVELC structure, which contains the factorid. The value, level no and labeid are returned to the LEVEL_VALUE, LEVELNO and LABELID elements of the data strcuture. The function returns DMS_NO_DATA if no record is found.

Syntax

Long DMS_getAllLabelC(LevC, fopt)

Arguments

Argument	Type	Use	Description
LevC	DMS_LEVELC	Input/Output	The address of the DMS_LEVELC structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getLevelN

DMS_getLevelC retrieves the value of a numeric factor. The argument of the function is a pointer to DMS_LEVELN structure which contains the label id, factor id and the level no that identify the factor value. If the function fails to find a numeric factor value, it returns DMS_NO_DATA.

Syntax

Long DMS_getLevelN(LevN)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN	Input/Output	The address of the DMS_LEVELN structure.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getLabelN

DMS_getLabelN retrieves the label ids and its associated values for a given level of a factor. The parameters passed to the function are the factor id and level number stored in the DMS_LEVELN structure, which will also contain the returned label id and value.

Syntax

Long DMS_getLabelN(LevN, fopt)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN	Input/Output	The address of the DMS_LEVELC structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getAllLevelN

DMS_getAllLevelN retrieves the levels and values of a given numeric label or factor. The argument of the function is a pointer to DMS_LEVELN structure, which contains the label id. The level number and the numeric value of the label are returned to the LEVELNO and LEVEL_VALUE elements of the data structure. If the function fails to find a numeric factor value, it returns DMS_NO_DATA.

Syntax

Long DMS_getAllLevelN(LevN, fopt)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN	Input/Output	The address of the DMS_LEVELN structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

0DMS_getAllLabelN

DMS_getAllLabelN retrieves the labels and factor values of a given factorid from the LEVEL_N table. The argument of the function is a pointer to DMS_LEVELN structure, which contains the factorid. The value, level no and labeid are returned to the LEVEL_VALUE, LEVELNO and LABELID elements of the data strcuture. The function returns DMS_NO_DATA if no record is found.

Syntax

Long DMS_getAllLabelN(LevN, fopt)

Arguments

Argument	Type	Use	Description
LevN	DMS_LEVELN	Input/Output	The address of the DMS_LEVELN structure.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getDataC

DMS_getDataC retrieves the value of a character data. The argument of the function is a pointer to DMS_DATAC structure which contains the observation unit id and the variate id that identify the data value. If the function fails to find a character data value, it returns DMS_NO_DATA.

Syntax

Long DMS_getDataC(DatC)

Arguments

Argument	Type	Use	Description
DatC	DMS_DATAC	Input/Output	The address of the DMS_DATAC structure.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getDataN

DMS_getDataN retrieves the value of a numeric data. The argument of the function is a pointer to DMS_DATAN structure which contains the observation unit id and the variate id that identify the data value. If the function fails to find a numeric data value, it returns DMS_NO_DATA.

Syntax

Long DMS_getDataN(DatN)

Arguments

Argument	Type	Use	Description
DatN	DMS_DATAN	Input/Output	The address of the DMS_DATAN structure.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getTrait

DMS_getTrait retrieves details of a trait. The first argument of the function is a pointer to DMS_TRAIT structure. If the TRAITID element is not zero then the details for the corresponding trait is retrieved. If it is zero, the function returns the details for the first trait if fOpt = FIND_FIRST (0) or for the next available trait if fOpt = FIND_NEXT(1). The description of the trait is placed in a separate argument szTDesc. Any call which fails to find a trait returns DMS_NO_DATA.

Syntax

Long DMS_getTrait(TRAIT, szTDesc, cTDesc, fopt)

Arguments

Argument	Type	Use	Description
TRAIT	DMS_TRAIT	Input/Output	Address of a DMS_TRAIT structure.
szTDesc	Char *	Output	Address of a NULL terminated string to place the trait description.
cTDesc	Long	Input	Maximum size of szTDesc.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getScale

DMS_getScale retrieves details of a scale. The first argument of the function is a pointer to DMS_SCALE structure. If the SCALEID element is not zero then the details for the corresponding scale is retrieved. If it is zero, the function returns the details for the first scale if fOpt = FIND_FIRST (0) or for the next available scale if fOpt=FIND_NEXT(1).

Syntax

Long DMS_getScale(SCALE, fopt)

Arguments

Argument	Type	Use	Description
SCALE	DMS_SCALE	Input/Output	Address of a DMS_SCALE structure .
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getScaleCon

DMS_getScaleCon retrieves the start value and end value of continuous numeric scale. The first argument of the function is a pointer to DMS_SCALECON structure. If the SCALEID element is not zero then the range for the corresponding scale is retrieved. If it is zero, the function returns all the ranges of the continuous scales. If fOpt = FIND_FIRST (0), then first record is retrieved. if fOpt=FIND_NEXT(1), then the succedding record is retrieved. If no record is found, DMS_NO_DATA is return value of the function.

Syntax

Long DMS_getScaleCon(ScaleCon; fopt)

Arguments

Argument	Type	Use	Description
ScaleCon	DMS_SCALECON	Input/Output	Address of a DMS_SCALECON structure .
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

5.6.16

DMS_getScaleDis

DMS_getScaleDis retrieves the allowed value of a discreet scale and its description. The first argument of the function is a pointer to DMS_SCALEDIS structure. If the SCALEID element is not zero then the allowed values for the given scale are retrieved. If it is zero, the function returns all the values of the discreets scales. If fOpt = FIND_FIRST (0), then first record is retrieved. if fOpt=FIND_NEXT(1), then the succeeding record is retrieved. If no record is found, DMS_NO_DATA is return value of the function.

Syntax

Long DMS_getScaleDis(ScaleDis; fopt)

Arguments

Argument	Type	Use	Description
ScaleDis	DMS_SCALEDIS	Input/Output	Address of a DMS_SCALEDIS structure .
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

DMS_getScaleDis2

DMS_getScaleDis2 retrieves the description of the value of a given scaleid. If no record is found, DMS_NO_DATA is return value of the function.

Syntax

Long DMS_getScaleDis2(ScaleDis; fopt)

Arguments

Argument	Type	Use	Description
ScaleDis	DMS_SCALEDIS	Input/Output	Address of a DMS_SCALEDIS structure. The value and scalied are provided as inputs and the description is returned by the function
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

DMS_getScaleTab

DMS_getScaleTab executes the SQL statement stored in the ScaleTab table for the specified scaleid. The result of the query is stored in the given file name and the number of resulted columns is returned by the function.

Syntax

Long DMS_getScaleTab(scaleid,fileName,noCol)

Arguments

Argument	Type	Use	Description
scaleid	long	Input	The identification of the scale whose values are stored in the ICIS tables. .
fileName	Char *	Input	Address of a NULL terminated string that contains the file name where the result of the SQL statement is stored.
noCol	Long	Output	The number of columns returned by the SQL statement.

DMS_getTmethod

DMS_getTmethod retrieves details of a method. The first argument of the function is a pointer to DMS_TMETHOD structure. If the TMETHID element is not zero then the details for the corresponding method is retrieved. If it is zero, the function returns the details for the first method if fOpt = FIND_FIRST (0) or for the next available method if fOpt = FIND_NEXT(1).

Syntax

Long DMS_getTmethod(TMETHOD, szTmethDesc,cTmethDescn,fopt)

Arguments

Argument	Type	Use	Description
TMETHOD	DMS_TMETHOD	Input/Output	Address of a DMS_TMETHOD structure.
szTmethDesc	Char *	Output	Address of a NULL terminated string to place the method description.
cTmethDesc	Long	Input	Maximum size of szTmethDesc.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getOunitLevelN

DMS_getOunitLevelN retrieves an observation unit of a numeric factor level. The first argument of the function is a pointer to LEVELN structure. Values for the LABELID and FACTORID elements must be provided. The corresponding observation unit for the LABELID and FACTORID is retrieved, along with the LEVELNO and LVALUE values. If fOpt = FIND_FIRST (0), details of the first level value is retrieved, or the next available level value, of fOpt = FIND_NEXT(1).

Syntax

Long DMS_getOunitLevelN(LEVELN,ouid,fopt)

Arguments

Argument	Type	Use	Description
LEVELN	DMS_LEVELN	Input/Output	Address of a DMS_LEVELN structure.
ounitid	Long	Output	The observation unit number being defined by the combination of factors and levels.
Fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getOunitLevelC

DMS_getOunitLevelC retrieves an observation unit of a character factor level. The first argument of the function is a pointer to LEVELC structure. Values for the LABELID and FACTORID elements must be provided. The corresponding observation unit for the LABELID and FACTORID is retrieved, along with the LEVELNO and LVALUE values. If fOpt = FIND_FIRST (0), details of the first level value is retrieved, or the next available level value, of fOpt = FIND_NEXT(1).

Syntax

Long DMS_getOunitLevelC(LEVELC,ouid,fopt)

Arguments

Argument	Type	Use	Description
LEVELC	DMS_LEVELC	Input/Output	Address of a DMS_LEVELC structure.
ounitid	Long	Output	The observation unit number being defined by the combination of factors and levels.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getEffectOunit

DMS_getEffectOunit extracts the observation units included in an effect representation.

Syntax

Long DMS_getEffectOunit( represno, ounitid, fOpt)

Arguments

Argument	Type	Use	Description
represno	Long	Input	The number of an effect representation.
ounitid	Long *	Output	The observation unit number included in an effect representation.
fopt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getEffectRecord

DMS_getEffectRecord retrieves records of representation number, factor id and effect number of a study from the EFFECT table.

Syntax

Long DMS_getEffectRecord(studyid, effect, fOpt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input	The identification number of a study.
effect	DMS_EFFECT	Output	The address to the DMS_EFFECT table.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getEffectRecordV

DMS_getEffectRecordV extracts the representation number, variate id and effect number of a study.

Syntax

Long DMS_getEffectRecord(studyid, effect, fOpt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input	The identification number of a study.
Effect	DMS_EFFECT	Output	The address to the DMS_EFFECT table to contain the representation number, the variate id and effect number.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getEffect

DMS_getEffect retrieves the effect representations of a study.

Syntax

Long DMS_getEffect(studyid, effectid, repres,, fOpt)

Arguments

Argument	Type	Use	Description
studyid	Long	Input	The identification number of a study.
effectid	Long *	Output	The identification number of an effect.
repres	Long *	Output	The identification number of an effect representation.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getFactorEffect

DMS_getFactorEffect retrieves the factors of an effect representation.

Syntax

Long DMS_getFactorEffect( effect, fOpt)

Arguments

Argument	Type	Use	Description
Effect	DMS_EFFECT	Input/Output	The address to the DMS_EFFECT structure. The representation number and effect id are passed to the function while the factor id is returned by the function.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getFactor

DMS_getFactor retrieves the factors of a given study. If the id of the factor label is specified, the function retrieves its record.

Syntax

Long DMS_getFactor( factor, fOpt)

Arguments

Argument	Type	Use	Description
Factor	DMS_FACTOR	Input/Output	The address to the DMS_FACTOR structure to contain the record of a factor label. The study id or the label id is a parameter passed to the function.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getFactorLabel

DMS_getFactorLabel retrieves the labels of a given factor id.

Syntax

Long DMS_getFactor( factor, fOpt)

Arguments

Argument	Type	Use	Description
Factor	DMS_FACTOR	Input/Output	The address to the DMS_FACTOR structure to contain the record of a factor label. The factor id is a parameter passed to the function.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getVariate

DMS_getVariate retrieves the variates a given study. If the id of the variate is specified, the function gets its record.

Syntax

Long DMS_getVariate( variate, fOpt)

Arguments

Argument	Type	Use	Description
variate	DMS_VARIATE	Input/Output	The address to the DMS_VARIATE structure to contain the record of a variate. The id of the study or variate is a parameter passed to the function.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_getDMSAttr

DMS_getDMSAttr retrieves additional attributes of a given DMS entity. The type of entity or table name (e.g. STUDY, FACTOR,VARIATE) is provided in the TABLE_NAME element of the DMS_DMSATTR structure. The ATTRIBUTE_TYPE element contains the id of the attribute type (e.g. Description), which is defined in the UDFLDS table. The record id of the entity in a DMS table (e.g. LABELID, VARIATID) is stored in the RECORDID_IN_TABLE element.

Syntax

Long DMS_getDMSAttr( attr, fOpt)

Arguments

Argument	Type	Use	Description
attr	DMS_DMSATTR	Input/Output	The address to the DMS_DMSATTR structure to contain the attribute of DMS entity. The type of entity, type of attribute and the specific id of the entity are parameters passed to the function.
fOpt	Long	Input	Either FIND_FIRST (0) or FIND_NEXT (1)

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS UPDATE FUNCTIONS

DMS_updateDataC

DMS_updateDataC changes the character data value associated to the given ounitid and variatid.

Syntax

Long DMS_updateDataC( DataC)

Arguments

Argument	Type	Use	Description
DataC	DMS_DATAC	Input/Output	The address to the DMS_DATAC structure that contains the new data value and the variatid and ounitid

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_updateDataN

DMS_updateDataN changes the numeric data value associated to the given ounitid and variatid.

Syntax

Long DMS_updateDataN( DataN)

Arguments

Argument	Type	Use	Description
DataN	DMS_DATAN	Input/Output	The address to the DMS_DATAN structure that contains the new data value and the variatid and ounitid

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS DELETE FUNCTION

DMS_deleteStudy

DMS_deleteStudy deletes all information about a study stored in the local DMS database.

Syntax

long GMS_deleteStudy(studyid)

Arguments

Argument	Type	Use	Description
studyid	Long	input	the ID of the study to be deleted

Returns

GMS_SUCCESS, GMS_ERROR

MISCELLANEOUS FUNCTIONS

DMS_existCombination

DMS_existCombination determines if a combination of factor levels exists or not in a study. It retrieves the observation unit which is defined by the array of factor ids and level numbers. It returns DMS_SUCCESS if the combination exists.

Syntax

Long DMS_existCombination (studyid, arrLev, ounitid, nArr)

Arguments

Argument	Type	Use	Description
Studyid	Long	Input	The specific study where to search.
ArrLev	*source	Input	The address of the first element of the array of factor ids and level numbers
Ounitid	Long	Output	The observation unit number being defined by the combination of factors and levels.
NArr	Long	Input/ Output	The number of factors in the array.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_existEffect

DMS_existEffect determines if there is an effect representation defined by the given list of factors. It retrieves the representation number and effect number if it exists and returns DMS_SUCCESS.

Syntax

Long DMS_existEffect (lstfactor, nfactor, represno, effectid)

Arguments

Argument	Type	Use	Description
lstfactor	Long*	Input	The address to the array of factors.
nfactor	Long	Input	The number of factors.
represno	Long*	Output	The number of the representation defined by the given list of factors.
effectid	Long*	Output	The number of the effect.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA (0)

DMS_minOunitid

DMS_minOunitid gets the minimum number of observation unit existing in the database. This function is primarily used in loading data to DMS.

Syntax

Long DMS_minOunitid(ounitid)

Arguments

Argument	Type	Use	Description
ounitid	long	Output	The minimum number of observation unit existing in the database.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1), DMS_NO_DATA(0)

DMS_deleteStudy

DMS_deleteStudy deletes all records associated to the specified studyid.

Syntax

Long DMS_deleteStudy(studyid)

Arguments

Argument	Type	Use	Description
studyid	long	Output	The identification number of the study to be deleted.

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_deleteDataC

DMS_deleteDataC deletes a record from the DATA_C table based on the specified ounitid and variateid.

Syntax

Long DMS_deleteDataC(ounitid, variateid)

Arguments

Argument	Type	Use	Description
ounitid	long	Input	The observation unit of the record to be deleted.
variateid	long	Input	The variateid of the record to be deleted

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

DMS_deleteDataN

DMS_deleteDataN deletes a record from the DATA_N table based on the specified ounitid and variateid.

Syntax

Long DMS_deleteDataN(ounitid, variateid)

Arguments

Argument	Type	Use	Description
ounitid	long	Input	The observation unit of the record to be deleted.
variateid	long	Input	The variateid of the record to be deleted

Returns

DMS_SUCCESS(1), DMS_ERROR(-1)

IMS DLL FUNCTIONS

The IMS_openDatabase function should be called first before calling any function mentioned in this section. The different data structures used by the functions are discussed in section 2.

ADD Functions

IMS_addLot

IMS_addLot adds a new LOT record in the LOT table of the inventory database. LOTID is automatically assigned by the function. EID needs to exist already in the GERMPLSM table. If it doesn’t, the function returns IMS_INVALID_ID(-9).

Syntax

Long IMS_addLot(LOT)

Arguments

Argument	Type	Use	Description
lotData	IMS_LOT	Input	Address of the IMS_LOT structure that contains the information to be added to the database.

Returns

IMS_SUCCESS(1), IMS_INVALID_ID(-9), IMS_ERROR(-1)

IMS_addTransaction

IMS_addTransaction adds a new transaction record in the Transactions table. TRNID is automatically assigned by the function. LOTID needs to exist in the LOT table. If it doesn’t, the function returns IMS_INVALID_ID (-9).

Syntax

long IMS_addTransaction('''TRANSACTION''')

Arguments

Argument	Type	Use	Description
transactionData	IMS_TRANSACTION	Input	Address of the IMS_TRANSACTION structure that contains the information to be added to the database.

Returns

IMS_SUCCESS(1), IMS_INVALID_ID(-9), IMS_ERROR(-1)

DATA RETRIEVAL FUNCTIONS

IMS_findLotRecord

IMS_findLotRecord retrieves data from the Lot table for a given

• Etype
• Or etype and eid
• Or etype and locid
• Or etype and eid or locid

Values specified in the ETYPE, EID, and LOCID fields of the IMS_LOT structure.

If no records match the given criteria, the function returns IMS_NO_DATA .

Syntax

Long IMS_findLotRecord ( lotData, fOpt)

Arguments

Argument	Type	Use	Description
lotData	IMS_LOT	Input/Output	Address of a IMS_Lot record
fOpt	long	Input	Either FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_findTransactionRecord

IMS_findTransactionRecord retrieves transaction records from the Transaction Table for a specified LOTID value.

Syntax

Long IMS_findTransactionRecord (lotid, transactionData, fOpt)

Arguments

Argument	Type	Use	Description
Lotid	long	Input	The TRNID to search
transactionData	IMS_TRANSACTION	Output	Address of a IMS_Transaction record
fOpt	long	Input	FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_getTransactionReserve

IMS_getTransactionReserve retrieves all reserve transaction records from the Transaction Table. If the flagAll is not 1, then only transactions reserved by the current user are retrieved.

Syntax

Long IMS_getTransactionReserve (flagAll, transactionData,LotData, fOpt)

Arguments

Argument	Type	Use	Description
flagAll	long	Input	1 (all reserve) or 0 (only reserve done by the current user)
transactionData	IMS_TRANSACTION	Output	Address of a IMS_Transaction record
lotData	IMS_LOT	Output	Address of a IMS_Lot record
fOpt	long	input	FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_getTransactionDeposit

IMS_getTransactionDeposit retrieves all deposit transaction records from the Transaction Table. If the flagAll is not 1, then only transactions deposited by the current user are retrieved.

Syntax

Long IMS_getTransactionDeposit (flagAll, transactionData,LotData, fOpt)

Arguments

Argument	Type	Use	Description
flagAll	long	Input	1 (all deposit) or 0 (only deposit done by the current user)
transactionData	IMS_TRANSACTION	Output	Address of a IMS_Transaction record
lotData	IMS_LOT	Output	Address of a IMS_Lot record
fOpt	long	input	FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_getReserveByPerson

IMS_getReserveByPerson retrieves all reserve transaction made by a particular requestor. The PERSONID of the requestor is stored in the IMS_TRANSACTION data structure (transactionData).

Syntax

Long IMS_getReserveByPerson (transactionData, LotData, fOpt)

Arguments

Argument	Type	Use	Description
flagAll	long	Input	1 (all reserve) or 0 (only reserve done by the current user)
transactionData	IMS_TRANSACTION	Output	Address of a IMS_Transaction record
lotData	IMS_LOT	Output	Address of a IMS_Lot record
fOpt	long	input	FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_getDepositByPerson

IMS_getDepositByPerson retrieves all deposits done by a particular person. The PERSONID is stored in the IMS_TRANSACTION data structure (transactionData).

Syntax

Long IMS_getDepositByPerson (transactionData, LotData, fOpt)

Arguments

Argument	Type	Use	Description
flagAll	long	Input	1 (all reserve) or 0 (only reserve done by the current user)
transactionData	IMS_TRANSACTION	Output	Address of a IMS_Transaction record
lotData	IMS_LOT	Output	Address of a IMS_Lot record
fOpt	long	input	FIND_FIRST or FIND_NEXT

Returns

IMS_SUCCESS, IMS_ERROR, NO_DATA

IMS_getBalanceOfLot

This function retrieves the total sum of the transaction quantities for a given lot.

Syntax

Long IMS_reportBalance (lotid, sumTrans)

Argument	Type	Use	Description
lotid	Long	input	The lot
sumTrans	Double	output	The sum of the transaction quantities of the lot

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

UPDATE FUNCTIONS

IMS_setTransaction

This function changes the value of any field in of the IMS_Transaction Table except LOTID and TRANSID given TRANSID. The status of the transaction can be updated by setting the TRNSTAT field to 1 (committed) or to 9 (cancelled) .

Syntax

Long IMS_setTransaction (transactionData)

Arguments

Argument	Type	Use	Description
transactionData	IMS_TRANSACTION	Input	Address of the IMS_TRANSACTION data structure

Returns

IMS_SUCCESS, IMS_ERROR

IMS_setLot

This function changes the value of any field in of the IMS_LOT Table except LOTID which is the given parameter.

Syntax

Long IMS_setLot (lotData)

Arguments

Argument	Type	Use	Description
lotData	IMS_LOT	Input	Address of the IMS_LOT data structure

Returns

IMS_SUCCESS, IMS_ERROR

REPORT FUNCTIONS

IMS_reportAllTransaction

This function retrieves all uncommitted transactions which include commitment date and quantity of the transaction, location, scale and comment about its lot.

Syntax

Long IMS_reportAllTransaction (lotid, cmtdate, quantity, szLocName, szScale, szComment, fOpt)

Argument	Type	Use	Description
lotid	Long	Output	The lot of the transaction
cmtdate	Long	output	The commitment date of the transaction
quantity	Double	output	The quantity of the transaction
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportMaterialDist

This function reports on all requested reserve (uncommitted withdrawal).

Syntax

Long IMS_reportMaterialDist (lotid, eid, quantity, szLocName, szScale, szComment, cmtdate, fOpt)

Argument	Type	Use	Description
lotid	Long	Output	The lot of the transaction
eid	Long	Output	The ID of the entity (e.g. GID) in the lot
quantity	Double	output	The quantity of the transaction
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
cmtdate	Long	output	The commitment date of the transaction
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportByRequestor

This function reports on all requested reserves and withdrawals including the persons who requested for them. The first record is returned if fOpt = FIND_FIRST and the succeeding record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportMaterialDist (lotid, eid, quantity, szLocName, szScale, szComment, cmtdate, lngStat, lngPerson, fOpt)

Argument	Type	Use	Description
lotid	Long	Output	The lot of the transaction
eid	Long	Output	The ID of the entity (e.g. GID) in the lot
quantity	Double	output	The quantity of the reserve or withdrawal
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
cmtdate	Long	output	The commitment date of the transaction
lngPerson	Long	output	The person who reserved or withdrew the amount
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportBalance

This function retrieves the sum of the transaction, location and scale of all lots. The first record is returned if fOpt = FIND_FIRST and the succeeding record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportBalance (lotid, sumTrans, szLocName, szScale, fOpt)

Argument	Type	Use	Description
lotid	Long	Output	The lot of the transactions
sumTrans	Double	output	The sum of the quantity of the transactions
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportEmptyShelves

This function reports on the lot that have zero balance or the sum of committed transactions is zero. The first record is returned if fOpt = FIND_FIRST and the succeeding record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportEmptyShelves (lotid, eid, szLocName, szScale, fOpt)

Argument	Type	Use	Description
lotid	Long	Output	The lot which has zero balance
eid	Long	Input	The identification (GID) of the entity asoociated with the lot
szLocName	Char *	output	The location where the lot is originally stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 (FIND_NEXT) for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportDormantEntries

This function reports on the lots with non-zero actual balance that are stored on or earlier than the specified year. The first record is returned if fOpt = FIND_FIRST and the succeeding record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportDormantEntries (minYear, lotid, eid, quantity, szLocName, szScale, fOpt)

Argument	Type	Use	Description
minYear	Long	Input	The year used as basis for dormant entries
lotid	Long	Input	The lot considered as dormant
eid	Long	Input	The identification (GID) of the entity asoociated with the lot
quantity	Double	Input	The actual balance or sum of committed transactions
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 (FIND_NEXT) for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportMinimumAmount

This function reports on the lots with actual balance (or sum of committed transactions) less than the given amount. The first record is returned if fOpt = FIND_FIRST and the succeeding record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportMinimumAmount (minQty, lotid, eid, quantity, szLocName, szScale, fOpt)

Argument	Type	Use	Description
minQty	Long	Input	The amount used as basis
lotid	Long	Input	The lot where it is considered below the minimum balance
eid	Long	Input	The identification (GID) of the entity asoociated with the lot
quantity	Double	Input	The actual balance or sum of committed transactions
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 (FIND_NEXT) for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportLotByEntity

This function retrieves the lot, scale, location and ids for a given type of Entity (e.g. GERMPLASM).

Syntax

Long IMS_reportLotByEntity (szType, lotid, eid, szLocName, szScale, szComment, fOpt)

Argument	Type	Use	Description
szType	Char *	Input	The type of Entity. Generally, it is "GERMPLASM".
lotid	Long	Output	The lotid of a particular instance of the given Entity
eid	Long	Output	The identification (GID) of a particular instance of the entity
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportLotByEntityGIDFrom

This function reports on the lot, scale, location for a given type of Entity (e.g. GERMPLASM) and its identification (e.g. GID). The first match is returned if fOpt = FIND_FIRST and the next matching record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportLotByEntityGIDFrom (szType, lotid, eid, szLocName, szScale, szComment, fOpt)

Argument	Type	Use	Description
szType	Char *	Input	The type of Entity. Generally, it is "GERMPLASM".
lotid	Long	Output	The lotid of a particular instance of the given Entity
eid	Long	Input	The identification (GID) of the entity
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 (FIND_NEXT) for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

IMS_reportLotByEntityGIDRange

This function reports on the lot, scale, location for a given type of Entity (e.g. GERMPLASM) and range of its IDs (e.g. GID). The first match is returned if fOpt = FIND_FIRST and the next matching record is returned if fOpt = FIND_NEXT

Syntax

Long IMS_reportLotByEntityGIDRange (szType, lotid, eidFrom, eidTo, szLocName, szScale, szComment, fOpt)

Argument	Type	Use	Description
szType	Char *	Input	The type of Entity. Generally, it is "GERMPLASM".
lotid	Long	Output	The lotid of a particular instance of the given Entity
eid	Long	Input	The identification (GID) of the entity
szLocName	Char *	output	The location where the lot is stored
szScale	Char *	output	The scale or measurement unit on how the lot is stored
szComment	Char *	output	Comment about the lot
fOpt	Long	input	0 (FIND_FIRST) to get the first record, 1 (FIND_NEXT) for succeeding records

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA(0)

MISCELLANEOUS

IMS_closeLot

This function changes the STATUS field of the Lot Table to 1 "Closed". Lot records are not deleted from the table.

Syntax

Long IMS_closeLot (lotid)

Arguments

Argument	Type	Use	Description
lotid	Long	Input	The lotid to close.

Returns

IMS_SUCCESS, IMS_ERROR

IMS_calculateBalance

IMS_calculateBalance gets all values from field TRNQTY of the Transaction Table, for a given LOTID, and adds up all the anticipated and committed values to get the available balance, and all the committed values to get the actual balance. Cancelled transactions are ignored

Syntax

Long IMS_calculateBalance(lotid, trnqty1, trnqty2)

Arguments

Argument	Type	Use	Description
Lotid	long	input
Trnqty1	long	Output	The summation of the TRNQTY field values for anticipated and committed transactions
Trnqty2	long	Output	The summation of the TRNQTY field values for committed transactions only.

Returns

IMS_SUCCESS(1), IMS_ERROR(-1), IMS_NO_DATA (0)

LMS DLL FUNCTIONS

The GMS_openDatabase function mentioned in Section IV.A.3 should be called first before calling any functions mentioned in this section. The different data structures used by the functions are discussed in section 2.

GMS_findLocation

GMS_findLocation searches the location table for the first location with name which matches the string in the PREFERRED_NAME field of the Locn argument when fOpt=FIND_FIRST. It searches for the next match if fOpt is FIND_NEXT. If the TYPE field of Locn is non zero, the search is restricted to locations with LOCATION TYPE which match its value. The search string may contain wild cards such as _ and %.

Syntax

long GMS_findLocation(Locn, fOpt)

Arguments

Argument	Type	Use	Description
Locn	GMS Location Structure	Input/ output	Address of a GMS_Germplasm record
fOpt	long	input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GMS_getLocation

GMS_getLocation will retrieve location information. The first argument of GMS_getLocation is a pointer to a GMS_Location structure (6.1.2f). If the LOCATION_ID is not zero when the function is called then it returns the details for the corresponding location ID. If it is zero then the function returns details for the first location record if fOpt = FIND_FIRST or for the next available location record if fOpt = FIND_NEXT. Any call which fails to get location information returns GMS_NO_DATA.

Syntax

long GMS_getLocation(location ,fOpt)

Arguments

Argument	Type	Use	Description
location	GMS_Location*	input/output	Address of a GMS_Location structure
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

If the function is called and there is a problem accessing the database, the function will return GMS_ERROR. Any call which fails to get location information returns GMS_NO_DATA.

GMS_getLocation2

GMS_getLocation2 will retrieve location information for all locations matching specified criteria. The first argument of GMS_getLocation2 is a pointer to a GMS_Location structure (6.1.2f). All elements of the structure must be set to valid values or zeros or blanks before calling the function with parameter fOpt=FIND_FIRST. This sets a search template restricting the search to records with fields matching the valid values. The first match is returned if fOpt = FIND_FIRST and the next matching location is returned if fOpt = FIND_NEXT

Syntax

long GMS_getLocation2(location ,fOpt)

Arguments

Argument	Type	Use	Description
location	GMS_Location*	input/output	Address of a GMS_Location structure
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

Comments

The principle of using GMS_getLocation2 is similar to GMS_getAttribute2. If the function is called and there is a problem accessing the database, the function will return GMS_ERROR. Any call which fails to get location information returns GMS_NO_DATA.

GMS_addLocation

GMS_addLocation adds a new location to the local LOCATION table. Details of the location must be stored in appropriate elements of the location parameter (6.1.2f), and the LOCATION_ID element must be set to zero before the call to GMS_addLocation. The next available location number will be returned in the LOCATION_ID 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_addLocation(location)

Arguments

Argument	Type	Use	Description
Location	GMS_Location *	input/output	Address of a GMS_Location structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the location structure (6.1.2f) must be properly populated with values before calling the function:

• LOCATION_ID must be set to 0,

• PREFERRED_NAME must be set to a null terminated ASCII string,

Other elements may be set if values are known. Otherwise they should be set to the defined nulls for each field

BIBREF DLL FUNCTIONS

The GMS_openDatabase function mentioned in Section 3.1 should be called first before calling any functions mentioned in this section. The different data structures used by the functions are discussed in section IV.A.2.

GMS_getBibrefs

GMS_getBibrefs retrieves bibliographic reference information. The first argument is a pointer to GMS_BIBREFS structure. If the referenece ID is not zero when the function is called then it returns the details for the corresponding reference ID. If it is zero then the function returns details for the first bibliographic reference record if fOpt = FIND_FIRST or for the next available reference record if fOpt = FIND_NEXT. If no bibliographic information is found, the function returns GMS_NO_DATA.

Syntax

long GMS_getBibrefs(bibref ,fOpt)

Arguments

Argument	Type	Use	Description
bibref	GMS_BIBREFS*	input/output	Address of a GMS_BIBREFS structure
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GMS_addBibrefs

GMS_addBibrefs adds a new record of bibliographic reference to the local BIBREFS table. Details of the bibliographic reference must be stored in appropriate elements of the bibref parameter, and the REFID element must be set to zero before the call to GMS_addBibrefs. The next available bibliographic reference number will be returned in the REFID element

New data is not committed to the local database until the function GMS_commitData (see Section 3.1) has been called, and uncommitted data can be deleted from the buffer with the GMS_rollbackData function (see Section 3.1)

Syntax

long GMS_addBibrefs(bibref)

Arguments

Argument	Type	Use	Description
bibref	GMS_BIBREFS*	input/output	Address of a GMS_BIBREFS structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the bibref structure must be properly populated with values before calling the function:

• REFID must be set to 0,

• All character fields must be null terminated ASCII string,

Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS DLL FUNCTIONS

The GEMS_openDatabase function mentioned in Section 3 should be called first before calling any functions mentioned in this section. The different data structures used by the functions are discussed in section 2.

ADD FUNCTIONS

GEMS_addGEMSName

(GEMS_NAME *recName) GEMS_addGEMSName adds a new record of names for GEMS entities to the local GEMS_NAMES table. Details of the names must be stored in appropriate elements of the recName parameter, and the GNID element must be set to zero before the call to GMS_addGEMSName. The next available name ID will be returned in the GNID element.

Syntax

long GEMS_addGEMSName(recName)

Arguments

Argument	Type	Use	Description
recName	GEMS_NAME*	input/output	Address of a GEMS_NAME structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the recName structure must be properly populated with values before calling the function:

• GNID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addComponent

GEMS_addComponent adds a new record of component of a polymorphic detector to the GEMS_COMP table. Details of the component must be stored in appropriate elements of the data parameter, and the CID element must be set to zero before the call to GMS_addComponent. The next available component ID will be returned in the CID element.

Syntax

long GEMS_addComponent(data)

Arguments

Argument	Type	Use	Description
data	GEMS_COMPONENT*	input/output	Address of a GEMS_COMPONENT structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• CID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addMD

GEMS_addMD adds a record in GEMS_MARKER_DETECTOR table. Details of the marker detector must be stored in appropriate elements of the data parameter, and the MDID element must be set to zero before the call to GMS_addMD. The next available component ID will be returned in the MDID element.

Syntax

long GEMS_addMD(data)

Arguments

Argument	Type	Use	Description
data	GEMS_MARKER_DETECTOR*	input/output	Address of a GEMS_MARKER_DETECTOR structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• MDID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addMV

GEMS_addMV adds a record of information on molecular variant names in GEMS_MV table. Details of the molecular variant must be stored in appropriate elements of the data parameter, and the MVID element must be set to zero before the call to GEMS_addMV. The next available ID will be returned in the MVID element.

Syntax

long GEMS_addMV(data)

Arguments

Argument	Type	Use	Description
data	GEMS_MV*	input/output	Address of a GEMS_MV structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• MVID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addLocus

GEMS_addLocus adds a record in GEMS_LOCUS table. GEMS_LOCUS table contains information on chromosome and location of a molecular variant. Details of the locus must be stored in appropriate elements of the data parameter, and the LOCUSID element must be set to zero before the call to GEMS_LOCUS. The next available ID will be returned in the LOCUSID element.

Syntax

long GEMS_addLocus(data)

Arguments

Argument	Type	Use	Description
data	GEMS_LOCUS*	input/output	Address of a GEMS_LOCUS structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• LOCUSID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addPD

GEMS_addPD adds a record in GEMS_PD table. The PD table the different combination of Marker Detector ID(MDID) and condition ID (condid). Details of this relationship must be stored in appropriate elements of the data parameter, and the PDID element must be set to zero before the call to GMS_addPD. The next available ID will be returned in the PDID element.

Syntax

long GEMS_addPD(data)

Arguments

Argument	Type	Use	Description
data	GEMS_PD*	input/output	Address of a GEMS_PD structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• PDID must be set to 0,

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addPdComp

GEMS_addPdComp adds a record in GEMS_PD_COMP table. The GEMS_PD_COMP (Polymorphic Detector and Components) table serves as the intermediate table to break the many-to-many relationship between the protocols/conditions and marker detector. Details of this relationship must be stored in appropriate elements of the data parameter, and the PD_COMP element must be set to zero before the call to GMS_addPdComp. The next available ID will be returned in the PD_COMP element.

Syntax

long GEMS_addPdComp(data)

Arguments

Argument	Type	Use	Description
data	GEMS_PD_COMP*	input/output	Address of a GEMS_PD_COMP structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

GEMS_addProp

GEMS_addProp adds a record in GEMS_PROPERTY table. This table defines the property, method and scale used by each component in the GEMS_COMP table. These information must be stored in appropriate elements of the data parameter.

Syntax

long GEMS_addProp(data)

Arguments

Argument	Type	Use	Description
data	GEMS_PROP*	input/output	Address of a GEMS_PROP structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addScale

GEMS_addScale adds a record in GEMS_SCALE table. Details of the scale are stored in the appropriate elements of the data parameter.

Syntax

long GEMS_addScale(data)

Arguments

Argument	Type	Use	Description
data	GEMS_SCALE*	input/output	Address of a GEMS_SCALE structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GEMS_addMethod

GEMS_addMethod adds a record in GEMS_METHOD table. Details of the method are stored in the appropriate elements of the data parameter.

Syntax

long GEMS_addMethod(data)

Arguments

Argument	Type	Use	Description
data	GEMS_METHOD*	input/output	Address of a GEMS_METHOD structure

Returns

GMS_SUCCESS, GMS_ERROR , GMS_NO_ACCESS

Comments

The following fields of the data structure must be properly populated with values before calling the function:

• All character fields must be null terminated ASCII string

• Other elements may be set if values are known. Otherwise they should be set to the default values.

GET FUNCTIONS

GEMS_getGemsMID

GMS_getGemsMID retrieves the corresponding GEMS MID based on the marker name & object type . The function returns details of the first matched record if fOpt = FIND_FIRST or of the succeeding matched record if fOpt = FIND_NEXT.

Syntax

long GEMS_getGemsMID(gemsInfo ,fOpt)

Arguments

Argument	Type	Use	Description
gemsInfo	GEMS_INFO*	input/output	Address of a GMS_INFO structure
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_getGemsMVID

GEMS_getGemsMVID retrieves the corresponding GEMS MVID based on the allele name, object type, & marker ID. The function returns details of the first matched record if fOpt = FIND_FIRST or of the succeeding matched record if fOpt = FIND_NEXT.

Syntax

long GEMS_getGemsMVID(gemsInfo ,fOpt)

Arguments

Argument	Type	Use	Description
gemsInfo	GEMS_INFO*	input/output	Address of a GMS_INFO structure
fOpt	Long	Input	Either FIND_FIRST or FIND_NEXT

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_getNameID

GEMS_getNameID gets the corresponding GOBJID from GEMS_NAMES table based on the given GOBJTYPE and GNVAL. The function returns the retrieved ID in the GOBJID element of the data parameter.

Syntax

long GEMS_getNameID(data)

Arguments

Argument	Type	Use	Description
data	GEMS_INFO*	input/output	Address of a GMS_INFO structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_getProtocolID

GEMS_getProtocolID gets the corresponding GOBJID from GEMS_NAMES table where GOBJTYPE= PROTOCOL and on the given GNVAL. The function returns the retrieved ID in the GOBJID element of the data parameter.

Syntax

long GEMS_getProtocolID(data, fOpt)

Arguments

Argument	Type	Use	Description
data	GEMS_INFO*	input/output	Address of a GMS_INFO structure
fOpt	Long	input	FIND_FIRST = 0 or FIND_NEXT = 1

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_getPdComp

GEMS_getPdComp add all cids in gems_comp where condition is equal to Condition of the pdCompInfo parameter. All cids found will be added to GEMS_PD_COMP table with pd_comp equal to the next available id.

Syntax long GEMS_getPdComp(pdCompInfo, fOpt)

Arguments

Argument	Type	Use	Description
pdCompInfo	GEMS_PD_COMP*	input/output	Address of a GMS_PD_COMP structure
fOpt	Long	input	FIND_FIRST = 0 or FIND_NEXT = 1

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_findPID

GEMS_findPID gets the corresponding PID from GEMS_PROP table given the property, scale, method and property group. The function returns the retrieved ID in the PID element of the data parameter.

Syntax

long GEMS_findPID(data)

Arguments

Argument	Type	Use	Description
data	PROP_INFO*	input/output	Address of a PROP_INFO structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_findPdid

gems_pd.condid = ? AND gems_pd.mdid = GEMS_findPdid gets the corresponding PDID from GEMS_PD table given CONDID and MDID. The function returns the retrieved ID in the PDID element of the data parameter.

Syntax

long GEMS_findPdid(data)

Arguments

Argument	Type	Use	Description
data	GEMS_PD*	input/output	Address of a GEMS_PD structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_findPropID

GEMS_findPID gets the corresponding PID and PROPID from GEMS_PROP table given the property name and property group. The function returns the retrieved IDs in the appropriate elements of the data parameter.

Syntax

long GEMS_findPID(data)

Arguments

Argument	Type	Use	Description
data	GEMS_PROP*	input/output	Address of a GEMS_PROP structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_findScale

GEMS_findScale gets the corresponding SCALEID from GEMS_SCALE table given the scale name and property id. The specified information should be stored in the appropriate elements of the data parameter. The function returns the retrieved ID in the SCALEID element of the parameter.

Syntax

long GEMS_findScale(data)

Arguments

Argument	Type	Use	Description
data	GEMS_SCALE*	input/output	Address of a GEMS_SCALE structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA

GEMS_findMethod

GEMS_findMethod retrieves a record of the method from GEMS_METHOD table given the name. Details of the information are stored in the appropriate elements of the data parameter.

Syntax

long GEMS_findMethod(data)

Arguments

Argument	Type	Use	Description
data	GEMS_METHOD*	input/output	Address of a GEMS_METHOD structure

Returns

GMS_SUCCESS, GMS_ERROR, GMS_NO_DATA