GAMS Data Exchange API (GDX) Documentation

Generated for GAMS ..

Note
For a more detailed documentation please refer to the official GAMS Data Exchange API (GDX): https://gams-dev.github.io/gdx/.

Functions, Procedures, and Properties

 
Boolean gdxStoreDomainSets
 Get flag to store one dimensional sets as potential domains, false (0) saves lots of space for large 1-dim sets that are no domains but can create inconsistent GDX files if used incorrectly. Returns 1 (true) iff. elements of 1-dim sets should be tracked for domain checking, 0 (false) otherwise.
 
Boolean gdxStoreDomainSetsSet
 Set flag to store one dimensional sets as potential domains, false (0) saves lots of space for large 1-dim sets that are no domains but can create inconsistent GDX files if used incorrectly. Param flag 1 (true) iff. elements of 1-dim sets should be tracked for domain checking, 0 (false) otherwise.
 
Boolean gdxAllowBogusDomains
 Get flag to ignore using 1-dim sets as domain when their elements are not tracked (see gdxStoreDomainSets). In case the flag is enabled this is allowing potentially unsafe writing of records to symbols with one dimensional sets as domain, when GDX has no lookup table for the elements of this set. This can happen when `gdxStoreDomainSets` was disabled by the user to save memory. For backwards compatability, this is enabled by default. Return 1 (true) iff. using a 1-dim set as domain (when store domain sets option is disabled) should be ignored. Otherwise an error is raised (ERR_NODOMAINDATA).
 
Boolean gdxAllowBogusDomainsSet
 Set flag to ignore using 1-dim sets as domain when their elements are not tracked (see gdxStoreDomainSets). Toggle allowing potentially unsafe writing of records to symbols with one dimensional sets as domain, when GDX has no lookup table for the elements of this set. This can happen when `gdxStoreDomainSets` was disabled by the user to save memory. For backwards compatability, this is enabled by default. When the user explicitly disables it, e.g. via `gdxAllowBogusDomainsSet(false)`, then using a one dimensional set as domain will cause a GDX error (ERR_NODOMAINDATA). Param flag 1 (true) iff. using a 1-dim set as domain (when store domain sets option is disabled) should be ignored. Otherwise an error is raised (ERR_NODOMAINDATA).
 
Boolean gdxMapAcronymsToNaN
 Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default.
 
Boolean gdxMapAcronymsToNaNSet
 Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default.
 

Acronyms

Integer gdxAcronymAdd
 Add a new acronym entry. This can be used to add entries before data is written. Returns negative value (<0) if the entry is not added.
 
Integer gdxAcronymCount
 Number of entries in the acronym table.
 
Integer gdxAcronymGetInfo
 Retrieve acronym information from the acronym table. Non-zero if the index into the acronym table is valid.
 
Integer gdxAcronymGetMapping
 Get information how acronym values are remapped. When reading GDX data, we need to map indices for acronyms used in the GDX file to indices used by the reading program. Non-zero if the index into the acronym table is valid.
 
Integer gdxAcronymIndex
 Get index value of an acronym. Returns zero if V does not represent an acronym.
 
Integer gdxAcronymName
 Find the name of an acronym value. Non-zero if a name for the acronym is defined. An unnamed acronym value will return a string of the form UnknownAcronymNNN, were NNN is the index of the acronym.
 
Integer gdxAcronymNextNr
 Returns the value of the NextAutoAcronym variable and sets the variable to nv.
  • When we read from a GDX file and encounter an acronym that was not defined, we need to assign a new index for that acronym. The variable NextAutoAcronym is used for this purpose and is incremented for each new undefined acronym.
  • When NextAutoAcronym has a value of zero, the default, the value is ignored and the original index as stored in the GDX file is used for the index.
 
Integer gdxAcronymSetInfo
 Modify acronym information in the acronym table
  • When writing a GDX file, this function is used to provide the name of an acronym; in this case the Indx parameter must match.
  • When reading a GDX file, this function is used to provide the acronym index, and the AName parameter must match.
 
Double gdxAcronymValue
 Create an acronym value based on the index (AIndx should be greater than 0). Returns the calculated acronym value (zero if AIndx is <0).
 

Comment

Integer gdxSymbolAddComment
 Add a line of comment text for a symbol. Returns zero if the operation is not possible.
 
Integer gdxSymbolGetComment
 Retrieve a line of comment text for a symbol. Returns zero if the operation is not possible.
 

Domain

Integer gdxSymbolGetDomain
 Retrieve the domain of a symbol. Returns zero if the operation is not possible.
 
Integer gdxSymbolGetDomainX
 Retrieve the domain of a symbol (using relaxed or domain information). Returns zero if the operation is not possible.
 
Integer gdxSymbolSetDomain
 Define the domain of a symbol for which a write data operation just started using DataWriteRawStart, DataWriteMapStart or DataWriteStrStart. Returns zero if the operation is not possible.
 
Integer gdxSymbolSetDomainX
 Define the domain of a symbol (relaxed version). Returns zero if the operation is not possible.
 
Integer gdxGetDomainElements
 Get the unique elements for a given dimension of a given symbol.
 

Errors

Integer gdxErrorCount
 Returns the number of errors.
 
Integer gdxErrorStr
 Returns the text for a given error number. Always non-zero.
 
Integer gdxGetLastError
 Returns the last error number or zero if there was no error. Calling this function will clear the last error stored.
 

File (Open/Close)

Integer gdxClose
 Close a GDX file that was previously opened for reading or writing. Before the file is closed, any pending write operations will be finished. This does not free the GDX in-memory object. This method will automatically be called when the GDX object lifetime ends (e.g. being out of scope).
 
Integer gdxOpenAppend
 Open an existing GDX file for output. Non-zero if the file can be opened, zero otherwise.
 
Integer gdxOpenRead
 Open a GDX file for reading. Non-zero if the file can be opened, zero otherwise.
 
Integer gdxOpenReadEx
 Open a GDX file for reading allowing for skipping sections. Non-zero if the file can be opened, zero otherwise.
 
Integer gdxOpenWrite
 Open a new GDX file for output. Non-zero if the file can be opened, zero otherwise.
 
Integer gdxOpenWriteEx
 Create a GDX file for writing with explicitly given compression flag. Non-zero if the file can be opened, zero otherwise.
 

Filters

Integer gdxFilterExists
 Check if there is a filter defined based on its number as used in gdxFilterRegisterStart. Returns zero if the operation is not possible.
 
Integer gdxFilterRegister
 Add a unique element to the current filter definition, zero if the index number is out of range or was never mapped into the user index space.
 
Integer gdxFilterRegisterDone
 Finish registration of unique elements for a filter. Returns zero if the operation is not possible.
 
Integer gdxFilterRegisterStart
 Define a unique element filter. Returns zero if the operation is not possible.
 

Information

Integer gdxFindSymbol
 Search for a symbol by name in the symbol table; the search is not case-sensitive.
  • When the symbol is found, SyNr contains the symbol number and the function returns a non-zero integer.
  • When the symbol is not found, the function returns zero and SyNr is set to -1.
 
Integer gdxGetUEL
 Get the string for a unique element using a mapped index. Returns zero if the operation is not possible.
 

Longest symbol UEL

Integer gdxSymbIndxMaxLength
 Returns the length of the longest UEL used for every index position for a given symbol.
 
Integer gdxSymbMaxLength
 Returns the length of the longest symbol name in the GDX file.
 
Integer gdxUELMaxLength
 Returns the length of the longest unique element (UEL) name.
 
Integer gdxAddAlias
 Add an alias for a set to the symbol table. One of the two identifiers has to be a known set, an alias or "*" (universe); the other identifier is used as the new alias for the given set. The function gdxSymbolInfoX can be used to retrieve the set or alias associated with the identifier; it is returned as the UserInfo parameter.
 
Integer gdxAutoConvert
 Returns the value of the AutoConvert variable and sets the variable to nv.

When we close a new GDX file, we look at the value of AutoConvert; if AutoConvert is non-zero, we look at the GDXCOMPRESS and GDXCONVERT environment variables to determine if conversion to an older file format is desired. We needed this logic so gdxcopy.exe can disable automatic file conversion.

 
Int64 gdxGetMemoryUsed
 Return the number of bytes used by the data objects.
 

Read Data

Integer gdxDataErrorCount
 Query the number of error records.
 
Integer gdxDataErrorRecord
 Retrieve an error record. Non-zero if the record number is valid.
 
Integer gdxDataErrorRecordX
 Retrieve an error record. Non-zero if the record number is valid.
 
