gdx::TGXFileObj Class Reference

#include <gdx.h>

Public Types
enum class	TraceLevels : uint8_t { trl_none , trl_errors , trl_some , trl_all }

Public Member Functions
	TGXFileObj (std::string &ErrMsg)
	Create a new GDX file object. Does not open a file yet. More...
	~TGXFileObj ()
	Dispose GDX file object. More...
void	SetTraceLevel (TraceLevels tl)
int	gdxStoreDomainSets () const
	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. More...
void	gdxStoreDomainSetsSet (int flag)
	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. More...
int	gdxAllowBogusDomains () const
	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). More...
void	gdxAllowBogusDomainsSet (int flag)
	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). More...
int	gdxMapAcronymsToNaN () const
	Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default. More...
void	gdxMapAcronymsToNaNSet (int flag)
	Flag to map all acronym values to the GAMS "Not a Number" special value. Disabled by default. More...
int	gdxAddAlias (const char *Id1, const char *Id2)
	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. More...
int	gdxAutoConvert (int NV)
	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. More...
int64_t	gdxGetMemoryUsed ()
	Return the number of bytes used by the data objects. More...
Acronyms
int	gdxAcronymAdd (const char *AName, const char *Txt, int AIndx)
	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. More...
int	gdxAcronymCount () const
	Number of entries in the acronym table. More...
int	gdxAcronymGetInfo (int N, char *AName, char *Txt, int &AIndx) const
	Retrieve acronym information from the acronym table. Non-zero if the index into the acronym table is valid. More...
int	gdxAcronymGetMapping (int N, int &orgIndx, int &newIndx, int &autoIndex)
	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. More...
int	gdxAcronymIndex (double V) const
	Get index value of an acronym. Returns zero if V does not represent an acronym. More...
int	gdxAcronymName (double V, char *AName)
	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. More...
int	gdxAcronymNextNr (int NV)
	Returns the value of the NextAutoAcronym variable and sets the variable to nv. More...
int	gdxAcronymSetInfo (int N, const char *AName, const char *Txt, int AIndx)
	Modify acronym information in the acronym table. More...
double	gdxAcronymValue (int AIndx) const
	Create an acronym value based on the index (AIndx should be greater than 0). Returns the calculated acronym value (zero if AIndx is <0). More...
Comment
int	gdxSymbolAddComment (int SyNr, const char *Txt)
	Add a line of comment text for a symbol. Returns zero if the operation is not possible. More...
int	gdxSymbolGetComment (int SyNr, int N, char *Txt)
	Retrieve a line of comment text for a symbol. Returns zero if the operation is not possible. More...
Domain
int	gdxSymbolGetDomain (int SyNr, int *DomainSyNrs)
	Retrieve the domain of a symbol. Returns zero if the operation is not possible. More...
int	gdxSymbolGetDomainX (int SyNr, char **DomainIDs)
	Retrieve the domain of a symbol (using relaxed or domain information). Returns zero if the operation is not possible. More...
int	gdxSymbolSetDomain (const char **DomainIDs)
	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. More...
int	gdxSymbolSetDomainX (int SyNr, const char **DomainIDs)
	Define the domain of a symbol (relaxed version). Returns zero if the operation is not possible. More...
int	gdxGetDomainElements (int SyNr, int DimPos, int FilterNr, TDomainIndexProc_t DP, int &NrElem, void *Uptr)
	Get the unique elements for a given dimension of a given symbol. More...
File (Open/Close)
int	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). More...
int	gdxOpenAppend (const char *FileName, const char *Producer, int &ErrNr)
	Open an existing GDX file for output. Non-zero if the file can be opened, zero otherwise. More...
int	gdxOpenRead (const char *FileName, int &ErrNr)
	Open a GDX file for reading. Non-zero if the file can be opened, zero otherwise. More...
int	gdxOpenReadEx (const char *FileName, int ReadMode, int &ErrNr)
	Open a GDX file for reading allowing for skipping sections. Non-zero if the file can be opened, zero otherwise. More...
int	gdxOpenWrite (const char *FileName, const char *Producer, int &ErrNr)
	Open a new GDX file for output. Non-zero if the file can be opened, zero otherwise. More...
int	gdxOpenWriteEx (const char *FileName, const char *Producer, int Compr, int &ErrNr)
	Create a GDX file for writing with explicitly given compression flag. Non-zero if the file can be opened, zero otherwise. More...
Filters
int	gdxFilterExists (int FilterNr)
	Check if there is a filter defined based on its number as used in gdxFilterRegisterStart. Returns zero if the operation is not possible. More...
int	gdxFilterRegister (int UelMap)
	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. More...
int	gdxFilterRegisterDone ()
	Finish registration of unique elements for a filter. Returns zero if the operation is not possible. More...
int	gdxFilterRegisterStart (int FilterNr)
	Define a unique element filter. Returns zero if the operation is not possible. More...
Information
int	gdxFindSymbol (const char *SyId, int &SyNr)
	Search for a symbol by name in the symbol table; the search is not case-sensitive. More...
int	gdxGetUEL (int UelNr, char *Uel) const
	Get the string for a unique element using a mapped index. Returns zero if the operation is not possible. More...
Longest symbol UEL
int	gdxSymbIndxMaxLength (int SyNr, int *LengthInfo)
	Returns the length of the longest UEL used for every index position for a given symbol. More...
int	gdxSymbMaxLength () const
	Returns the length of the longest symbol name in the GDX file. More...
int	gdxUELMaxLength () const
	Returns the length of the longest unique element (UEL) name. More...
Read Data
int	gdxDataErrorCount () const
	Query the number of error records. More...
int	gdxDataErrorRecord (int RecNr, int *KeyInt, double *Values)
	Retrieve an error record. Non-zero if the record number is valid. More...
int	gdxDataErrorRecordX (int RecNr, int *KeyInt, double *Values)
	Retrieve an error record. Non-zero if the record number is valid. More...
int	gdxDataReadDone ()
	Finish reading of a symbol in any mode (raw, mapped, string). . Returns zero if the operation is not possible. More...
int	gdxDataReadFilteredStart (int SyNr, const int *FilterAction, int &NrRecs)
	Initialize the reading of a symbol in filtered mode. Returns zero if the operation is not possible. More...
int	gdxDataReadMap (int RecNr, int *KeyInt, double *Values, int &DimFrst)
	Read the next record in mapped mode. Returns zero if the operation is not possible. More...
