Communicating Individual Identifier Values
Communicating identifier values
With every identifier handle AIMMS lets you retrieve all associated nondefault data values on an element-by-element basis. In addition, AIMMS lets you search whether a nondefault value exists for a particular element tuple, and make assignments to individual element tuples. this table lists all the available AIMMS API functions for this purpose.
AimmsValueCard returns the cardinality of a handle,
i.e. the number of nondefault elements of the associated identifier
slice. You can call this function, for instance, when you need to
allocate memory for the data structures in your own code before actually
retrieving the data.
Retrieving nondefault values
AimmsValueNext retrieve nondefault values associated with a handle
on an element-by-element basis.
AimmsValueResetHandleresets the handle to the position just before the first nondefault element.
AimmsValueSearchexpects an input tuple of element numbers (in the slice domain), and returns the first tuple for which a nondefault value exists on or following the input tuple.
AimmsValueNextreturns the first nondefault element directly following the element returned by the last call to
AimmsValueSearch, or the first element if the function
AimmsValueResetHandlewas called last. The function fails when there is no such element.
AimmsValueResetHandle and subsequently
it is possible to retrieve all nondefault values. By calling the
AimmsValueSearch you can directly skip to a particular
element tuple if you have found that the intermediate tuples are not
interesting anymore, and continue from there.
No scalar handles
AimmsValueSearch do not accept handles to scalar
(i.e. 0-dimensional) identifier slices. To retrieve and assign scalar
values you should use the functions
AimmsValueAssign explained below.
Unordered versus ordered retrieval
The particular element returned by the functions
AimmsValueNext may differ depending on the setting of the
ordered flag for the handle. If the handle has been created
unordered (default), the values returned successively are ordered by
increasing element number in a right-to- left tuple order. If the handle
has been created ordered, AIMMS will return values in accordance with
the ordering principles imposed on all local tuple domains.
Raw data retrieval
By default, AIMMS will only pass values for element tuples that lie
within the current contents of the intersection of the call domain and
declaration domain of an identifier. Thus, the values that get passed
may depend on a dynamically changing domain restriction that is part of
the index domain in the declaration of an identifier. When the
modification flag is set for a handle, AIMMS will pass all available
data values in the call domain, regardless of the domain restrictions.
Return tuple and value
All data retrieval functions return a
tuple and the associated
value. The interpretation of the
value argument for
all possible storage types was discussed on
Passing integer, double or string values. The
tuple argument must be an
integer array of length equal to the slice dimension of the handle.
Upon success, the tuple contains the element numbers in the global
domain sets for every non-sliced dimension.
Element or ordinal numbers
By setting the flag
elementsasordinals during the creation of a
handle, you can modify the default tuple representation. If this flag is
set, the tuples returned by AIMMS will contain ordinal numbers
corresponding to the respective call domains associated with the handle.
Similarly, AIMMS expects tuples that are passed to it, to contain
ordinal numbers as well, when this flag is set.
While at first sight the choice for representing tuples by their element
numbers in the global domain of a handle may seem less convenient than
ordinal numbers in its call domain, you must be aware that the latter
representation is not invariant under changes in the contents of the
call domain. Alternatively to setting the flag
you can also convert the returned element numbers into these formats
using the AIMMS API functions discussed in Accessing Sets and Set Elements.
The expected storage type of the data values returned by the data
retrieve functions can be obtained using the function
AimmsAttributeStorage. The possible storage types for the various
identifier types are listed below:
numeric parameters and variables return double or integer values,
all set types return binary values,
element parameters return integer element numbers, and
string and unit parameters return string values.
Element parameter values
The element numbers returned for element parameters are relative to the
set handle returned by the function
can use the AIMMS API functions of Accessing Sets and Set Elements to obtain the
associated ordinal numbers or string representations.
For sets (either simple, relation or indexed), the data retrieval functions return the binary value 1 for just those elements (or element tuples) that are contained in the set. For indexed sets, AIMMS returns tuples for which the last component is the element number of an element contained in the set slice associated with all but the last tuple components.
Converting special numbers
When a handle to a numeric parameter or variable has been created with
special flag set, the data retrieval functions will pass any
special number value associated with the handle as is (see also
Declaration of External Procedures and Functions and Obtaining Identifier Attributes). AIMMS
represents special numbers as double precision floating point numbers
outside AIMMS’ ordinary range of computation. The function
AimmsValueDoubleToMapval returns the
MapVal value associated
with any double value (see also this table), while
AimmsValueMapvalToDouble returns the double
representation associated with any type of special number.
Retrieving specific values
AimmsValueRetrieve returns the value for a specific
element tuple in the slice domain. This value can be either the default
value or a nondefault value. The tuple must consist of element numbers
in the corresponding domain sets. When the
raw flag is not set, the
function fails (but still returns the default value of the associated
identifier) for any tuple outside of the index domain of the handle.
raw flag is set, the function fails only when there is no
data for the tuple.
AimmsValueAssign lets you assign a new value to a
particular element tuple in the slice domain. If you want to assign the
default value you can either pass a null pointer for
value, or a
pointer to the appropriate default value. The function fails if you try
to assign a value to an element tuple outside the contents of the call
domain of the handle. When the
raw flag is not set, the function
will also fail if the assigned tuple lies outside of the current
(active) contents of the declaration domain.
Exchanging multiple values
When a particular identifier handle requires the exchange of a large
amount of values, you are strongly encouraged to use the functions
AimmsValueAssignMulti instead of the
AimmsValueAssign. In general, AIMMS
can perform the simultaneous exchange of multiple values much more
efficient than the equivalent sequence of single exchanges. For both
tuples array must be an integer array of length
times the slice dimension of the handle, while the
must be the corresponding
AimmsValue array of length
In the function
AimmsValueNextMulti, AIMMS will fill the
tuplesarray with the respective tuples for which nondefault values are returned in the
valuesarray. Upon return, the
nargument will contain the actual number of values passed.
In the function
tuplesarray must be filled sequentially with the respective tuples to which the assignments take place via the
When your data transfer involves the addition of a large amount of set
elements to an AIMMS set as well, you may also want to consider using
AimmsSetAddElementMulti (see Accessing Sets and Set Elements).
Communicating scalar values
When a handle corresponds to a 0-dimensional (i.e. scalar) identifier
slice, you can still use the
AimmsValueAssign to retrieve its value or assign a value to it. In
this case, the
tuple argument is ignored.
Assigning set values
When you want to delete or add an existing element or element tuple to a
set, you must assign the value 0 or 1 to the associated tuple
respectively. If you want to add a tuple of nonexisting simple elements,
you must first add these elements to the corresponding global simple
domain sets using the function
AimmsSetAddElement discussed below.