Integer gdxDataReadDone
 Finish reading of a symbol in any mode (raw, mapped, string). . Returns zero if the operation is not possible.
 
Integer gdxDataReadFilteredStart
 Initialize the reading of a symbol in filtered mode. Returns zero if the operation is not possible.
 
Integer gdxDataReadMap
 Read the next record in mapped mode. Returns zero if the operation is not possible.
 
Integer gdxDataReadMapStart
 Initialize the reading of a symbol in mapped mode. Returns zero if the operation is not possible.
 
Integer gdxDataReadRaw
 Read the next record in raw mode. Returns zero if the operation is not possible.
 
Integer gdxDataReadRawFast
 Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible.
 
Integer gdxDataReadRawFastEx
 Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible.
 
Integer gdxDataReadRawFastFilt
 Read a symbol in Raw mode while applying a filter using a callback procedure. Returns zero if the operation is not possible.
 
Integer gdxDataReadRawStart
 Initialize the reading of a symbol in raw mode. Returns zero if the operation is not possible.
 
Integer gdxDataReadSlice
 Read a slice of data from a data set, by fixing zero or more index positions in the data. When a data element is available, the callback procedure DP is called with the current index and the values. The indices used in the index vary from zero to the highest value minus one for that index position. This function can be called multiple times. Returns zero if the operation is not possible.
 
Integer gdxDataReadSliceStart
 Prepare for the reading of a slice of data from a data set. The actual read of the data is done by calling gdxDataReadSlice. When finished reading, call gdxDataReadDone. Returns zero if the operation is not possible.
 
Integer gdxDataReadStr
 Read the next record using strings for the unique elements. The reading should be initialized by calling DataReadStrStart. Returns zero if the operation is not possible or if there is no more data.
 
Integer gdxDataReadStrStart
 Initialize the reading of a symbol in string mode. Returns zero if the operation is not possible.
 
Integer gdxDataSliceUELS
 Map a slice index in to the corresponding unique elements. After calling DataReadSliceStart, each index position is mapped from 0 to N(d)-1. This function maps this index space back in to unique elements represented as strings. Returns zero if the operation is not possible.
 

Special values

Integer gdxGetSpecialValues
 Retrieve the internal values for special values. Always non-zero.
 
Integer gdxMapValue
 Classify a value as a potential special value. Non-zero if D is a special value, zero otherwise.
 
Integer gdxResetSpecialValues
 Reset the internal values for special values. Always non-zero.
 
Integer gdxSetReadSpecialValues
 Set the internal values for special values when reading a GDX file. Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first. Always non-zero.
 
Integer gdxSetSpecialValues
 Set the internal values for special values. Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first. Note, values in AVals have to be unique. Non-zero if all values specified are unique, zero otherwise.
 

System/Symbol

Integer gdxFileInfo
 Returns file format number and compression level used. Always non-zero.
 
Integer gdxSymbolDim
 Returns dimensionality of a symbol.
 
Integer gdxSymbolInfo
 Returns information (name, dimension count, type) about a symbol from the symbol table. Returns zero if the symbol number is out of range, non-zero otherwise.
 
Integer gdxSymbolInfoX
 Returns additional information about a symbol. Returns zero if the symbol number is out of range, non-zero otherwise.
 
Integer gdxSystemInfo
 Returns the number of symbols and unique elements. Always non-zero.
 
Integer gdxCurrentDim
 Returns the dimension of the currently active symbol When reading or writing data, the dimension of the current active symbol is sometimes needed to convert arguments from strings to pchars (char ) etc.
 

Text for UELs

Integer gdxAddSetText
 Register a string in the string table Register a string in the string table and return the integer number assigned to this string. The integer value can be used to set the associated text of a set element. The string must follow the GAMS syntax rules for explanatory text e.g. not longer than 255 characters.
 
Integer gdxGetElemText
 Retrieve the string and node number for an entry in the string table. Returns zero if the operation is not possible.
 
Integer gdxSetHasText
 Test if any of the elements of the set has an associated text. Non-zero if the Set contains at least one unique element that has associated text, zero otherwise.
 
Integer gdxSetTextNodeNr
 Set the Node number for an entry in the string table. After registering a string with AddSetText, we can assign a node number for later retrieval. Returns zero if the operation is not possible.
 

Unique elements

Integer gdxUELRegisterDone
 Finish registration of unique elements. Returns zero if the operation is not possible.
 
Integer gdxUELRegisterMap
 Register unique element in mapped mode. A unique element must follow the GAMS rules when it contains quote characters. Returns zero if the operation is not possible.
 
Integer gdxUELRegisterMapStart
 Start registering unique elements in mapped mode. Returns zero if the operation is not possible.
 
Integer gdxUELRegisterRaw
 Register unique element in raw mode. This can only be used while writing to a GDX file. Returns zero if the operation is not possible.
 
Integer gdxUELRegisterRawStart
 Start registering unique elements in raw mode. Returns zero if the operation is not possible.
 
Integer gdxUELRegisterStr
 Register a unique element in string mode. A unique element must follow the GAMS rules when it contains quote characters. Non-zero if the element was registered, zero otherwise.
 
Integer gdxUELRegisterStrStart
 Start registering unique elements in string mode. Returns zero if the operation is not possible.
 
Integer gdxUMFindUEL
 Search for unique element by its string. Non-zero if the element was found, zero otherwise.
 
Integer gdxUMUelGet
 Get a unique element using an unmapped index. Returns zero if the operation is not possible.
 
Integer gdxUMUelInfo
 Return information about the unique elements (UELs). Always non-zero.
 
Integer gdxRenameUEL
 Rename unique element OldName to NewName.
 

Version/Information

Integer gdxGetDLLVersion
 Returns a version descriptor of the library. Always non-zero.
 
Integer gdxFileVersion
 Return strings for file version and file producer. Always non-zero.
 
Integer gdxSetTraceLevel
 Set the amount of trace (debug) information generated. Always non-zero.
 

Write Data

Integer gdxDataWriteDone
 Finish a write operation. Returns zero if the operation is not possible.
 
Integer gdxDataWriteMap
 Write a data element in mapped mode. Returns zero if the operation is not possible.
 
Integer gdxDataWriteMapStart
 Start writing a new symbol in mapped mode. Returns zero if the operation is not possible.
 
Integer gdxDataWriteRaw
 Write a data element in raw mode. Returns zero if the operation is not possible.
 
Integer gdxDataWriteRawStart
 Start writing a new symbol in raw mode. Returns zero if the operation is not possible.
 
Integer gdxDataWriteRawStartKeyBounds
 Start writing a new symbol in raw mode with bounds for UEL key indices being known in advance. This helps potentially reducing the required storage for the keys as smaller integral datatypes can be used. Returns zero if the operation is not possible.
 
Integer gdxDataWriteStr
 Write a data element in string mode. Each element string must follow the GAMS rules for unique elements. Returns zero if the operation is not possible.
 
Integer gdxDataWriteStrStart
 Start writing a new symbol in string mode. Returns zero if the operation is not possible or failed.
 

Definitions

gdxAllowBogusDomains 

Get flag to ignore using 1-dim sets as domain when their elements are not tracked (see gdxStoreDomainSets). In case the flag is enabled this is allowing potentially unsafe writing of records to symbols with one dimensional sets as domain, when GDX has no lookup table for the elements of this set. This can happen when `gdxStoreDomainSets` was disabled by the user to save memory. For backwards compatability, this is enabled by default. Return 1 (true) iff. using a 1-dim set as domain (when store domain sets option is disabled) should be ignored. Otherwise an error is raised (ERR_NODOMAINDATA).

Type
Property of type Boolean
Action
read

gdxAllowBogusDomainsSet 

Get flag to ignore using 1-dim sets as domain when their elements are not tracked (see gdxStoreDomainSets). In case the flag is enabled this is allowing potentially unsafe writing of records to symbols with one dimensional sets as domain, when GDX has no lookup table for the elements of this set. This can happen when `gdxStoreDomainSets` was disabled by the user to save memory. For backwards compatability, this is enabled by default. Return 1 (true) iff. using a 1-dim set as domain (when store domain sets option is disabled) should be ignored. Otherwise an error is raised (ERR_NODOMAINDATA).

Type
Property of type Boolean
Action
write

gdxMapAcronymsToNaN 

Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default.

Type
Property of type Boolean
Action
read

gdxMapAcronymsToNaNSet 

Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default.

Type
Property of type Boolean
Action
write

gdxStoreDomainSets 

Get flag to store one dimensional sets as potential domains, false (0) saves lots of space for large 1-dim sets that are no domains but can create inconsistent GDX files if used incorrectly. Returns 1 (true) iff. elements of 1-dim sets should be tracked for domain checking, 0 (false) otherwise.