int	gdxDataReadMapStart (int SyNr, int &NrRecs)
	Initialize the reading of a symbol in mapped mode. Returns zero if the operation is not possible. More...
int	gdxDataReadRaw (int *KeyInt, double *Values, int &DimFrst)
	Read the next record in raw mode. Returns zero if the operation is not possible. More...
int	gdxDataReadRawFast (int SyNr, TDataStoreProc_t DP, int &NrRecs)
	Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible. More...
int	gdxDataReadRawFastEx (int SyNr, TDataStoreExProc_t DP, int &NrRecs, void *Uptr)
	Read a symbol in Raw mode using a callback procedure. Returns zero if the operation is not possible. More...
int	gdxDataReadRawFastFilt (int SyNr, const char **UelFilterStr, TDataStoreFiltProc_t DP)
	Read a symbol in Raw mode while applying a filter using a callback procedure. Returns zero if the operation is not possible. More...
int	gdxDataReadRawStart (int SyNr, int &NrRecs)
	Initialize the reading of a symbol in raw mode. Returns zero if the operation is not possible. More...
int	gdxDataReadSlice (const char **UelFilterStr, int &Dimen, TDataStoreProc_t DP)
	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. More...
int	gdxDataReadSliceStart (int SyNr, int *ElemCounts)
	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. More...
int	gdxDataReadStr (char **KeyStr, double *Values, int &DimFrst)
	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. More...
int	gdxDataReadStrStart (int SyNr, int &NrRecs)
	Initialize the reading of a symbol in string mode. Returns zero if the operation is not possible. More...
int	gdxDataSliceUELS (const int *SliceKeyInt, char **KeyStr)
	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. More...
Special values
int	gdxGetSpecialValues (double *AVals)
	Retrieve the internal values for special values. Always non-zero. More...
int	gdxMapValue (double D, int &sv)
	Classify a value as a potential special value. Non-zero if D is a special value, zero otherwise. More...
int	gdxResetSpecialValues ()
	Reset the internal values for special values. Always non-zero. More...
int	gdxSetReadSpecialValues (const double *AVals)
	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. More...
int	gdxSetSpecialValues (const double *AVals)
	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. More...
System/Symbol
int	gdxFileInfo (int &FileVer, int &ComprLev) const
	Returns file format number and compression level used. Always non-zero. More...
int	gdxSymbolDim (int SyNr)
	Returns dimensionality of a symbol. More...
int	gdxSymbolInfo (int SyNr, char *SyId, int &Dimen, int &Typ)
	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. More...
int	gdxSymbolInfoX (int SyNr, int &RecCnt, int &UserInfo, char *ExplTxt)
	Returns additional information about a symbol. Returns zero if the symbol number is out of range, non-zero otherwise. More...
int	gdxSystemInfo (int &SyCnt, int &UelCnt) const
	Returns the number of symbols and unique elements. Always non-zero. More...
int	gdxCurrentDim () const
	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. More...
Text for UELs
int	gdxAddSetText (const char *Txt, int &TxtNr)
	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. More...
int	gdxGetElemText (int TxtNr, char *Txt, int &Node)
	Retrieve the string and node number for an entry in the string table. Returns zero if the operation is not possible. More...
int	gdxSetHasText (int SyNr)
	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. More...
int	gdxSetTextNodeNr (int TxtNr, int Node)
	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. More...
Unique elements
int	gdxUELRegisterDone ()
	Finish registration of unique elements. Returns zero if the operation is not possible. More...
int	gdxUELRegisterMap (int UMap, const char *Uel)
	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. More...
int	gdxUELRegisterMapStart ()
	Start registering unique elements in mapped mode. Returns zero if the operation is not possible. More...
int	gdxUELRegisterRaw (const char *Uel)
	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. More...
int	gdxUELRegisterRawStart ()
	Start registering unique elements in raw mode. Returns zero if the operation is not possible. More...
int	gdxUELRegisterStr (const char *Uel, int &UelNr)
	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. More...
int	gdxUELRegisterStrStart ()
	Start registering unique elements in string mode. Returns zero if the operation is not possible. More...
int	gdxUMFindUEL (const char *Uel, int &UelNr, int &UelMap)
	Search for unique element by its string. Non-zero if the element was found, zero otherwise. More...
int	gdxUMUelGet (int UelNr, char *Uel, int &UelMap)
	Get a unique element using an unmapped index. Returns zero if the operation is not possible. More...
int	gdxUMUelInfo (int &UelCnt, int &HighMap) const
	Return information about the unique elements (UELs). Always non-zero. More...
int	gdxRenameUEL (const char *OldName, const char *NewName)
	Rename unique element OldName to NewName. More...
Write Data
int	gdxDataWriteDone ()
	Finish a write operation. Returns zero if the operation is not possible. More...
int	gdxDataWriteMap (const int *KeyInt, const double *Values)
	Write a data element in mapped mode. Returns zero if the operation is not possible. More...
int	gdxDataWriteMapStart (const char *SyId, const char *ExplTxt, int Dimen, int Typ, int UserInfo)
	Start writing a new symbol in mapped mode. Returns zero if the operation is not possible. More...
int	gdxDataWriteRaw (const int *KeyInt, const double *Values)
	Write a data element in raw mode. Returns zero if the operation is not possible. More...
int	gdxDataWriteRawStart (const char *SyId, const char *ExplTxt, int Dimen, int Typ, int UserInfo)
	Start writing a new symbol in raw mode. Returns zero if the operation is not possible. More...
int	gdxDataWriteRawStartKeyBounds (const char *SyId, const char *ExplTxt, int Dimen, int Typ, int UserInfo, const int *MinUELIndices, const int *MaxUELIndices)
	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. More...
int	gdxDataWriteStr (const char **KeyStr, const double *Values)
	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. More...
int	gdxDataWriteStrStart (const char *SyId, const char *ExplTxt, int Dimen, int Typ, int UserInfo)
	Start writing a new symbol in string mode. Returns zero if the operation is not possible or failed. More...

Public Attributes
bool	gdxGetDomainElements_DP_CallByRef {}
bool	gdxDataReadRawFastFilt_DP_CallByRef {}
bool	gdxDataReadRawFastEx_DP_CallByRef {}

Errors
int	gdxErrorCount () const
	Returns the number of errors. More...
int	gdxGetLastError ()
	Returns the last error number or zero if there was no error. Calling this function will clear the last error stored. More...
static int	gdxErrorStr (int ErrNr, char *ErrMsg)
	Returns the text for a given error number. Always non-zero. More...

