3.35 DM_GetVectorValue

Using this function, attributes occurring several times in an object (vector attributes) can be queried (see end of this function description for details). Moreover, you can query user-defined attributes by means of this function.

In contrast to DM_GetValue, this function causes the DM to process structures and allocate memory. Afterward, the memory allocated must be released by DM_FreeVector.

DM_Boolean DML_default DM_EXPORT DM_GetVectorValue
(
  DM_ID objectID,
  DM_Attribute attr,
  DM_Value *firstindex,
  DM_Value *lastindex,
  DM_VectorValue **values,
  DM_Options options
)

Parameters

-> DM_ID objectID

Describes the object whose attribute you query.

-> DM_Attribute attr

This parameter describes the object attribute you want to query.

-> DM_Value *firstindex

Using this parameter you can control which part of the contents is to be queried by this function. In this parameter the starting point of the part is defined. For a one-dimensional attribute this means that the type in the DM_Value structure is set to DT_integer and the integer values in the union are assigned the starting value. For a two-dimensional attribute this means that the type in the DM_Value structure is set to DT_index and that the index value in the union is assigned the starting value. In index.first the row has to be specified, in index.second the column has to be indicated.

Note

If this parameter is a NULL pointer, the starting point has the following default values:

Listbox.content:

integer = 1

Tablefield.content:

index.first = 1, index.second = 1

-> DM_Value *lastindex

Using this parameter you can control which part of the contents is to be queried by the function. In this parameter the starting point of the part is defined. For a one-dimensional attribute this means that the type in the DM_Value structure is set to DT_integer and the integer values in the union are assigned the starting value. For a two-dimensional attribute this means that the type in the DM_Value structure is set to DT_index and that the index value in the union is assigned the starting value. In index.first the row has to be specified, in index.second the column has to be indicated.

Note

If this parameter is a NULL pointer, the ending point has the following default values:

Listbox.content:

integer = object.itemcount

Tablefield.content:

index.first = object.rowcount, index.second = object.colcount

<- DM_VectorValue **values

This parameter is a pointer to the values which are to be queried. In the DM_VectorValue structure you can control via the field type the data type of the individual values. You can control in the DM_VectorValue structure via the field count how many values the vector contains. The fields type and count are executed by the function call.

-> DM_Options options

Using this parameter you can control the form of the texts to be returned from DM, if the corresponding attribute is of the text-type.

Option

Meaning

DMF_GetMasterString

This object means that the string of textual attributes is to be returned in the development language, independently of the language the user is working with.

DMF_GetLocalString

This option means that the string of textual attributes is returned in the selected language.

DMF_GetTextID

This option means that the string of textual attributes is returned as textID. This is especially useful if the text is to be assigned to another object.

DMF_DontFreeLastStrings

Usually, strings are transferred in a temporary buffer (which remains until the next call to DM) to the application. If strings are to remain valid for a longer time in the application, the option DMF_DontFreeLastStrings has to be set. The memory will only be released, if a DM function is called without this option and if then a string is returned by the DM to the application.

Return Value

TRUE

The object could be queried successfully.

FALSE

The attribute is not permitted for this object.

Example

Querying row-wise the contents of a tablefield with 5 columns.

/*

*write the content of a tablefield to a file

*the file format is described above

*/

DM_Boolean DML_default DM_ENTRY SaveTable_ _2(

(DM_ID, Table),

(char *, filename))

{

    DM_boolean retval = FALSE;

    DM_VectorValue *vector;

 

    if (DM_GetVectorValue (table, AT_field, (DM_Value *) 0,

        (DM_Value *) 0, &vector, 0))

    {

        FILE *f;

 

        if ((f = fopen(filename, "w")))

        {

          int vpos = 0;

          int i;

 

          retval = TRUE;

 

          while ((vpos + 5) < vector->count)

          {

              DM_boolean ok = TRUE;

              for (i=0; i<5, i++)

                  if (!vector->vector.stringPtr[vpos+i]

                && !*vector->vector.stringPtr[vposi])

                    ok = FALSE;

            if (ok)

                for (1=0, i<5; i++)

                {

                fputs(vector->vector.stringPtr[vpos+i], f);

                    putc((i<4) ? ' ' : '\n', f);

                vpos += 5;

                }

          }

          fclose(f);

 

          DM_FreeVectorValue(vector,0);

    }

    return retval;

}