Type
Property of type Boolean
Action
read

gdxStoreDomainSetsSet 

Get flag to store one dimensional sets as potential domains, false (0) saves lots of space for large 1-dim sets that are no domains but can create inconsistent GDX files if used incorrectly. Returns 1 (true) iff. elements of 1-dim sets should be tracked for domain checking, 0 (false) otherwise.

Type
Property of type Boolean
Action
write

gdxAcronymAdd 

Add a new acronym entry. This can be used to add entries before data is written. Returns negative value (<0) if the entry is not added.

This function can be used to add entries before data is written. When entries are added implicitly use gdxAcronymSetInfo to update the table.

See: gdxAcronymGetInfo, gdxAcronymCount.

Type
Function returns Integer
Returns
  • 0 If the entry is not added because of a duplicate name using the same value fo the index.
  • -1 If the entry is not added because of a duplicate name using a different value for the index.
  • Otherwise the index into the acronym table (1..gdxAcronymCount).
Parameters
  const  ShortString    AName
     Name of the acronym (up to 63 characters) The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique.
  const  ShortString    Txt
     Explanatory text of the acronym (up to 255 characters, mixed quotes will be unified to first occurring quote character).
   Integer    AIndx
     Index value of the acronym.

gdxAcronymCount 

Number of entries in the acronym table.

See: gdxAcronymSetInfo, gdxAcronymSetInfo.

Type
Function returns Integer
Returns
The number of entries in the acronym table.

gdxAcronymGetInfo 

Retrieve acronym information from the acronym table. Non-zero if the index into the acronym table is valid.

Attention: Make sure AName is 64 bytes and Txt 256 bytes wide to prevent overflow!

See: gdxAcronymSetInfo, gdxAcronymCount.

Type
Function returns Integer
Returns
Non-zero if the index into the acronym table is valid; false otherwise.
Parameters
   Integer    N
     Index into acronym table (range 1..AcronymCount).
  out  ShortString    AName
     Name of the acronym (up to 63 characters).
  out  ShortString    Txt
     Explanatory text of the acronym (up to 255 characters, mixed quote chars will be unified to first occurring quote).
  out  Integer    AIndx
     Index value of the acronym.

gdxAcronymGetMapping 

Get information how acronym values are remapped. When reading GDX data, we need to map indices for acronyms used in the GDX file to indices used by the reading program. Non-zero if the index into the acronym table is valid.

When reading GDX data, we need to map indices for acronyms used in the GDX file to indices used by the reading program. There is a problem when not all acronyms have been registered before reading the GDX data. We need to map an undefined index we read to a new value. The value of NextAutoAcronym is used for that.

See: gdxAcronymGetInfo, gdxAcronymCount, gdxAcronymNextNr.

Type
Function returns Integer
Returns
Non-zero if the index into the acronym table is valid; false otherwise.
Parameters
   Integer    N
     Index into acronym table; range from 1 to AcronymCount.
  out  Integer    orgIndx
     The Index used in the GDX file.
  out  Integer    newIndx
     The Index returned when reading GDX data.
  out  Integer    autoIndex
     Non-zero if the newIndx was generated using the value of NextAutoAcronym.

gdxAcronymIndex 

Get index value of an acronym. Returns zero if V does not represent an acronym.

See: gdxAcronymValue.

Type
Function returns Integer
Returns
Index of acronym value V; zero if V does not represent an acronym.
Parameters
   Double    V
     Input value possibly representing an acronym/Version string after return (gdxGetDLLVersion).

gdxAcronymName 

Find the name of an acronym value. Non-zero if a name for the acronym is defined. An unnamed acronym value will return a string of the form UnknownAcronymNNN, were NNN is the index of the acronym.

Attention: Supplied buffer for AName should be 64 bytes long to prevent overflow!

See: gdxAcronymIndex.

Type
Function returns Integer
Returns
Return non-zero if a name for the acronym is defined. Return zero if V does not represent an acronym value or a name is not defined. An unnamed acronym value will return a string of the form UnknownAcronymNNN; were NNN is the index of the acronym.
Parameters
   Double    V
     Input value possibly containing an acronym/Version string after return (gdxGetDLLVersion).
  out  ShortString    AName
     Name of acronym value or the empty string (can be up to 63 characters).

gdxAcronymNextNr 

Returns the value of the NextAutoAcronym variable and sets the variable to nv.

  • When we read from a GDX file and encounter an acronym that was not defined, we need to assign a new index for that acronym. The variable NextAutoAcronym is used for this purpose and is incremented for each new undefined acronym.
  • When NextAutoAcronym has a value of zero, the default, the value is ignored and the original index as stored in the GDX file is used for the index.

Type
Function returns Integer
Returns
Previous value of NextAutoAcronym.
Parameters
   Integer    NV
     New value for NextAutoAcronym; a value of less than zero is ignored.

gdxAcronymSetInfo 

Modify acronym information in the acronym table

  • When writing a GDX file, this function is used to provide the name of an acronym; in this case the Indx parameter must match.
  • When reading a GDX file, this function is used to provide the acronym index, and the AName parameter must match.

See: gdxAcronymGetInfo, gdxAcronymCount.

Type
Function returns Integer
Returns
Non-zero if the index into the acronym table is valid; false otherwise.
Parameters
   Integer    N
     Index into acronym table (range 1..AcronymCount).
  const  ShortString    AName
     Name of the acronym (up to 63 characters). The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique.
  const  ShortString    Txt
     Explanatory text of the acronym (up to 255 characters, mixed quote chars will be unified to first occurring quote).
   Integer    AIndx
     Index value of the acronym.

gdxAcronymValue 

Create an acronym value based on the index (AIndx should be greater than 0). Returns the calculated acronym value (zero if AIndx is <0).

See: gdxAcronymIndex.

Type
Function returns Double
Returns
The calculated acronym value; zero if Indx is not positive.
Parameters
   Integer    AIndx
     Index value; should be greater than zero.

gdxAddAlias 

Add an alias for a set to the symbol table. One of the two identifiers has to be a known set, an alias or "*" (universe); the other identifier is used as the new alias for the given set. The function gdxSymbolInfoX can be used to retrieve the set or alias associated with the identifier; it is returned as the UserInfo parameter.

Attention: One of the set identifiers must be a novel unique name.

See: gdxSymbolSetDomain.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    Id1
     First set identifier.
  const  ShortString    Id2
     Second set identifier.

gdxAddSetText 

Register a string in the string table Register a string in the string table and return the integer number assigned to this string. The integer value can be used to set the associated text of a set element. The string must follow the GAMS syntax rules for explanatory text e.g. not longer than 255 characters.

Attention: Mixing of single- and double-quotes in the explanatory text will be resolved by replacing all quote character occurrences with the first one in the text.

See: gdxGetElemText, gdxSetTextNodeNr.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    Txt
     The string to be registered (must not exceed 255 characters).
  out  Integer    TxtNr
     The index number assigned to this string (output argument).

gdxAutoConvert 

Returns the value of the AutoConvert variable and sets the variable to nv.

When we close a new GDX file, we look at the value of AutoConvert; if AutoConvert is non-zero, we look at the GDXCOMPRESS and GDXCONVERT environment variables to determine if conversion to an older file format is desired. We needed this logic so gdxcopy.exe can disable automatic file conversion.

Type
Function returns Integer
Returns
Previous value of AutoConvert.
Parameters
   Integer    NV
     New value for AutoConvert.

gdxClose 

Close a GDX file that was previously opened for reading or writing. Before the file is closed, any pending write operations will be finished. This does not free the GDX in-memory object. This method will automatically be called when the GDX object lifetime ends (e.g. being out of scope).

See: gdxOpenRead, gdxOpenWrite.

Type
Function returns Integer
Returns
Returns the value of gdxGetLastError.

gdxCurrentDim 

Returns the dimension of the currently active symbol When reading or writing data, the dimension of the current active symbol is sometimes needed to convert arguments from strings to pchars (char ) etc.

When reading or writing data, the dimension of the current active symbol is sometimes needed to convert arguments from strings to pchars (char ) etc. The currently active symbol is selected e.g. by starting a write- or read-operation and choosing its symbol number (SyNr).

See: gdxDataReadRawStart, gdxDataWriteRawStart.

Type
Function returns Integer
Returns
Dimension of current active symbol.

gdxDataErrorCount 

Query the number of error records.

After a write operation is finished (with gdxDataWriteDone), the data is sorted and written to the GDX file (for map- and string-mode). If there are duplicate records, the first record is written to the file and the duplicates are added to the error list.