Version/Information
int	gdxFileVersion (char *FileStr, char *ProduceStr) const
	Return strings for file version and file producer. Always non-zero. More...
int	gdxSetTraceLevel (int N, const char *s)
	Set the amount of trace (debug) information generated. Always non-zero. More...
static int	gdxGetDLLVersion (char *V)
	Returns a version descriptor of the library. Always non-zero. More...

Detailed Description

Class for reading and writing GDX files through a efficient low-level interface

Constructor & Destructor Documentation

TGXFileObj()

gdx::TGXFileObj::TGXFileObj ( std::string &  ErrMsg )

explicit

Create a new GDX file object. Does not open a file yet.

Constructor of GDX file object

Parameters

ErrMsg

Out argument for storing potential error messages. Will be empty when there is no error.

~TGXFileObj()

gdx::TGXFileObj::~TGXFileObj

(

)

Dispose GDX file object.

Destructor of GDX file object

Tears down a file GDX object and potentially closes (and flushes) a file opened for writing.

Member Function Documentation

gdxAcronymAdd()

int gdx::TGXFileObj::gdxAcronymAdd	(	const char *	AName,
		const char *	Txt,
		int	AIndx
	)

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.

Parameters

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.
Txt	Explanatory text of the acronym (up to 255 characters, mixed quotes will be unified to first occurring quote character).
AIndx	Index value of the acronym.

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

See also

gdxAcronymGetInfo, gdxAcronymCount

gdxAcronymCount()

int gdx::TGXFileObj::gdxAcronymCount

(

)

const

Number of entries in the acronym table.

Returns

The number of entries in the acronym table.

See also

gdxAcronymSetInfo, gdxAcronymSetInfo

gdxAcronymGetInfo()

int gdx::TGXFileObj::gdxAcronymGetInfo	(	int	N,
		char *	AName,
		char *	Txt,
		int &	AIndx
	)		const

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

Parameters

N	Index into acronym table (range 1..AcronymCount).
AName	Name of the acronym (up to 63 characters).
Txt	Explanatory text of the acronym (up to 255 characters, mixed quote chars will be unified to first occurring quote).
AIndx	Index value of the acronym.

Attention

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

Returns

Non-zero if the index into the acronym table is valid; false otherwise.

See also

gdxAcronymSetInfo, gdxAcronymCount

gdxAcronymGetMapping()

int gdx::TGXFileObj::gdxAcronymGetMapping	(	int	N,
		int &	orgIndx,
		int &	newIndx,
		int &	autoIndex
	)

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.

Parameters

N	Index into acronym table; range from 1 to AcronymCount.
orgIndx	The Index used in the GDX file.
newIndx	The Index returned when reading GDX data.
autoIndex	Non-zero if the newIndx was generated using the value of NextAutoAcronym.

Returns

Non-zero if the index into the acronym table is valid; false otherwise.

See also

gdxAcronymGetInfo, gdxAcronymCount, gdxAcronymNextNr

gdxAcronymIndex()

int gdx::TGXFileObj::gdxAcronymIndex

(

double

V

)

const

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

Parameters

V	Input value possibly representing an acronym/Version string after return (gdxGetDLLVersion).

Returns

Index of acronym value V; zero if V does not represent an acronym.

See also

gdxAcronymValue

gdxAcronymName()

int gdx::TGXFileObj::gdxAcronymName	(	double	V,
		char *	AName
	)

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.

Parameters

V	Input value possibly containing an acronym/Version string after return (gdxGetDLLVersion).
AName	Name of acronym value or the empty string (can be up to 63 characters).

Attention

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

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.

See also

gdxAcronymIndex

gdxAcronymNextNr()

int gdx::TGXFileObj::gdxAcronymNextNr

(

int

NV

)

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.

Parameters

NV	New value for NextAutoAcronym; a value of less than zero is ignored.

Returns

Previous value of NextAutoAcronym.

gdxAcronymSetInfo()

int gdx::TGXFileObj::gdxAcronymSetInfo	(	int	N,
		const char *	AName,
		const char *	Txt,
		int	AIndx
	)

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.

Parameters

N	Index into acronym table (range 1..AcronymCount).
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.
Txt	Explanatory text of the acronym (up to 255 characters, mixed quote chars will be unified to first occurring quote).
AIndx	Index value of the acronym.

Returns

Non-zero if the index into the acronym table is valid; false otherwise.

See also

gdxAcronymGetInfo, gdxAcronymCount

gdxAcronymValue()

double gdx::TGXFileObj::gdxAcronymValue

(

int

AIndx

)

const

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

Parameters

AIndx

Index value; should be greater than zero.

Returns

The calculated acronym value; zero if Indx is not positive.

See also

gdxAcronymIndex

gdxAddAlias()

int gdx::TGXFileObj::gdxAddAlias	(	const char *	Id1,
		const char *	Id2
	)

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.

Parameters

Id1	First set identifier.
Id2	Second set identifier.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolSetDomain

gdxAddSetText()

int gdx::TGXFileObj::gdxAddSetText	(	const char *	Txt,
		int &	TxtNr
	)

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.

Parameters

Txt	The string to be registered (must not exceed 255 characters).
TxtNr	The index number assigned to this string (output argument).

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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxGetElemText, gdxSetTextNodeNr

gdxAllowBogusDomains()

int gdx::TGXFileObj::gdxAllowBogusDomains

(

)

const

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

Returns

1 (true) iff. flag is set, 0 (false) otherwise.

gdxAllowBogusDomainsSet()

void gdx::TGXFileObj::gdxAllowBogusDomainsSet

(

int

flag

)

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

Parameters

flag	1 (true) to enable and 0 (false) to disable flag.

gdxAutoConvert()

int gdx::TGXFileObj::gdxAutoConvert

(

int

NV

)

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.

Parameters

NV	New value for AutoConvert.

Returns

Previous value of AutoConvert.

gdxClose()

int gdx::TGXFileObj::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).

Returns

Returns the value of gdxGetLastError.

See also

gdxOpenRead, gdxOpenWrite

gdxCurrentDim()

int gdx::TGXFileObj::gdxCurrentDim

(

)

const

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

Returns

Dimension of current active symbol.

See also

gdxDataReadRawStart, gdxDataWriteRawStart

gdxDataErrorCount()

int gdx::TGXFileObj::gdxDataErrorCount

(

)

const

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.

Returns

The number of error records available.

See also

gdxDataErrorRecord

gdxDataErrorRecord()

