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.
| |
Integer | gdxAcronymSetInfo |
Modify acronym information in the acronym table
| |
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.
| |
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 code | Result |
DOMC_UNMAPPED | The index is not mapped into user space |
DOMC_EXPAND | New unique elements encountered will be mapped into the user space |
DOMC_STRICT | If 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 |
FilterNumber | If 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: 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
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.
- 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).
See: gdxDataWriteMapStart, gdxDataWriteDone.
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.
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.