When reading data using a filtered read operation, data records that were filtered out because an index is not in the user index space or not in a filter are added the error list.

See: gdxDataErrorRecord.

Type
Function returns Integer
Returns
The number of error records available.

gdxDataErrorRecord 

Retrieve an error record. Non-zero if the record number is valid.

Does not indicate domain violation for filtered/strict read with negative indices.

Attention:

  • Same as gdxDataErrorRecordX but negative UEL index numbers (for domain violations) are inverted, so the index is always >=0.
  • KeyInt must be big enough to hold one UEL index for each dimension! Values must have length >=5.

See: gdxDataErrorCount.

Type
Function returns Integer
Returns
Non-zero if the record number is valid, zero otherwise.
Parameters
   Integer    RecNr
     The number of the record to be retrieved (range = 1..NrErrorRecords); this argument is ignored in gdxDataReadMap
  var  TgdxUELIndex    KeyInt
     Index for the record (array of UEL numbers for each dimension).
  var  TgdxValues    Values
     Values for the record (level, marginal, lower-, upper-bound, scale).

gdxDataErrorRecordX 

Retrieve an error record. Non-zero if the record number is valid.

Also indicate domain violations for filtered/strict read with negative UEL index values.

Attention:

  • KeyInt must be big enough to hold one UEL index for each dimension!
  • Values must have length >=5.

See: gdxDataErrorCount.

Type
Function returns Integer
Returns
Non-zero if the record number is valid, zero otherwise.
Parameters
   Integer    RecNr
     The number of the record to be retrieved, (range 1..NrErrorRecords); this argument is ignored in gdxDataReadMap
  var  TgdxUELIndex    KeyInt
     Index for the record, negative uel indicates domain violation for filtered/strict read.
  var  TgdxValues    Values
     Values for the record (level, marginal, lower-, upper-bound, scale).

gdxDataReadDone 

Finish reading of a symbol in any mode (raw, mapped, string). . Returns zero if the operation is not possible.

See: gdxDataReadRawStart, gdxDataReadMapStart, gdxDataReadStrStart.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxDataReadFilteredStart 

Initialize the reading of a symbol in filtered mode. Returns zero if the operation is not possible.

See: gdxFilterRegisterStart, gdxDataReadMap, gdxDataReadRawStart, gdxDataReadStrStart, gdxDataReadDone.

Start reading data for a symbol in filtered mode. Each filter action (1..Dimension) describes how each index should be treated when reading a data record. When new unique elements are returned, they are added to the user index space automatically. The actual reading of records is done with DataReadMap.

The action codes are as follows:

Action codeResult
DOMC_UNMAPPEDThe index is not mapped into user space
DOMC_EXPANDNew unique elements encountered will be mapped into the user space
DOMC_STRICTIf the unique element in this position does not map into user space, the record will not be available and is added to the error list instead
FilterNumberIf the unique element in this position does not map into user space or is not enabled in this filter, the record will not be available and is added to the error list instead

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
  const  TgdxUELIndex    FilterAction
     Array of filter actions for each index position.
  out  Integer    NrRecs
     The maximum number of records available for reading. The actual number of records may be less when a filter is applied to the records read.

gdxDataReadMap 

Read the next record in mapped mode. Returns zero if the operation is not possible.

See: gdxDataReadMapStart, gdxDataReadFilteredStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    RecNr
     Ignored (left in for backward compatibility).
  var  TgdxUELIndex    KeyInt
     The index of the record.
  var  TgdxValues    Values
     The data of the record.
  out  Integer    DimFrst
     The first index position in KeyInt that changed.

gdxDataReadMapStart 

Initialize the reading of a symbol in mapped mode. Returns zero if the operation is not possible.

See: gdxDataReadMap, gdxDataReadRawStart, gdxDataReadStrStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
  out  Integer    NrRecs
     The maximum number of records available for reading. The actual number of records may be less when a filter is applied to the records read.

gdxDataReadRaw 

Read the next record in raw mode. Returns zero if the operation is not possible.

Attention: KeyInt must be big enough to hold one UEL index for each dimension! Values must have length >=5.

See: gdxDataReadRawStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise (e.g. no records left).
Parameters
  var  TgdxUELIndex    KeyInt
     The index of the record in UEL numbers for each dimension.
  var  TgdxValues    Values
     The data of the record (level, marginal, lower-, upper-bound, scale).
  out  Integer    DimFrst
     The first index position in KeyInt that changed.

gdxDataReadRawFast 

Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible.

Use a callback function to read a symbol in raw mode. Using a callback procedure to read the data is faster because we no longer have to check the context for each call to read a record.

See: gdxDataReadRaw, gdxDataReadMapStart, gdxDataReadStrStart, gdxDataReadDone, gdxDataReadRawFastFilt.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
  TDataStoreProc    DP
    Procedure (const Indx : TgdxUELIndex, const Vals : TgdxValues )
     Procedure that will be called for each data record. This procedure (return type=void) should have the following signature:
  • UEL index number keys (const int ),
  • values (level, marginal, lower-, upper-bound, scale) (const double )
  out  Integer    NrRecs
     The maximum number of records available for reading. The actual number of records may be less when a filter is applied to the records read.

gdxDataReadRawFastEx 

Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible.

Use a callback function to read a symbol in raw mode. Using a callback procedure to read the data is faster because we no longer have to check the context for each call to read a record.

See: gdxDataReadRawFast.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
  TDataStoreExProc    DP
    Function (const Indx : TgdxUELIndex, const Vals : TgdxValues, DimFrst : Integer, Uptr : Pointer ) returns Integer
     Procedure that will be called for each data record. This function (return type=integer) should return whether reading continues (=0 for stop, >=1 otherwise) and should have the following signature:
  • UEL index number keys (const int ),
  • values (level, marginal, lower-, upper-bound, scale) (const double ),
  • dimension of first change (int),
  • pointer to custom data (void )
  out  Integer    NrRecs
     The number of records available for reading.
   Pointer    Uptr
     Pointer to user memory that will be passed back with the callback.

gdxDataReadRawFastFilt 

Read a symbol in Raw mode while applying a filter using a callback procedure. Returns zero if the operation is not possible.

Read a slice of data, by fixing zero or more index positions in the data. When a data element is available, the callback procedure DP is called with the current index (as raw numbers) and the values.

See: gdxDataReadRawFast, gdxDataReadSliceStart, gdxDataSliceUELS, gdxDataReadDone, .

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range from 0 to NrSymbols; SyNr = 0 reads universe.
  const  TgdxStrIndex    UelFilterStr
     Each index can be fixed by setting the string for the unique element. Set an index position to the empty string in order not to fix that position. If the string is not-empty it should match an UEL name from the UEL table.
  TDataStoreFiltProc    DP
    Function (const Indx : TgdxUELIndex, const Vals : TgdxValues, Uptr : Pointer ) returns Integer
     Callback procedure which will be called for each available data item. This procedure (return type=void) should have the following signature:
  • UEL index number keys (const int ),
  • values (level, marginal, lower-, upper-bound, scale) (const double ),
  • pointer to custom data (void ).

gdxDataReadRawStart 

Initialize the reading of a symbol in raw mode. Returns zero if the operation is not possible.

See: gdxDataReadRaw, gdxDataReadMapStart, gdxDataReadStrStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
  out  Integer    NrRecs
     The maximum number of records available for reading. The actual number of records may be less when a filter is applied to the records read.

gdxDataReadSlice 

Read a slice of data from a data set, by fixing zero or more index positions in the data. When a data element is available, the callback procedure DP is called with the current index and the values. The indices used in the index vary from zero to the highest value minus one for that index position. This function can be called multiple times. Returns zero if the operation is not possible.

Attention: Supply one UEL filter str for each symbol dimension (up to 63 characters per str).

See: gdxDataReadSliceStart, gdxDataSliceUELS, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  TgdxStrIndex    UelFilterStr
     Each index can be fixed by setting the string for the unique element. Set an index position to the empty string in order not to fix that position.
  out  Integer    Dimen
     The dimension of the index space; this is the number of index positions that is not fixed.
  TDataStoreProc    DP
    Procedure (const Indx : TgdxUELIndex, const Vals : TgdxValues )
     Callback procedure which will be called for each available data item. Signature is
  • UEL index number keys for each symbol dimension (const int )
  • 5 double values (const double )

gdxDataReadSliceStart 

Prepare for the reading of a slice of data from a data set. The actual read of the data is done by calling gdxDataReadSlice. When finished reading, call gdxDataReadDone. Returns zero if the operation is not possible.