int gdx::TGXFileObj::gdxDataErrorRecord	(	int	RecNr,
		int *	KeyInt,
		double *	Values
	)

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

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

Parameters

RecNr	The number of the record to be retrieved (range = 1..NrErrorRecords); this argument is ignored in gdxDataReadMap
KeyInt	Index for the record (array of UEL numbers for each dimension).
Values	Values for the record (level, marginal, lower-, upper-bound, scale).

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.

Returns

Non-zero if the record number is valid, zero otherwise.

See also

gdxDataErrorCount

gdxDataErrorRecordX()

int gdx::TGXFileObj::gdxDataErrorRecordX	(	int	RecNr,
		int *	KeyInt,
		double *	Values
	)

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.

Parameters

RecNr	The number of the record to be retrieved, (range 1..NrErrorRecords); this argument is ignored in gdxDataReadMap
KeyInt	Index for the record, negative uel indicates domain violation for filtered/strict read.
Values	Values for the record (level, marginal, lower-, upper-bound, scale).

Attention

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

Returns

Non-zero if the record number is valid, zero otherwise.

See also

gdxDataErrorCount

gdxDataReadDone()

int gdx::TGXFileObj::gdxDataReadDone

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadRawStart, gdxDataReadMapStart, gdxDataReadStrStart

gdxDataReadFilteredStart()

int gdx::TGXFileObj::gdxDataReadFilteredStart	(	int	SyNr,
		const int *	FilterAction,
		int &	NrRecs
	)

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

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

Parameters

SyNr	The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
FilterAction	Array of filter actions for each index position.
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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxFilterRegisterStart, gdxDataReadMap, gdxDataReadRawStart, gdxDataReadStrStart, gdxDataReadDone

gdxDataReadMap()

int gdx::TGXFileObj::gdxDataReadMap	(	int	RecNr,
		int *	KeyInt,
		double *	Values,
		int &	DimFrst
	)

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

Parameters

RecNr	Ignored (left in for backward compatibility).
KeyInt	The index of the record.
Values	The data of the record.
DimFrst	The first index position in KeyInt that changed.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadMapStart, gdxDataReadFilteredStart, gdxDataReadDone

gdxDataReadMapStart()

int gdx::TGXFileObj::gdxDataReadMapStart	(	int	SyNr,
		int &	NrRecs
	)

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

Parameters

SyNr	The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadMap, gdxDataReadRawStart, gdxDataReadStrStart, gdxDataReadDone

gdxDataReadRaw()

int gdx::TGXFileObj::gdxDataReadRaw	(	int *	KeyInt,
		double *	Values,
		int &	DimFrst
	)

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

Parameters

KeyInt	The index of the record in UEL numbers for each dimension.
Values	The data of the record (level, marginal, lower-, upper-bound, scale).
DimFrst	The first index position in KeyInt that changed.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise (e.g. no records left).

See also

gdxDataReadRawStart, gdxDataReadDone

gdxDataReadRawFast()

int gdx::TGXFileObj::gdxDataReadRawFast	(	int	SyNr,
		TDataStoreProc_t	DP,
		int &	NrRecs
	)

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.

Parameters

SyNr	The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
DP	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 )
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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadRaw, gdxDataReadMapStart, gdxDataReadStrStart, gdxDataReadDone, gdxDataReadRawFastFilt

gdxDataReadRawFastEx()

int gdx::TGXFileObj::gdxDataReadRawFastEx	(	int	SyNr,
		TDataStoreExProc_t	DP,
		int &	NrRecs,
		void *	Uptr
	)

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.

Parameters

SyNr	The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
DP	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 )
NrRecs	The number of records available for reading.
Uptr	Pointer to user memory that will be passed back with the callback.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadRawFast

gdxDataReadRawFastFilt()

int gdx::TGXFileObj::gdxDataReadRawFastFilt	(	int	SyNr,
		const char **	UelFilterStr,
		TDataStoreFiltProc_t	DP
	)

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.

Parameters

SyNr	The index number of the symbol, range from 0 to NrSymbols; SyNr = 0 reads universe.
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.
DP	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 ).

Returns

Non-zero if the operation is possible, zero otherwise.

auto DPCallBack = [](const int *Indx, const double *Vals, void *Uptr)
{
  std::string s;
  int UelMap;
  ((TGXFileObj*)Uptr).gdxUMUelGet(Indx[1], s, UelMap);
  std::cout << s << ' ' << Vals[vallevel] << std::endl;
  return 1;
};
TgdxStrIndex IndxS;
IndxS[0] = "i200"; IndxS[1] = "";
pgx.gdxDataReadRawFastFilt(1, IndxS, DPCallBack);

See also

gdxDataReadRawFast, gdxDataReadSliceStart, gdxDataSliceUELS, gdxDataReadDone

gdxDataReadRawStart()

int gdx::TGXFileObj::gdxDataReadRawStart	(	int	SyNr,
		int &	NrRecs
	)

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

Parameters

SyNr	The index number of the symbol, range 0..NrSymbols; SyNr = 0 reads universe.
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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadRaw, gdxDataReadMapStart, gdxDataReadStrStart, gdxDataReadDone

gdxDataReadSlice()

int gdx::TGXFileObj::gdxDataReadSlice	(	const char **	UelFilterStr,
		int &	Dimen,
		TDataStoreProc_t	DP
	)

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.

Parameters

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.
Dimen	The dimension of the index space; this is the number of index positions that is not fixed.
DP	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 )

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadSliceStart, gdxDataSliceUELS, gdxDataReadDone

gdxDataReadSliceStart()

int gdx::TGXFileObj::gdxDataReadSliceStart	(	int	SyNr,
		int *	ElemCounts
	)

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.

Parameters

SyNr	Symbol number to read, range 1..NrSymbols; SyNr = 0 reads universe.
ElemCounts	Array of integers, each position indicating the number of unique indices in that position.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadSlice, gdxDataReadDone

gdxDataReadStr()

int gdx::TGXFileObj::gdxDataReadStr	(	char **	KeyStr,
		double *	Values,
		int &	DimFrst
	)

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.

Parameters

KeyStr	The index of the record as strings for the unique elements. Array of strings with one string for each dimension.
Values	The data of the record (level, marginal, lower-, upper-bound, scale).
DimFrst	The first index position in KeyStr that changed.

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.

'

Returns

Non-zero if the operation is possible; return zero if the operation is not possible or if there is no more data.

See also

gdxDataReadStrStart, gdxDataReadDone

gdxDataReadStrStart()