See: gdxDataReadSlice, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     Symbol number to read, range 1..NrSymbols; SyNr = 0 reads universe.
  var  TgdxUELIndex    ElemCounts
     Array of integers, each position indicating the number of unique indices in that position.

gdxDataReadStr 

Read the next record using strings for the unique elements. The reading should be initialized by calling DataReadStrStart. Returns zero if the operation is not possible or if there is no more data.

Attention: KeyStr must point to one string for each symbol dimension where each string buffer must have size of 64 bytes. Values must have length >=5 double entries.

See: gdxDataReadStrStart, gdxDataReadDone.

'

Type
Function returns Integer
Returns
Non-zero if the operation is possible; return zero if the operation is not possible or if there is no more data.
Parameters
  out  TgdxStrIndex    KeyStr
     The index of the record as strings for the unique elements. Array of strings with one string for each dimension.
  var  TgdxValues    Values
     The data of the record (level, marginal, lower-, upper-bound, scale).
  out  Integer    DimFrst
     The first index position in KeyStr that changed.

gdxDataReadStrStart 

Initialize the reading of a symbol in string mode. Returns zero if the operation is not possible.

Reading data using strings is the simplest way to read data. Every record read using DataReadStr will return the strings for the unique elements. Internal mapping is not affected by this function.

See: gdxDataReadStr, gdxDataReadRawStart, gdxDataReadMapStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
  out  Integer    NrRecs
     The maximum number of records available for reading. The actual number of records may be less when a filter is applied to the records read.

gdxDataSliceUELS 

Map a slice index in to the corresponding unique elements. After calling DataReadSliceStart, each index position is mapped from 0 to N(d)-1. This function maps this index space back in to unique elements represented as strings. Returns zero if the operation is not possible.

Attention: Both SliceKeyInt and KeyStr should match the symbol dimension with their length The string buffers pointed to by KeyStr should each be at least 64 bytes long to store up to 63 character UEL names.

See: gdxDataReadSliceStart, gdxDataReadDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  TgdxUELIndex    SliceKeyInt
     The slice index to be mapped to strings with one entry for each symbol dimension.
  out  TgdxStrIndex    KeyStr
     Array of strings containing the unique elements.

gdxDataWriteDone 

Finish a write operation. Returns zero if the operation is not possible.

For mapped- and string-mode the actual writing of the records to the GDX file happens here.

See: gdxDataErrorCount, gdxDataWriteRawStart, gdxDataWriteMapStart, gdxDataWriteStrStart.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxDataWriteMap 

Write a data element in mapped mode. Returns zero if the operation is not possible.

See: gdxDataWriteMapStart, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  TgdxUELIndex    KeyInt
     The index for this element using mapped values.
  const  TgdxValues    Values
     The values for this element.

gdxDataWriteMapStart 

Start writing a new symbol in mapped mode. Returns zero if the operation is not possible.

See: gdxDataWriteMap, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise
Parameters
  const  ShortString    SyId
     Name of the symbol (up to 63 characters) or acronym. The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique. Might be an empty string at gdxAcronymName.
  const  ShortString    ExplTxt
     Explanatory text for the symbol (up to 255 characters).
   Integer    Dimen
     Dimension of the symbol.
   Integer    Typ
     Type of the symbol.
   Integer    UserInfo
     User field value storing additional data; GAMS follows the following conventions:
TypeValue(s)
Aliased SetThe symbol number of the aliased set, or zero for the universe
SetZero
ParameterZero
VariableThe variable type: binary=1, integer=2, positive=3, negative=4, free=5, sos1=6, sos2=7, semicontinous=8, semiinteger=9
EquationThe equation type: eque=53, equg=54, equl=55, equn=56, equx=57, equc=58, equb=59

gdxDataWriteRaw 

Write a data element in raw mode. Returns zero if the operation is not possible.

When writing data in raw mode, the index space used is based on the internal index space. The indices used are in the range 1..NrUels but this is not enforced. Before we can write in raw mode, the unique elements (strings) should be registered first.

When writing raw, it assumed that the records are written in sorted order and that there are no duplicate records. Records that are not in sorted order or are duplicates will be added to the error list (see DataErrorCount and DataErrorRecord).

See: gdxDataWriteRawStart, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  TgdxUELIndex    KeyInt
     The index for this element.
  const  TgdxValues    Values
     The values for this element.

gdxDataWriteRawStart 

Start writing a new symbol in raw mode. Returns zero if the operation is not possible.

Raw mode flushes new records immediately to the GDX file (unlike mapped or string mode). The key indices for the record are provided as unique element numbers.

See: gdxDataWriteRaw, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    SyId
     Name of the symbol (up to 63 characters). The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique.
  const  ShortString    ExplTxt
     Explanatory text for the symbol (up to 255 characters).
   Integer    Dimen
     Dimension of the symbol (up to 20).
   Integer    Typ
     Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
   Integer    UserInfo
     User field value storing additional data; GAMS follows the following conventions:
Type Value(s)
Aliased Set The symbol number of the aliased set, or zero for the universe
Set Zero
Parameter Zero
Variable The variable type: binary=1, integer=2, positive=3, negative=4, free=5, sos1=6, sos2=7, semicontinous=8, semiinteger=9
Equation The equation type: eque=53, equg=54, equl=55, equn=56, equx=57, equc=58, equb=59

gdxDataWriteRawStartKeyBounds 

Start writing a new symbol in raw mode with bounds for UEL key indices being known in advance. This helps potentially reducing the required storage for the keys as smaller integral datatypes can be used. Returns zero if the operation is not possible.

Raw mode flushes new records immediately to the GDX file (unlike mapped or string mode). The key indices for the record are provided as unique element numbers.

See: gdxDataWriteRaw, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    SyId
     Name of the symbol (up to 63 characters). The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique.
  const  ShortString    ExplTxt
     Explanatory text for the symbol (up to 255 characters).
   Integer    Dimen
     Dimension of the symbol (up to 20).
   Integer    Typ
     Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
   Integer    UserInfo
     User field value storing additional data; GAMS follows the following conventions:
Type Value(s)
Aliased Set The symbol number of the aliased set, or zero for the universe
Set Zero
Parameter Zero
Variable The variable type: binary=1, integer=2, positive=3, negative=4, free=5, sos1=6, sos2=7, semicontinous=8, semiinteger=9
Equation The equation type: eque=53, equg=54, equl=55, equn=56, equx=57, equc=58, equb=59
  const  TgdxUELIndex    MinUELIndices
     Minimum UEL indices for each symbol dimension. Can help with shrinking storage for keys.
  const  TgdxUELIndex    MaxUELIndices
     Maximum UEL indices for each symbol dimension. Can help with shrinking storage for keys.

gdxDataWriteStr 

Write a data element in string mode. Each element string must follow the GAMS rules for unique elements. Returns zero if the operation is not possible.

  • When writing data using string elements, each string element is added to the internal unique element (UEL) table and assigned an index.
  • Writing using strings does not add the unique elements to the user mapped space.
  • Each element string must follow the GAMS rules for unique elements e.g. not exceeding 63 characters in length and not mixing single- and double-quotes.

Attention:

  • This write operation affects the in-memory GDX object.
  • Actual flushing of the records to the GDX file happens in gdxDataWriteDone.
  • KeyStr should point to one string for each symbol dimension.
  • Each key string should not be longer than 63 characters. Values should be big enough to store 5 double values.
  • Make sure there is a key string for each symbol dimension and each key string does not exceed 63 characters.
  • Make sure values does not contain more than 5 entries.
  • See: gdxDataWriteMapStart, gdxDataWriteDone.

    Type
    Function returns Integer
    Returns
    Non-zero if the operation is possible, zero otherwise.
    Parameters
      const  TgdxStrIndex    KeyStr
         The index for this element using strings for the unique elements. One entry for each symbol dimension.
      const  TgdxValues    Values
         The values for this element (level, marginal, lower-, upper-bound, scale).

gdxDataWriteStrStart 

Start writing a new symbol in string mode. Returns zero if the operation is not possible or failed.

Adds a new symbol and supplies the UEL keys of the records for each dimension as strings. UEL labels can be known or new (in which case they are added to the UEL table).

See: gdxDataWriteStr, gdxDataWriteDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    SyId
     Name of the symbol (limited to 63 characters). The first character of a symbol must be a letter. Following symbol characters may be letters, digits, and underscores. Symbol names must be new and unique.
  const  ShortString    ExplTxt
     Explanatory text for the symbol (limited to 255 characters). Mixed quote characters will be unified to first occurring one.
   Integer    Dimen
     Dimension of the symbol (limited to 20).
   Integer    Typ
     Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
   Integer    UserInfo
     Supply additional data. See gdxDataWriteRawStart for more information.