int gdx::TGXFileObj::gdxDataReadStrStart	(	int	SyNr,
		int &	NrRecs
	)

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.

Parameters

SyNr	The index number of the symbol (range 0..NrSymbols); SyNr = 0 reads universe.
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.

Returns

Non-zero if the operation is possible, zero otherwise.

if(pgx.gdxDataReadStrStart(1,NrRecs)) {
  while(pgx.gdxDataReadStr(Uels,Vals)) {
    ...
  }
  pgx.gdxDataReadDone();
}

See also

gdxDataReadStr, gdxDataReadRawStart, gdxDataReadMapStart, gdxDataReadDone

gdxDataSliceUELS()

int gdx::TGXFileObj::gdxDataSliceUELS	(	const int *	SliceKeyInt,
		char **	KeyStr
	)

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.

Parameters

SliceKeyInt	The slice index to be mapped to strings with one entry for each symbol dimension.
KeyStr	Array of strings containing the unique elements.

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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataReadSliceStart, gdxDataReadDone

gdxDataWriteDone()

int gdx::TGXFileObj::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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataErrorCount, gdxDataWriteRawStart, gdxDataWriteMapStart, gdxDataWriteStrStart

gdxDataWriteMap()

int gdx::TGXFileObj::gdxDataWriteMap	(	const int *	KeyInt,
		const double *	Values
	)

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

Parameters

KeyInt	The index for this element using mapped values.
Values	The values for this element.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataWriteMapStart, gdxDataWriteDone

gdxDataWriteMapStart()

int gdx::TGXFileObj::gdxDataWriteMapStart	(	const char *	SyId,
		const char *	ExplTxt,
		int	Dimen,
		int	Typ,
		int	UserInfo
	)

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

Parameters

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.
ExplTxt	Explanatory text for the symbol (up to 255 characters).
Dimen	Dimension of the symbol.
Typ	Type of the symbol.
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

Returns

Non-zero if the operation is possible, zero otherwise

See also

gdxDataWriteMap, gdxDataWriteDone

gdxDataWriteRaw()

int gdx::TGXFileObj::gdxDataWriteRaw	(	const int *	KeyInt,
		const double *	Values
	)

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

Parameters

KeyInt	The index for this element.
Values	The values for this element.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataWriteRawStart, gdxDataWriteDone

gdxDataWriteRawStart()

int gdx::TGXFileObj::gdxDataWriteRawStart	(	const char *	SyId,
		const char *	ExplTxt,
		int	Dimen,
		int	Typ,
		int	UserInfo
	)

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.

Parameters

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.
ExplTxt	Explanatory text for the symbol (up to 255 characters).
Dimen	Dimension of the symbol (up to 20).
Typ	Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataWriteRaw, gdxDataWriteDone

gdxDataWriteRawStartKeyBounds()

int gdx::TGXFileObj::gdxDataWriteRawStartKeyBounds	(	const char *	SyId,
		const char *	ExplTxt,
		int	Dimen,
		int	Typ,
		int	UserInfo,
		const int *	MinUELIndices,
		const int *	MaxUELIndices
	)

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.

Parameters

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.
ExplTxt	Explanatory text for the symbol (up to 255 characters).
Dimen	Dimension of the symbol (up to 20).
Typ	Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
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
MinUELIndices	Minimum UEL indices for each symbol dimension. Can help with shrinking storage for keys.
MaxUELIndices	Maximum UEL indices for each symbol dimension. Can help with shrinking storage for keys.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataWriteRaw, gdxDataWriteDone

gdxDataWriteStr()

int gdx::TGXFileObj::gdxDataWriteStr	(	const char **	KeyStr,
		const double *	Values
	)

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.

Parameters

KeyStr	The index for this element using strings for the unique elements. One entry for each symbol dimension.
Values	The values for this element (level, marginal, lower-, upper-bound, scale).

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

Returns

Non-zero if the operation is possible, zero otherwise.

gdxDataWriteStrStart()

int gdx::TGXFileObj::gdxDataWriteStrStart	(	const char *	SyId,
		const char *	ExplTxt,
		int	Dimen,
		int	Typ,
		int	UserInfo
	)

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

Parameters

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.
ExplTxt	Explanatory text for the symbol (limited to 255 characters). Mixed quote characters will be unified to first occurring one.
Dimen	Dimension of the symbol (limited to 20).
Typ	Type of the symbol (set=0, parameter=1, variable=2, equation=3, alias=4).
UserInfo	Supply additional data. See gdxDataWriteRawStart for more information.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxDataWriteStr, gdxDataWriteDone

gdxErrorCount()

int gdx::TGXFileObj::gdxErrorCount

(

)

const

Returns the number of errors.

Returns

Total number of errors encountered.

See also

gdxGetLastError

gdxErrorStr()

int gdx::TGXFileObj::gdxErrorStr ( int  ErrNr, char *  ErrMsg  )

static

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

Parameters

ErrNr	Error number.
ErrMsg	Error message (output argument). Contains error text after return.

Attention

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

Returns

Always returns non-zero.

See also

gdxGetLastError

gdxFileInfo()

int gdx::TGXFileObj::gdxFileInfo	(	int &	FileVer,
		int &	ComprLev
	)		const

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

Parameters

FileVer	File format number or zero if the file is not open.
ComprLev	Compression used; 0= no compression, 1=zlib.

Returns

Always returns non-zero.

gdxFileVersion()

int gdx::TGXFileObj::gdxFileVersion	(	char *	FileStr,
		char *	ProduceStr
	)		const

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

Parameters

FileStr	Version string (out argument). Known versions are V5, V6U, V6C and V7.
ProduceStr	Producer string (out argument). The producer is the application that wrote the GDX file.

Attention

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

Returns

Always non-zero.

See also

gdxOpenWrite, gdxOpenWriteEx

gdxFilterExists()

int gdx::TGXFileObj::gdxFilterExists

(

int

FilterNr

)

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

Parameters

FilterNr

Filter number as used in FilterRegisterStart.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxFilterRegisterStart

gdxFilterRegister()

int gdx::TGXFileObj::gdxFilterRegister

(

int

UelMap

)

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.

Parameters

UelMap

Unique element number in the user index space or -1 if element was never mapped.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxFilterRegisterStart, gdxFilterRegisterDone

gdxFilterRegisterDone()

int gdx::TGXFileObj::gdxFilterRegisterDone

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxFilterRegisterStart, gdxFilterRegister

gdxFilterRegisterStart()