gdxErrorCount 

Returns the number of errors.

See: gdxGetLastError.

Type
Function returns Integer
Returns
Total number of errors encountered.

gdxErrorStr 

Returns the text for a given error number. Always non-zero.

Attention: Supplied buffer for error message ErrMsg should be at least 256 bytes long.

See: gdxGetLastError.

Type
Function returns Integer
Returns
Always returns non-zero.
Parameters
   Integer    ErrNr
     Error number.
  out  ShortString    ErrMsg
     Error message (output argument). Contains error text after return.

gdxFileInfo 

Returns file format number and compression level used. Always non-zero.

Type
Function returns Integer
Returns
Always returns non-zero.
Parameters
  out  Integer    FileVer
     File format number or zero if the file is not open.
  out  Integer    ComprLev
     Compression used; 0= no compression, 1=zlib.

gdxFileVersion 

Return strings for file version and file producer. Always non-zero.

Attention: Supplied buffers for FileStr and ProduceStr should be 256 bytes long to prevent overflow.

See: gdxOpenWrite, gdxOpenWriteEx.

Type
Function returns Integer
Returns
Always non-zero.
Parameters
  out  ShortString    FileStr
     Version string (out argument). Known versions are V5, V6U, V6C and V7.
  out  ShortString    ProduceStr
     Producer string (out argument). The producer is the application that wrote the GDX file.

gdxFilterExists 

Check if there is a filter defined based on its number as used in gdxFilterRegisterStart. Returns zero if the operation is not possible.

See: gdxFilterRegisterStart.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    FilterNr
     Filter number as used in FilterRegisterStart.

gdxFilterRegister 

Add a unique element to the current filter definition, zero if the index number is out of range or was never mapped into the user index space.

Register a unique element as part of the current filter. The function returns false if the index number is out of range of valid user indices or the index was never mapped into the user index space.

See: gdxFilterRegisterStart, gdxFilterRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    UelMap
     Unique element number in the user index space or -1 if element was never mapped.

gdxFilterRegisterDone 

Finish registration of unique elements for a filter. Returns zero if the operation is not possible.

See: gdxFilterRegisterStart, gdxFilterRegister.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxFilterRegisterStart 

Define a unique element filter. Returns zero if the operation is not possible.

Start the registration of a filter. A filter is used to map a number of elements to a single integer; the filter number. A filter number can later be used to specify a filter for an index position when reading data.

See: gdxFilterRegister, gdxFilterRegisterDone, gdxDataReadFilteredStart.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    FilterNr
     Filter number to be assigned.

gdxFindSymbol 

Search for a symbol by name in the symbol table; the search is not case-sensitive.

  • When the symbol is found, SyNr contains the symbol number and the function returns a non-zero integer.
  • When the symbol is not found, the function returns zero and SyNr is set to -1.

See: gdxSymbolInfo, gdxSymbolInfoX.

Type
Function returns Integer
Returns
Non-zero if the symbol is found, zero otherwise.
Parameters
  const  ShortString    SyId
     Name of the symbol (must not exceed 63 characters).
  out  Integer    SyNr
     Symbol number (>=1 if exists, 0 for universe and -1 if not found).

gdxGetDLLVersion 

Returns a version descriptor of the library. Always non-zero.

Attention: Output argument buffer V should be 256 bytes long.

Type
Function returns Integer
Returns
Always returns non-zero.
Parameters
  out  ShortString    V
     Contains version string after return.

gdxGetDomainElements 

Get the unique elements for a given dimension of a given symbol.

Using the data of a symbol, get the unique elements for a given index position. To achieve this, the symbols data is read and a tally is kept for the elements in the given index position. When a filter is specified, records that have elements in the specified index position that are outside the filter will be added to the list of DataErrorRecords.

See: gdxDataErrorRecord.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range 1..NrSymbols; SyNr = 0 reads universe.
   Integer    DimPos
     The dimension to use, range 1..dim.
   Integer    FilterNr
     Number of a previously registered filter or the value DOMC_EXPAND if no filter is wanted.
  TDomainIndexProc    DP
    Procedure ( RawIndex : Integer, MappedIndex : Integer, Uptr : Pointer )
     Callback procedure which will be called once for each available element (can be nil).
  out  Integer    NrElem
     Number of unique elements found.
   Pointer    Uptr
     User pointer; will be passed to the callback procedure.

gdxGetElemText 

Retrieve the string and node number for an entry in the string table. Returns zero if the operation is not possible.

  • When writing to a GDX file, this index is the value returned by calling gdxAddSetText.
  • When reading a GDX file, the index is returned as the level value when reading a set.
The Node number can be used as an index in a string table in the user space; the value is set by calling SetTextNodeNr.
If the Node number was never assigned, it will be returned as zero.

Attention: Buffer supplied in out argument string Txt should be 256 bytes wide to prevent overflow!

See: gdxAddSetText, gdxSetTextNodeNr.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    TxtNr
     String table index.
  out  ShortString    Txt
     Text found for the entry. Buffer should be 256 bytes wide.
  out  Integer    Node
     Node number (user space) found for the entry.

gdxGetLastError 

Returns the last error number or zero if there was no error. Calling this function will clear the last error stored.

When an error is encountered, an error code is stored which can be retrieved with this function. If subsequent errors occur before this function is called, the first error code will be maintained. Calling this function will clear the last error stored.

See: gdxErrorCount.

Type
Function returns Integer
Returns
The error number, or zero if there was no error.

gdxGetMemoryUsed 

Return the number of bytes used by the data objects.

Type
Function returns Int64
Returns
The number of bytes used by the data objects.

gdxGetSpecialValues 

Retrieve the internal values for special values. Always non-zero.

Attention: Output argument array Avals should have size for 7 elements.

See: gdxResetSpecialValues, gdxSetSpecialValues.

Type
Function returns Integer
Returns
Always non-zero.
Parameters
  var  TgdxSVals    AVals
     6-element array of special values used for Undef (0), NA (1), +Inf (2), -Inf (3), Eps (4), Acronym (6).

gdxGetUEL 

Get the string for a unique element using a mapped index. Returns zero if the operation is not possible.

Retrieve the string for an unique element based on a mapped index number.

Attention: Supplied buffer for storing the Uel name should be 64 bytes long to prevent overflow!

See: gdxUMUelGet.

Type
Function returns Integer
Returns
Return non-zero if the index is in a valid range, zero otherwise.
Parameters
   Integer    UelNr
     Index number in user space (range 1..NrUserElem).
  out  ShortString    Uel
     String for the unique element which may be up to 63 characters.

gdxMapValue 

Classify a value as a potential special value. Non-zero if D is a special value, zero otherwise.

See: gdxGetSpecialValues, gdxSetSpecialValues.

Type
Function returns Integer
Returns
Returns non-zero if D is a special value, zero otherwise.
Parameters
   Double    D
     Value to classify.
  out  Integer    sv
     Classification.

gdxOpenAppend 

Open an existing GDX file for output. Non-zero if the file can be opened, zero otherwise.

If a file extension is not supplied, the extension ''.gdx'' will be used. The return code is a system dependent I/O error. When appending to a GDX file, the symbol table, uel table etc will be read and the whole setup will be treated as if all symbols were just written to the GDX file. Replacing a symbol is not allowed; it will generate a duplicate symbol error.

See: gdxOpenRead, gdxOpenWrite, gdxOpenWriteEx.

'

Type
Function returns Integer
Returns
Returns non-zero if the file can be opened; zero otherwise.
Parameters
  const  ShortString    FileName
     File name of the GDX file to be created (arbitrary length).
  const  ShortString    Producer
     Name of program that appends to the GDX file (should not exceed 255 characters).
  out  Integer    ErrNr
     Returns an error code or zero if there is no error.

gdxOpenRead 

Open a GDX file for reading. Non-zero if the file can be opened, zero otherwise.

Open an existing GDX file for input. If a file extension is not supplied, the extension '.gdx' will be used. The return code is a system dependent I/O error. If the file was found, but is not a valid GDX file, the function GetLastError can be used to handle these type of errors.

See: gdxOpenWrite, gdxGetLastError.

Type
Function returns Integer
Returns
Returns non-zero if the file can be opened; zero otherwise.
Parameters
  const  ShortString    FileName
     File name of the GDX file to be opened (arbitrary length).
  out  Integer    ErrNr
     Returns an error code or zero if there is no error.

gdxOpenReadEx 

Open a GDX file for reading allowing for skipping sections. Non-zero if the file can be opened, zero otherwise.

Open an existing GDX file for input. If a file extension is not supplied, the extension '.gdx' will be used. The return code is a system dependent I/O error. If the file was found, but is not a valid GDX file, the function GetLastError can be used to handle these type of errors.

See: gdxOpenWrite, gdxGetLastError.

Type
Function returns Integer
Returns
Returns non-zero if the file can be opened; zero otherwise.
Parameters
  const  ShortString    FileName
     File name of the GDX file to be opened (arbitrary length).
   Integer    ReadMode
     Bitmap skip reading sections: 0-bit: string (1 skip reading string).
  out  Integer    ErrNr
     Returns an error code or zero if there is no error.

gdxOpenWrite 

Open a new GDX file for output. Non-zero if the file can be opened, zero otherwise.

Uses the environment variable GDXCOMPRESS to set compression argument for gdxOpenWriteEx. Potentially overwrites existing file with same name. If a file extension is not supplied, the extension '.gdx' will be used. The return code is a system dependent I/O error.

See: gdxOpenRead, gdxOpenWriteEx.

Type
Function returns Integer
Returns
Returns non-zero if the file can be opened; zero otherwise.
Parameters
  const  ShortString    FileName
     File name of the GDX file to be created with arbitrary length.
  const  ShortString    Producer
     Name of program that creates the GDX file (should not exceed 255 characters).
  out  Integer    ErrNr
     Returns an error code or zero if there is no error.

gdxOpenWriteEx 

Create a GDX file for writing with explicitly given compression flag. Non-zero if the file can be opened, zero otherwise.

Open a new GDX file for output. If a file extension is not supplied, the extension '.gdx' will be used. The return code is a system dependent I/O error.

Attention: When writing compressed, set the AutoConvert flag to zero so the file is not uncompressed after the gdxClose; see gdxAutoConvert.

See: gdxOpenRead, gdxOpenWrite, gdxAutoConvert.

Type
Function returns Integer
Returns
Returns non-zero if the file can be opened; zero otherwise.
Parameters
  const  ShortString    FileName
     File name of the GDX file to be created with arbitrary length.
  const  ShortString    Producer
     Name of program that creates the GDX file (should not exceed 255 characters).
   Integer    Compr
     Zero for no compression; non-zero uses compression (if available).
  out  Integer    ErrNr
     Returns an error code or zero if there is no error.

gdxRenameUEL 

Rename unique element OldName to NewName.

Attention: String for unique element (UEL) which may not exceed a length of 63 characters. Furthermore a UEL string must not mix single- and double-quotes.

Type
Function returns Integer
Returns
Zero if the renaming was possible; non-zero is an error indicator.
Parameters
  const  ShortString    OldName
     Name of an existing unique element (UEL).
  const  ShortString    NewName
     New name for the UEL. Must not exist in UEL table yet.

gdxResetSpecialValues 

Reset the internal values for special values. Always non-zero.

See: gdxSetSpecialValues, gdxGetSpecialValues.

Type
Function returns Integer
Returns
Always non-zero.

gdxSetHasText 

Test if any of the elements of the set has an associated text. Non-zero if the Set contains at least one unique element that has associated text, zero otherwise.

See: gdxSystemInfo, gdxSymbolInfo.

Type
Function returns Integer
Returns
Non-zero if the set contains at least one element that has associated text, zero otherwise.
Parameters
   Integer    SyNr
     Set symbol number (range 1..NrSymbols); SyNr = 0 reads universe.

gdxSetReadSpecialValues 

Set the internal values for special values when reading a GDX file. Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first. Always non-zero.

Note: Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first.

Attention: AVals must have length of at least 5 double values.

See: gdxSetSpecialValues, gdxResetSpecialValues, gdxGetSpecialValues.

Type
Function returns Integer
Returns
Always non-zero.
Parameters
  const  TgdxSVals    AVals
     5-element array of special values to be used for Undef, NA, +Inf, -Inf, and Eps. Note that the values do not have to be unique.

gdxSetSpecialValues 

Set the internal values for special values. Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first. Note, values in AVals have to be unique. Non-zero if all values specified are unique, zero otherwise.

Note: Before calling this function, initialize the array of special values by calling gdxGetSpecialValues first.

Attention: Size of AVals should be 7.

See: gdxSetReadSpecialValues, gdxResetSpecialValues, gdxGetSpecialValues.

Type
Function returns Integer
Returns
Non-zero if all values specified are unique, zero otherwise.
Parameters
  const  TgdxSVals    AVals
     Array of special values to be used Undef (0), NA (1), +Inf (2), -Inf (3), and EPS (4). Note that the values have to be unique and AVals should have length 7.

gdxSetTextNodeNr 

Set the Node number for an entry in the string table. After registering a string with AddSetText, we can assign a node number for later retrieval. Returns zero if the operation is not possible.

After registering a string with AddSetText, we can assign a node number for later retrieval. The node number is any integer which is stored without further restrictions.

See: gdxAddSetText, gdxGetElemText.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    TxtNr
     Index number of the entry to be modified.
   Integer    Node
     The new Node value for the entry.

gdxSetTraceLevel 

Set the amount of trace (debug) information generated. Always non-zero.

Type
Function returns Integer
Returns
Always non-zero.
Parameters
   Integer    N
     Tracing level N <= 0 no tracing N >= 3 maximum tracing.
  const  ShortString    s
     A string to be included in the trace output (arbitrary length).

gdxSymbIndxMaxLength 

Returns the length of the longest UEL used for every index position for a given symbol.

Attention: Make sure LengthInfo can store one integer for each symbol dimension.

See: gdxUELMaxLength.

Type
Function returns Integer
Returns
The length of the longest UEL found in the data (over all dimensions).
Parameters
   Integer    SyNr
     Symbol number (range 1..NrSymbols); SyNr = 0 reads universe.
  var  TgdxUELIndex    LengthInfo
     The longest length for each index position. This output argument should be able to store one integer for each symbol dimension.

gdxSymbMaxLength 

Returns the length of the longest symbol name in the GDX file.

Type
Function returns Integer
Returns
The number of characters in the longest symbol name.

gdxSymbolAddComment 

Add a line of comment text for a symbol. Returns zero if the operation is not possible.

Attention: A line of comment text can not contain more than 255 characters but there are no other restrictions on it.

See: gdxSymbolGetComment.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The symbol number (range 1..NrSymbols); if SyNr <= 0 the current symbol being written.
  const  ShortString    Txt
     String to add which should not exceed a length of 255 characters.

gdxSymbolDim 

Returns dimensionality of a symbol.

See: gdxSymbolInfo, gdxSymbolInfoX, gdxFindSymbol.

Type
Function returns Integer
Returns
-1 if the symbol number is not in the correct range, the symbol dimension otherwise.
Parameters
   Integer    SyNr
     The symbol number (range 0..NrSymbols); return universe info when SyNr = 0..

gdxSymbolGetComment 

Retrieve a line of comment text for a symbol. Returns zero if the operation is not possible.

Attention: Output argument string buffer must have size of 256 bytes.

See: gdxSymbolAddComment.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The symbol number (range 1..NrSymbols); SyNr = 0 reads universe.
   Integer    N
     Line number in the comment block (1..Count).
  out  ShortString    Txt
     String containing the line requested (empty on error). Buffer should be able to hold 255 characters. Potential causes for empty strings are symbol- (SyNr) or line-number (N) out of range.

gdxSymbolGetDomain 

Retrieve the domain of a symbol. Returns zero if the operation is not possible.

Attention: Integer array DomainSyNrs should be able to store one entry for each symbol dimension.

See: gdxSymbolSetDomain, gdxSymbolGetDomainX.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol (range 1..NrSymbols); SyNr = 0 reads universe.
  var  TgdxUELIndex    DomainSyNrs
     Array (length=symbol dim) returning the set identifiers or "*"; DomainSyNrs[D] will contain the index number of the one dimensional set or alias used as the domain for index position D. A value of zero represents the universe "*".

gdxSymbolGetDomainX 

Retrieve the domain of a symbol (using relaxed or domain information). Returns zero if the operation is not possible.

Attention: Make sure DomainIDs is able to store a domain name for each symbol dimension. Each domain name requires a 256 byte wide buffer to store its maximum of 255 characters.

See: gdxSymbolSetDomainX, gdxSymbolSetDomain.

Type
Function returns Integer
Returns
  • 0: If operation was not possible (Bad SyNr)
  • 1: No domain information was available
  • 2: Data used was defined using gdxSymbolSetDomainX
  • 3: Data used was defined using gdxSymbolSetDomain