int gdx::TGXFileObj::gdxFilterRegisterStart

(

int

FilterNr

)

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.

Parameters

FilterNr

Filter number to be assigned.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxFilterRegister, gdxFilterRegisterDone, gdxDataReadFilteredStart

gdxFindSymbol()

int gdx::TGXFileObj::gdxFindSymbol	(	const char *	SyId,
		int &	SyNr
	)

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.

Parameters

SyId	Name of the symbol (must not exceed 63 characters).
SyNr	Symbol number (>=1 if exists, 0 for universe and -1 if not found).

Returns

Non-zero if the symbol is found, zero otherwise.

See also

gdxSymbolInfo, gdxSymbolInfoX

gdxGetDLLVersion()

int gdx::TGXFileObj::gdxGetDLLVersion ( char *  V )

static

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

Parameters

V	Contains version string after return.

Attention

Output argument buffer V should be 256 bytes long.

Returns

Always returns non-zero.

gdxGetDomainElements()

int gdx::TGXFileObj::gdxGetDomainElements	(	int	SyNr,
		int	DimPos,
		int	FilterNr,
		TDomainIndexProc_t	DP,
		int &	NrElem,
		void *	Uptr
	)

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.

Parameters

SyNr	The index number of the symbol, range 1..NrSymbols; SyNr = 0 reads universe.
DimPos	The dimension to use, range 1..dim.
FilterNr	Number of a previously registered filter or the value DOMC_EXPAND if no filter is wanted.
DP	Callback procedure which will be called once for each available element (can be nil).
NrElem	Number of unique elements found.
Uptr	User pointer; will be passed to the callback procedure.

Returns

Non-zero if the operation is possible, zero otherwise.

int Cnt;
auto DataDomainCB = [](int RawNr, int MappedNr, void *UPtr) {
    std::cout << RawNr << " (" << MappedNr << ")" << std::endl;
};
pgx.gdxGetDomainElements(1, 1, DOMC_EXPAND, nullptr, cnt);
std::cout << "Domain count only = " << cnt << std::endl;
pgx.gdxGetDomainElements(1, 1, DOMC_EXPAND, DataDomainCB, cnt);
std::cout << "Get domain count = " << cnt << std::endl;
pgx.gdxGetDomainElements(1, 1, 7, DataDomainCB, cnt);
std::cout << "Using filter 7; number of records in error list = " << gdxDataErrorCount(PGX) << std::endl;

See also

gdxDataErrorRecord

gdxGetElemText()

int gdx::TGXFileObj::gdxGetElemText	(	int	TxtNr,
		char *	Txt,
		int &	Node
	)

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.

Parameters

TxtNr	String table index.
Txt	Text found for the entry. Buffer should be 256 bytes wide.
Node	Node number (user space) found for the entry.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

// assumes we are reading using strings
while(pgx.gdxDataReadStr(Uels, Vals)) {
   for(int D{}; D<Dim; D++)
      std::cout << Uels[D] << " ";
   int indx = std::round(Vals[vallevel]);
   if(indx > 0) {
      pgx.gdxGetElemText(indx, S, N);
      std::cout << "txt = " << S << "Node = " << N;
   }
   std::cout << std::endl;
}

See also

gdxAddSetText, gdxSetTextNodeNr

gdxGetLastError()

int gdx::TGXFileObj::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.

Returns

The error number, or zero if there was no error.

See also

gdxErrorCount

gdxGetMemoryUsed()

int64_t gdx::TGXFileObj::gdxGetMemoryUsed

(

)

Return the number of bytes used by the data objects.

Returns

The number of bytes used by the data objects.

gdxGetSpecialValues()

int gdx::TGXFileObj::gdxGetSpecialValues

(

double *

AVals

)

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

Parameters

AVals

6-element array of special values used for Undef (0), NA (1), +Inf (2), -Inf (3), Eps (4), Acronym (6).

Attention

Output argument array Avals should have size for 7 elements.

Returns

Always non-zero.

See also

gdxResetSpecialValues, gdxSetSpecialValues

gdxGetUEL()

int gdx::TGXFileObj::gdxGetUEL	(	int	UelNr,
		char *	Uel
	)		const

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.

Parameters

UelNr	Index number in user space (range 1..NrUserElem).
Uel	String for the unique element which may be up to 63 characters.

Attention

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

Returns

Return non-zero if the index is in a valid range, zero otherwise.

See also

gdxUMUelGet

gdxMapAcronymsToNaN()

int gdx::TGXFileObj::gdxMapAcronymsToNaN

(

)

const

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

Returns

1 (true) iff. flag is set, 0 (false) otherwise.

gdxMapAcronymsToNaNSet()

void gdx::TGXFileObj::gdxMapAcronymsToNaNSet

(

int

flag

)

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

Parameters

flag	1 (true) to enable and 0 (false) to disable flag.

gdxMapValue()

int gdx::TGXFileObj::gdxMapValue	(	double	D,
		int &	sv
	)

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

Parameters

D	Value to classify.
sv	Classification.

Returns

Returns non-zero if D is a special value, zero otherwise.

See also

gdxGetSpecialValues, gdxSetSpecialValues

gdxOpenAppend()

int gdx::TGXFileObj::gdxOpenAppend	(	const char *	FileName,
		const char *	Producer,
		int &	ErrNr
	)

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

Parameters

FileName	File name of the GDX file to be created (arbitrary length).
Producer	Name of program that appends to the GDX file (should not exceed 255 characters).
ErrNr	Returns an error code or zero if there is no error.

Returns

Returns non-zero if the file can be opened; zero otherwise.

std::string Msg;
TGXFileObj pgx {Msg}
int ErrCode;
pgx.gdxOpenAppend("file1.gdx","Examples", ErrCode);
if(ErrCode) {
  [ ... ]
}

See also

gdxOpenRead, gdxOpenWrite, gdxOpenWriteEx

gdxOpenRead()

int gdx::TGXFileObj::gdxOpenRead	(	const char *	FileName,
		int &	ErrNr
	)

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.

Parameters

FileName	File name of the GDX file to be opened (arbitrary length).
ErrNr	Returns an error code or zero if there is no error.

Returns

Returns non-zero if the file can be opened; zero otherwise.

std::string errMsg;
TGXFileObj pgx{errMsg};
pgx.gdxOpenRead("file1.gdx", ErrNr);
if(ErrNr) {
  [...]
}

See also

gdxOpenWrite, gdxGetLastError

gdxOpenReadEx()