Parameters
   Integer    SyNr
     The index number of the symbol (range 1..NrSymbols); SyNr = 0 reads universe.
  out  TgdxStrIndex    DomainIDs
     DomainIDs[D] will contain the strings as they were stored with the call gdxSymbolSetDomainX. If gdxSymbolSetDomainX was never called, but gdxSymbolSetDomain was called, that information will be used instead. Length of this array should by dimensionality of the symbol. The special domain name "*" denotes the universe domain (all known UELs).

gdxSymbolInfo 

Returns information (name, dimension count, type) about a symbol from the symbol table. Returns zero if the symbol number is out of range, non-zero otherwise.

Attention: SyId must be 64 characters long.

See: gdxSystemInfo, gdxSymbolInfoX, gdxSymbolDim, gdxFindSymbol.

Type
Function returns Integer
Returns
Zero if the symbol number is not in the correct range, non-zero otherwise.
Parameters
   Integer    SyNr
     The symbol number (range 0..NrSymbols); return universe info () when SyNr = 0.
  out  ShortString    SyId
     Name of the symbol (buffer should be 64 bytes long). Magic name "*" for universe.
  out  Integer    Dimen
     Dimension of the symbol (range 0..20).
  out  Integer    Typ
     Symbol type (set=0, parameter=1, variable=2, equation=3, alias=4).

gdxSymbolInfoX 

Returns additional information about a symbol. Returns zero if the symbol number is out of range, non-zero otherwise.

Attention: Make sure the output argument string buffer for ExplTxt has size of 256 bytes.

See: gdxSystemInfo, gdxSymbolInfo, gdxFindSymbol.

Type
Function returns Integer
Returns
Zero if the symbol number is not in the correct range, non-zero otherwise.
Parameters
   Integer    SyNr
     The symbol number (range 0..NrSymbols); return universe info when SyNr = 0.
  out  Integer    RecCnt
     Total number of records stored (unmapped); for the universe (SyNr = 0) this is the number of entries when the GDX file was opened for reading.
  out  Integer    UserInfo
     User field value storing additional data; GAMS follows the following conventions:
Type Value(s)
Aliased Set The symbol number of the aliased set, or zero for the universe
Set Zero
Parameter Zero
Variable The variable type: binary=1, integer=2, positive=3, negative=4, free=5, sos1=6, sos2=7, semicontinous=8, semiinteger=9
Equation The equation type: eque=53, equg=54, equl=55, equn=56, equx=57, equc=58, equb=59
  out  ShortString    ExplTxt
     Explanatory text for the symbol. Buffer for this output argument should be 256 bytes long.

gdxSymbolSetDomain 

Define the domain of a symbol for which a write data operation just started using DataWriteRawStart, DataWriteMapStart or DataWriteStrStart. Returns zero if the operation is not possible.

This function defines the domain for the symbol for which a write data operation just started using DataWriteRawStart, DataWriteMapStart or DataWriteStrStart. At this point the symbol and dimension is known, but no data has been written yet.

Each identifier will be checked to be a one dimensional set or an alias. When a domain is specified, write operations will be domain checked; records violating the domain will be added the the internal error list (see DataErrorCount and DataErrorRecord).

Attention: Make sure there is one buffer with size 64 bytes for each symbol dimension.

See: gdxSymbolGetDomain.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  TgdxStrIndex    DomainIDs
     Array of identifiers (domain names) or "*" (universe). One domain name for each symbol dimension.

gdxSymbolSetDomainX 

Define the domain of a symbol (relaxed version). Returns zero if the operation is not possible.

This function defines the relaxed domain information for the symbol SyNr. The identifiers will NOT be checked to be known one-dimensional sets, and no domain checking will be performed. This function can be called during or after the write operation. If domain checking is needed, use gdxSymbolSetDomain.

See: gdxSymbolSetDomain, gdxSymbolGetDomainX.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    SyNr
     The index number of the symbol, range from 0 to NrSymbols; SyNr = 0 reads universe.
  const  TgdxStrIndex    DomainIDs
     Array of identifiers (domain names) or "*" (universe). One domain name per symbol dimension with not more than 63 characters.

gdxSystemInfo 

Returns the number of symbols and unique elements. Always non-zero.

Type
Function returns Integer
Returns
Returns a non-zero value.
Parameters
  out  Integer    SyCnt
     Number of symbols (sets, parameters, ...) available in the GDX file.
  out  Integer    UelCnt
     Number of unique elements (UELs) stored in the GDX file.

gdxUELMaxLength 

Returns the length of the longest unique element (UEL) name.

See: gdxSymbIndxMaxLength.

Type
Function returns Integer
Returns
The length of the longest UEL name in the UEL table.

gdxUELRegisterDone 

Finish registration of unique elements. Returns zero if the operation is not possible.

See: gdxUELRegisterRawStart, gdxUELRegisterMapStart, gdxUELRegisterStrStart.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxUELRegisterMap 

Register unique element in mapped mode. A unique element must follow the GAMS rules when it contains quote characters. Returns zero if the operation is not possible.

UMap is the user assigned index for the element. Registering an element a second time is not considered an error as long as the same UMap is used. Assigning different elements with the same UMap value is an error. A unique element must follow the GAMS rules when it contains quote characters and not exceed 63 characters length.

See: gdxUELRegisterMapStart, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    UMap
     User index number to be assigned to the unique element, -1 if not found or the element was never mapped.
  const  ShortString    Uel
     String for unique element (max. 63 chars and no single-/double-quote mixing).

gdxUELRegisterMapStart 

Start registering unique elements in mapped mode. Returns zero if the operation is not possible.

See: gdxUELRegisterMap, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxUELRegisterRaw 

Register unique element in raw mode. This can only be used while writing to a GDX file. Returns zero if the operation is not possible.

The unique element (UEL) is registered in raw mode, i.e. the internally assigned integer index is determined by the system. Can only be used while writing to a GDX file and gdxUELRegisterRawStart was called beforehand.

See: gdxUELRegisterMap, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
  const  ShortString    Uel
     String for unique element (UEL) which may not exceed 63 characters in length. Furthermore a UEL string must not mix single- and double-quotes.

gdxUELRegisterRawStart 

Start registering unique elements in raw mode. Returns zero if the operation is not possible.

See: gdxUELRegisterRaw, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxUELRegisterStr 

Register a unique element in string mode. A unique element must follow the GAMS rules when it contains quote characters. Non-zero if the element was registered, zero otherwise.

The unique element is registered in user mapped space. The returned index is the next higher value. Registering an element a second time is not considered an error and the same index position will be returned. A unique element must follow the GAMS rules when it contains quote characters. Can only be used while writing to a GDX file and gdxUELRegisterStrStart was called beforehand.

See: gdxUELRegisterStrStart, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the element was registered, zero otherwise.
Parameters
  const  ShortString    Uel
     String for unique element (UEL) which may not exceed a length of 63 characters. Furthermore a UEL string must not mix single- and double-quotes.
  out  Integer    UelNr
     Internal index number assigned to this unique element in user space (or -1 if not found).

gdxUELRegisterStrStart 

Start registering unique elements in string mode. Returns zero if the operation is not possible.

See: gdxUELRegisterStr, gdxUELRegisterDone.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.

gdxUMFindUEL 

Search for unique element by its string. Non-zero if the element was found, zero otherwise.

Type
Function returns Integer
Returns
Non-zero if the element was found, zero otherwise.
Parameters
  const  ShortString    Uel
     String to be searched (not longer than 63 characters, don't mix single- and double-quotes).
  out  Integer    UelNr
     Internal unique element number or -1 if not found.
  out  Integer    UelMap
     User mapping for the element or -1 if not found or the element was never mapped.

gdxUMUelGet 

Get a unique element using an unmapped index. Returns zero if the operation is not possible.

Attention: Make sure buffer for Uel is at least 64 bytes long to prevent potential overflow.

See: gdxUMUelInfo, gdxGetUEL.

Type
Function returns Integer
Returns
Non-zero if the operation is possible, zero otherwise.
Parameters
   Integer    UelNr
     Element number (unmapped) (range 1..NrElem) or -1 if not found.
  out  ShortString    Uel
     String for unique element. Buffer should be 64 bytes long (to store maximum of 63 characters).
  out  Integer    UelMap
     User mapping for this element or -1 if element was never mapped.

gdxUMUelInfo 

Return information about the unique elements (UELs). Always non-zero.

See: gdxUMUelGet.

Type
Function returns Integer
Returns
Always returns non-zero.
Parameters
  out  Integer    UelCnt
     Total number of unique elements (UELs in GDX file plus new registered UELs).
  out  Integer    HighMap
     Highest user mapping index used.