int gdx::TGXFileObj::gdxOpenReadEx	(	const char *	FileName,
		int	ReadMode,
		int &	ErrNr
	)

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.

Parameters

FileName	File name of the GDX file to be opened (arbitrary length).
ReadMode	Bitmap skip reading sections: 0-bit: string (1 skip reading string).
ErrNr	Returns an error code or zero if there is no error.

Returns

Returns non-zero if the file can be opened; zero otherwise.

int ErrNr;
pgx.gdxOpenReadEx("file1.gdx", fmOpenRead, ErrNr);
if(ErrNr) {
   [...]
}

See also

gdxOpenWrite, gdxGetLastError

gdxOpenWrite()

int gdx::TGXFileObj::gdxOpenWrite	(	const char *	FileName,
		const char *	Producer,
		int &	ErrNr
	)

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.

Parameters

FileName	File name of the GDX file to be created with arbitrary length.
Producer	Name of program that creates the GDX file (should not exceed 255 characters).
ErrNr	Returns an error code or zero if there is no error.

Returns

Returns non-zero if the file can be opened; zero otherwise.

See also

gdxOpenRead, gdxOpenWriteEx

gdxOpenWriteEx()

int gdx::TGXFileObj::gdxOpenWriteEx	(	const char *	FileName,
		const char *	Producer,
		int	Compr,
		int &	ErrNr
	)

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.

Parameters

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

Attention

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

Returns

Returns non-zero if the file can be opened; zero otherwise.

std::string errMsg;
TGXFileObj pgx{errMsg};
if(!errMsg.empty()) {
    std::cout << "Failure with GDX: " << errMsg << std::endl;
    return;
}
int ErrCode;
pgx.gdxOpenWriteEx("file1.gdx", "Examples", 1, ErrCode);
pgx.gdxAutoConvert(0);
if(ErrCode) {
[ ... ]
}

See also

gdxOpenRead, gdxOpenWrite, gdxAutoConvert

gdxRenameUEL()

int gdx::TGXFileObj::gdxRenameUEL	(	const char *	OldName,
		const char *	NewName
	)

Rename unique element OldName to NewName.

Parameters

OldName	Name of an existing unique element (UEL).
NewName	New name for the UEL. Must not exist in UEL table yet.

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.

Returns

Zero if the renaming was possible; non-zero is an error indicator.

gdxResetSpecialValues()

int gdx::TGXFileObj::gdxResetSpecialValues

(

)

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

Returns

Always non-zero.

See also

gdxSetSpecialValues, gdxGetSpecialValues

gdxSetHasText()

int gdx::TGXFileObj::gdxSetHasText

(

int

SyNr

)

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.

Parameters

SyNr	Set symbol number (range 1..NrSymbols); SyNr = 0 reads universe.

Returns

Non-zero if the set contains at least one element that has associated text, zero otherwise.

See also

gdxSystemInfo, gdxSymbolInfo

gdxSetReadSpecialValues()

int gdx::TGXFileObj::gdxSetReadSpecialValues

(

const double *

AVals

)

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.

Parameters

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.

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.

Returns

Always non-zero.

See also

gdxSetSpecialValues, gdxResetSpecialValues, gdxGetSpecialValues

gdxSetSpecialValues()

int gdx::TGXFileObj::gdxSetSpecialValues

(

const double *

AVals

)

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.

Parameters

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.

Note

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

Attention

Size of AVals should be 7.

Returns

Non-zero if all values specified are unique, zero otherwise.

See also

gdxSetReadSpecialValues, gdxResetSpecialValues, gdxGetSpecialValues

gdxSetTextNodeNr()

int gdx::TGXFileObj::gdxSetTextNodeNr	(	int	TxtNr,
		int	Node
	)

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.

Parameters

TxtNr	Index number of the entry to be modified.
Node	The new Node value for the entry.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxAddSetText, gdxGetElemText

gdxSetTraceLevel()

int gdx::TGXFileObj::gdxSetTraceLevel	(	int	N,
		const char *	s
	)

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

Parameters

N	Tracing level N <= 0 no tracing N >= 3 maximum tracing.
s	A string to be included in the trace output (arbitrary length).

Returns

Always non-zero.

! GetStdHandle(STD_OUTPUT_HANDLE) <> INVALID_HANDLE_VALUE;

gdxStoreDomainSets()

int gdx::TGXFileObj::gdxStoreDomainSets

(

)

const

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.

Returns

1 (true) iff. flag is set, 0 (false) otherwise.

gdxStoreDomainSetsSet()

void gdx::TGXFileObj::gdxStoreDomainSetsSet

(

int

flag

)

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.

Parameters

flag	1 (true) to enable and 0 (false) to disable flag.

gdxSymbIndxMaxLength()

int gdx::TGXFileObj::gdxSymbIndxMaxLength	(	int	SyNr,
		int *	LengthInfo
	)

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

Parameters

SyNr	Symbol number (range 1..NrSymbols); SyNr = 0 reads universe.
LengthInfo	The longest length for each index position. This output argument should be able to store one integer for each symbol dimension.

Attention

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

Returns

The length of the longest UEL found in the data (over all dimensions).

See also

gdxUELMaxLength

gdxSymbMaxLength()

int gdx::TGXFileObj::gdxSymbMaxLength

(

)

const

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

Returns

The number of characters in the longest symbol name.

gdxSymbolAddComment()

int gdx::TGXFileObj::gdxSymbolAddComment	(	int	SyNr,
		const char *	Txt
	)

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

Parameters

SyNr	The symbol number (range 1..NrSymbols); if SyNr <= 0 the current symbol being written.
Txt	String to add which should not exceed a length of 255 characters.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolGetComment

gdxSymbolDim()

int gdx::TGXFileObj::gdxSymbolDim

(

int

SyNr

)

Returns dimensionality of a symbol.

Parameters

SyNr	The symbol number (range 0..NrSymbols); return universe info when SyNr = 0..

Returns

-1 if the symbol number is not in the correct range, the symbol dimension otherwise.

See also

gdxSymbolInfo, gdxSymbolInfoX, gdxFindSymbol

gdxSymbolGetComment()

int gdx::TGXFileObj::gdxSymbolGetComment	(	int	SyNr,
		int	N,
		char *	Txt
	)

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

Parameters

SyNr	The symbol number (range 1..NrSymbols); SyNr = 0 reads universe.
N	Line number in the comment block (1..Count).
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.

Attention

Output argument string buffer must have size of 256 bytes.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolAddComment

gdxSymbolGetDomain()

int gdx::TGXFileObj::gdxSymbolGetDomain	(	int	SyNr,
		int *	DomainSyNrs
	)

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

Parameters

SyNr	The index number of the symbol (range 1..NrSymbols); SyNr = 0 reads universe.
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 "*".

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolSetDomain, gdxSymbolGetDomainX

gdxSymbolGetDomainX()

int gdx::TGXFileObj::gdxSymbolGetDomainX	(	int	SyNr,
		char **	DomainIDs
	)

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

Parameters

SyNr	The index number of the symbol (range 1..NrSymbols); SyNr = 0 reads universe.
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).

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.

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

See also

gdxSymbolSetDomainX, gdxSymbolSetDomain

gdxSymbolInfo()

int gdx::TGXFileObj::gdxSymbolInfo	(	int	SyNr,
		char *	SyId,
		int &	Dimen,
		int &	Typ
	)

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.

Parameters

SyNr	The symbol number (range 0..NrSymbols); return universe info () when SyNr = 0.
SyId	Name of the symbol (buffer should be 64 bytes long). Magic name "*" for universe.
Dimen	Dimension of the symbol (range 0..20).
Typ	Symbol type (set=0, parameter=1, variable=2, equation=3, alias=4).

Attention

SyId must be 64 characters long.

Returns

Zero if the symbol number is not in the correct range, non-zero otherwise.

See also

gdxSystemInfo, gdxSymbolInfoX, gdxSymbolDim, gdxFindSymbol

gdxSymbolInfoX()

int gdx::TGXFileObj::gdxSymbolInfoX	(	int	SyNr,
		int &	RecCnt,
		int &	UserInfo,
		char *	ExplTxt
	)

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

Parameters

SyNr	The symbol number (range 0..NrSymbols); return universe info when SyNr = 0.
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.
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
ExplTxt	Explanatory text for the symbol. Buffer for this output argument should be 256 bytes long.

Attention

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

Returns

Zero if the symbol number is not in the correct range, non-zero otherwise.

See also

gdxSystemInfo, gdxSymbolInfo, gdxFindSymbol

gdxSymbolSetDomain()

int gdx::TGXFileObj::gdxSymbolSetDomain

(

const char **

DomainIDs

)

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

Parameters

DomainIDs

Array of identifiers (domain names) or "*" (universe). One domain name for each symbol dimension.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolGetDomain

gdxSymbolSetDomainX()

int gdx::TGXFileObj::gdxSymbolSetDomainX	(	int	SyNr,
		const char **	DomainIDs
	)

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.

Parameters

SyNr	The index number of the symbol, range from 0 to NrSymbols; SyNr = 0 reads universe.
DomainIDs	Array of identifiers (domain names) or "*" (universe). One domain name per symbol dimension with not more than 63 characters.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxSymbolSetDomain, gdxSymbolGetDomainX

gdxSystemInfo()

int gdx::TGXFileObj::gdxSystemInfo	(	int &	SyCnt,
		int &	UelCnt
	)		const

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

Parameters

SyCnt	Number of symbols (sets, parameters, ...) available in the GDX file.
UelCnt	Number of unique elements (UELs) stored in the GDX file.

Returns

Returns a non-zero value.

gdxUELMaxLength()

int gdx::TGXFileObj::gdxUELMaxLength

(

)

const

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

Returns

The length of the longest UEL name in the UEL table.

See also

gdxSymbIndxMaxLength

gdxUELRegisterDone()

int gdx::TGXFileObj::gdxUELRegisterDone

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterRawStart, gdxUELRegisterMapStart, gdxUELRegisterStrStart

gdxUELRegisterMap()

int gdx::TGXFileObj::gdxUELRegisterMap	(	int	UMap,
		const char *	Uel
	)

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.

Parameters

UMap	User index number to be assigned to the unique element, -1 if not found or the element was never mapped.
Uel	String for unique element (max. 63 chars and no single-/double-quote mixing).

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterMapStart, gdxUELRegisterDone

gdxUELRegisterMapStart()

int gdx::TGXFileObj::gdxUELRegisterMapStart

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterMap, gdxUELRegisterDone

gdxUELRegisterRaw()

int gdx::TGXFileObj::gdxUELRegisterRaw

(

const char *

Uel

)

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.

Parameters

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.

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterMap, gdxUELRegisterDone

gdxUELRegisterRawStart()

int gdx::TGXFileObj::gdxUELRegisterRawStart

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterRaw, gdxUELRegisterDone

gdxUELRegisterStr()

int gdx::TGXFileObj::gdxUELRegisterStr	(	const char *	Uel,
		int &	UelNr
	)

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.

Parameters

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.
UelNr	Internal index number assigned to this unique element in user space (or -1 if not found).

Returns

Non-zero if the element was registered, zero otherwise.

See also

gdxUELRegisterStrStart, gdxUELRegisterDone

gdxUELRegisterStrStart()

int gdx::TGXFileObj::gdxUELRegisterStrStart

(

)

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUELRegisterStr, gdxUELRegisterDone

gdxUMFindUEL()

int gdx::TGXFileObj::gdxUMFindUEL	(	const char *	Uel,
		int &	UelNr,
		int &	UelMap
	)

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

Parameters

Uel	String to be searched (not longer than 63 characters, don't mix single- and double-quotes).
UelNr	Internal unique element number or -1 if not found.
UelMap	User mapping for the element or -1 if not found or the element was never mapped.

Returns

Non-zero if the element was found, zero otherwise.

gdxUMUelGet()

int gdx::TGXFileObj::gdxUMUelGet	(	int	UelNr,
		char *	Uel,
		int &	UelMap
	)

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

Parameters

UelNr	Element number (unmapped) (range 1..NrElem) or -1 if not found.
Uel	String for unique element. Buffer should be 64 bytes long (to store maximum of 63 characters).
UelMap	User mapping for this element or -1 if element was never mapped.

Attention

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

Returns

Non-zero if the operation is possible, zero otherwise.

See also

gdxUMUelInfo, gdxGetUEL

gdxUMUelInfo()

int gdx::TGXFileObj::gdxUMUelInfo	(	int &	UelCnt,
		int &	HighMap
	)		const

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

Parameters

UelCnt	Total number of unique elements (UELs in GDX file plus new registered UELs).
HighMap	Highest user mapping index used.

Returns

Always returns non-zero.

See also

gdxUMUelGet

---

The documentation for this class was generated from the following files:

• src/gdx.h
• src/gxfile.cpp