4.5 Inquiring and Changing Attributes

To set and inquire attributes in the Dialog Manager two different data structures are used. In the DM-Value structure exactly one value can be inquired or set. In the DM-ValueArray structure, however, up to 16 values can be inquired or set by one call. The DM-ValueIndex structure is used to pass an additional index value.

These structures are defined in IDMcobls.cob and IDMcobws.cob.

4.5.1 DM-Value

By means of this structure exactly one value can be set or inquired in the Dialog Manager. This structure has the following definition:

02 DM-Value.
   03 DM-object                  pic 9(9) binary value 0.
   03 DM-attribute               pic 9(9) binary value 0.
   03 DM-indexcount              pic 9(4) binary value 0.
   03 DM-index                   pic 9(4) binary value 0.
   03 DM-second                  pic 9(4) binary value 0.
   03 DM-datatype                pic 9(4) binary value 0.
   03 DM-long-first              pic 9(9) binary value 0.
   03 DM-long-second             pic 9(9) binary value 0.
   03 DM-value-object            pic 9(9) binary value 0.
   03 DM-value-boolean           pic 9(4) binary value 0.
   03 DM-value-cardinal          pic 9(4) binary value 0.
   03 DM-value-classid           pic XX value "??".
   03 filler                     pic XX value low-values.
   03 DM-value-integer           pic S9(9) binary value 0.
   03 DM-value-index.
      04 DM-value-long-first     pic 9(9) binary value 0.
      04 filler redefines DM-value-long-first.
         05 filler               pic XX.
         05 DM-value-first       pic 9(4) binary.
      04 DM-value-long-second    pic 9(9) binary value 0.
      04 filler redefines DM-value-long-second.
         05 filler               pic XX.
         05 DM-value-second      pic 9(4) binary.
   03 DM-value-attribute         pic 9(9) binary value 0.
   03 DM-value-method            pic 9(9) binary value 0.
   03 DM-value-pointer           pic X(8) value low-values.
   03 DM-value-string-putlen     pic 9(4) binary value 0.
   03 DM-value-string-getlen     pic 9(4) binary value 0.
   03 DM-value-string-size       pic 9(4) binary value 80.
   03 DM-value-string-S.
      04 DM-value-string         pic X(80) value low-values.
      04 filler                  pic X(80) value low-values.
   03 filler                     pic XX value low-values.

Definition in the COBOL Interface for Micro Focus Visual COBOL

02 DM-Value.
   03 DM-object                  pic 9(9) binary value 0.
   03 DM-attribute               pic 9(9) binary value 0.
   03 DM-indexcount              pic 9(4) binary value 0.
   03 DM-index                   pic 9(4) binary value 0.
   03 DM-second                  pic 9(4) binary value 0.
   03 DM-datatype                pic 9(4) binary value 0.
   03 DM-long-first              pic 9(9) binary value 0.
   03 DM-long-second             pic 9(9) binary value 0.
   03 DM-value-object            pic 9(9) binary value 0.
   03 DM-value-boolean           pic 9(4) binary value 0.
   03 DM-value-cardinal          pic 9(4) binary value 0.
   03 DM-value-classid           pic XX value "??".
   03 filler                     pic XX value low-values.
   03 DM-value-integer           pic S9(9) binary value 0.
   03 DM-value-index.
      04 DM-value-long-first     pic 9(9) binary value 0.
      04 filler redefines DM-value-long-first.
         05 filler               pic XX.
         05 DM-value-first       pic 9(4) binary.
      04 DM-value-long-second    pic 9(9) binary value 0.
      04 filler redefines DM-value-long-second.
         05 filler               pic XX.
         05 DM-value-second      pic 9(4) binary.
   03 DM-value-attribute         pic 9(9) binary value 0.
   03 DM-value-method            pic 9(9) binary value 0.
$IF P64 SET
   03 DM-value-pointer           pointer value null.
$ELSE
   03 DM-value-pointer           pointer value null.
   03 filler                     pic X(4) value low-values.
$END
   03 DM-value-string-putlen     pic 9(4) binary value 0.
   03 DM-value-string-getlen     pic 9(4) binary value 0.
   03 DM-value-string-size       pic 9(4) binary value 80.
   03 DM-value-string-S.
      04 DM-value-string         pic X(80) value low-values.
      04 filler                  pic X(80) value low-values.
   03 filler redefines DM-value-string-S.
      04 DM-value-string-u       pic N(80) national.
   03 filler                     pic XX value low-values.

Description of the Structure Elements

DM-object

This is the object whose attribute is to be changed or returned.

DM-attribute

This is the attribute which is to be set or returned.

DM-indexcount

This is the number of indexes which should be used by Dialog Manager when accessing or setting an attribute.

DM-index

This is the first index of the attribute which should be set or returned.

This number is only valid or used if the attribute is an indexed attribute or if DM-indexcount is set at a value greater than 0.

DM-second

This is the second index of the attribute which should be set or returned. This number is only valid or used if DM-indexcount is set at a value greater than 1.

DM-long-first

This element represents the first index. It is only used if DM-indexcount is greater than 1 and a function is called that processes the long index. These functions can be recognized by the name DMcob_L*. This allows index values in the range from 0 to 65535 to be passed to the Dialog Manager.

DM-long-second

This element represents the second index. It is only used if DM-indexcount is greater than 1 and a function is called that processes the long index. These functions can be recognized by the name DMcob_L*.

DM-datatype

This describes which part of the structure is filled and should be used to get the value.

DM-value-integer

This is used to set or get an integer attribute.

DM-value-object

This is used to set or get an attribute which is a Dialog Manager object like color, font, or object.

DM-value-boolean

This is used to set or get boolean attributes.

DM-value-cardinal

This is used to pass the enumeration and cardinal values.

DM-value-classid

This is used to get the class to which the object belongs.

DM-value-first, DM-value-second

These two elements are always used together. They pass an index value on to the DM and return respectively an index value from the DM to the COBOL function.

DM-value-long-first, DM-value-long-second

These two elements are always used together. They contain a long index value with the value range 0 … 65535 that is passed to the Dialog Manager or returned by the Dialog Manager to the COBOL function.

DM-value-attribute

This element is allocated if the identifier of a user-defined attribute is to be queried.

DM-value-method

This element is used for the handling of methods implemented in DM.

DM-value-pointer

This element is used to pass collections (value references) and data of the data type DT-anyvalue.

It is only used by the COBOL Interface for Micro Focus Visual COBOL.

DM-value-string-putlen

This can be set to show the Dialog Manager the end of a string if the string is to be terminated by a value which differs from the definitions. The number of characters is to be specified.

DM-value-string-getlen

This contains the length of the returned string from the Dialog Manager. The number of characters is specified.

DM-value-string-size

Internal field, not to be changed directly! The number of characters is specified.

DM-value-string

This is used to set or get string attributes. These strings must not be longer than 80 characters.

DM-value-string-u

In this element, strings can be passed as National Character (PIC N) when working with Unicode strings (UTF-16) (Micro Focus Visual COBOL only).

Note

Before IDM version A.06.01.d the structure DM-Value had this definition:

02 DM-Value.
   03 DM-object              pic 9(9) binary value 0.
   03 DM-attribute           pic 9(9) binary value 0.
   03 DM-indexcount          pic 9(4) binary value 0.
   03 DM-index               pic 9(4) binary value 0.
   03 DM-second              pic 9(4) binary value 0.
   03 DM-datatype            pic 9(4) binary value 0.
   03 DM-long-first          pic 9(9) binary value 0.
   03 DM-long-second         pic 9(9) binary value 0.
   03 DM-value-object        pic 9(9) binary value 0.
   03 DM-value-boolean       pic 9(4) binary value 0.
   03 DM-value-cardinal      pic 9(4) binary value 0.
   03 DM-value-classid       pic XX value "??".
   03 filler                 pic XX value low-values.
   03 DM-value-integer       pic S9(9) binary value 0.
   03 DM-value-first         pic 9(4) binary value 0.
   03 DM-value-second        pic 9(4) binary value 0.
   03 DM-value-attribute     pic 9(9) binary value 0.
   03 DM-value-method        pic 9(9) binary value 0.

   03 DM-value-string-putlen pic 9(4) binary value 0.
   03 DM-value-string-getlen pic 9(4) binary value 0.
   03 DM-value-string-size   pic 9(4) binary value 80.
   03 DM-value-string        pic X(80) value low-values.
   03 filler                 pic XX value low-values.

4.5.2 DM-ValueIndex

This structure allows for a full-fledged index argument. It is used by the DMcob_Value* functions of the COBOL Interface for Micro Focus Visual COBOL to process the collection data types. However, the structure is available for all supported COBOL variants and is not restricted to these application areas. It is identical to the DM-Value structure.

4.5.3 DM-ValueArray

For the call of some Dialog Manager functions an array of up to 16 structure elements is needed. To do so, the following structure is available:

02 DM-ValueArray.
   03 DM-value-size              pic 9(4) binary value 16.
   03 DM-value-count             pic 9(4) binary value 0.
   03 DM-ValueRecord occurs 16 indexed by DM-valuecount.
      04 DM-va-object            pic 9(9) binary value 0.
      04 DM-va-attribute         pic 9(9) binary value 0.
      04 DM-va-indexcount        pic 9(4) binary value 0.
      04 DM-va-index             pic 9(4) binary value 0.
      04 DM-va-second            pic 9(4) binary value 0.
      04 DM-va-datatype          pic 9(4) binary value 0.
      04 DM-va-long-first        pic 9(9) binary value 0.
      04 DM-va-long-second       pic 9(9) binary value 0.
      04 DM-va-value-object      pic 9(9) binary value 0.
      04 DM-va-value-boolean     pic 9(4) binary value 0.
      04 DM-va-value-cardinal    pic 9(4) binary value 0.
      04 DM-va-value-classid     pic XX value "??".
      04 filler                  pic XX value low-values.
      04 DM-va-value-integer     pic S9(9) binary value 0.
      04 DM-va-value-index.
         05 DM-va-value-long-first pic 9(9) binary value 0.
         05 filler redefines DM-va-value-long-first.
            06 filler            pic XX.
            06 DM-va-value-first pic 9(4) binary.
         05 DM-va-value-long-second pic 9(9) binary value 0.
         05 filler redefines DM-va-value-long-second.
            06 filler            pic XX.
            06 DM-va-value-second pic 9(4) binary.
      04 DM-va-value-attribute   pic 9(9) binary value 0.
      04 DM-va-value-method      pic 9(9) binary value 0.
      04 DM-va-value-pointer     pic X(8) value low-values.
      04 DM-va-value-string-putlen pic 9(4) binary value 0.
      04 DM-va-value-string-getlen pic 9(4) binary value 0.
      04 DM-va-value-string-size   pic 9(4) binary value 80.
      04 DM-va-value-string-S.
         05 DM-va-value-string   pic X(80) value low-values.
         05 filler               pic X(80) value low-values.
      04 filler                  pic XX value low-values.

Definition in the COBOL Interface for Micro Focus Visual COBOL

02 DM-ValueArray.
   03 DM-value-size              pic 9(4) binary value 16.
   03 DM-value-count             pic 9(4) binary value 0.
   03 DM-ValueRecord occurs 16 indexed by DM-valuecount.
      04 DM-va-object            pic 9(9) binary value 0.
      04 DM-va-attribute         pic 9(9) binary value 0.
      04 DM-va-indexcount        pic 9(4) binary value 0.
      04 DM-va-index             pic 9(4) binary value 0.
      04 DM-va-second            pic 9(4) binary value 0.
      04 DM-va-datatype          pic 9(4) binary value 0.
      04 DM-va-long-first        pic 9(9) binary value 0.
      04 DM-va-long-second       pic 9(9) binary value 0.
      04 DM-va-value-object      pic 9(9) binary value 0.
      04 DM-va-value-boolean     pic 9(4) binary value 0.
      04 DM-va-value-cardinal    pic 9(4) binary value 0.
      04 DM-va-value-classid     pic XX value "??".
      04 filler                  pic XX value low-values.
      04 DM-va-value-integer     pic S9(9) binary value 0.
      04 DM-va-value-index.
         05 DM-va-value-long-first pic 9(9) binary value 0.
         05 filler redefines DM-va-value-long-first.
            06 filler            pic XX.
            06 DM-va-value-first pic 9(4) binary.
         05 DM-va-value-long-second pic 9(9) binary value 0.
         05 filler redefines DM-va-value-long-second.
            06 filler            pic XX.
            06 DM-va-value-second pic 9(4) binary.
      04 DM-va-value-attribute   pic 9(9) binary value 0.
      04 DM-va-value-method      pic 9(9) binary value 0.
$IF P64 SET
      04 DM-va-value-pointer     pointer value null.
$ELSE
      04 DM-va-value-pointer     pointer value null.
      04 filler                  pic X(4) value low-values.
$END
      04 DM-va-value-string-putlen pic 9(4) binary value 0.
      04 DM-va-value-string-getlen pic 9(4) binary value 0.
      04 DM-va-value-string-size   pic 9(4) binary value 80.
      04 DM-va-value-string-S.
         05 DM-va-value-string   pic X(80) value low-values.
         05 filler               pic X(80) value low-values.
      04 filler redefines DM-va-value-string-S.
         05 DM-va-value-string-u pic N(80) national.
      04 filler                  pic XX value low-values.

Description of the Structure Elements

DM-value-size

This is the total size of the array. It is set at 16 by the Dialog Manager as a standard. This value may be changed by the user to allow to set more then sixteen values by one function call.

DM-value-count

This is the number of currently used values in the array. The value has to be set and has to be less than or equal to the DM-value-size.

DM-va-object

This is the object whose attributes are to be changed or returned.

DM-va-attribute

This is the attribute which should be set or returned.

DM-va-indexcount

This is the number of indexes which are to be used by accessing or setting the attribute.

DM-va-index

This is the first index of the attribute which should be set or returned. This number is only valid if DM-va-indexcount is specified by a value greater than 0.

DM-va-second

This is the second index of the attribute which should be set or returned. This number is only valid if DM-va-indexcount is specified by a value greater than 1.

DM-va-datatype

This describes which part of the structure is filled and should be used to get the value.

DM-va-value-integer

This is used to set or get an integer attribute.

DM-va-value-object

This is used to set or get an attribute which is a Dialog Manager object like color, font or object.

DM-va-value-boolean

This is used to set or get boolean attributes.

DM-va-value-cardinal

This is used to pass the enumeration and cardinal values.

DM-va-value-classid

This is used to get the class to which the object belongs.

DM-va-value-first, DM-va-value-second

These two elements are always used together. They pass an index value on to the DM and return respectively an index value from the DM to the COBOL function.

DM-va-value-long-first, DM-va-value-long-second

These two elements are always used together. They contain a long index value with the value range 0 … 65535 that is passed to the Dialog Manager or returned by the Dialog Manager to the COBOL function.

DM-va-value-attribute

This element is allocated if the identifier of a user-defined attribute is to be queried.

DM-va-value-method

This element is used for the handling of methods implemented in DM.

DM-va-value-pointer

This element is used to pass collections (value references) and data of the data type DT-anyvalue.

It is only used by the COBOL Interface for Micro Focus Visual COBOL.

DM-va-value-string-putlen

This can be set to show the Dialog Manager the end of a string, if the string to be terminated differs from the definitions.

DM-va-value-string-getlen

This contains the length of the returned string from the Dialog Manager.

DM-va-value-string-size

Internal field, not to be changed directly!

DM-va-value-string

This is used to set or get string attributes. These strings must not be longer than 80 characters.

DM-va-value-string-u

In this element, strings can be passed as National Character (PIC N) when working with Unicode strings (UTF-16) (Micro Focus Visual COBOL only).

Note

Before IDM version A.06.01.d the structure DM-ValueArray had this definition:

02 DM-ValueArray.
   03 DM-value-size          pic 9(4) binary value 16.
   03 DM-value-count         pic 9(4) binary value 0.
   03 DM-ValueRecord occurs 16 indexed by DM-valuecount.
      04 DM-va-object        pic 9(9) binary value 0.
      04 DM-va-attribute     pic 9(9) binary value 0.
      04 DM-va-indextype     pic 9(4) binary value 0.
      04 DM-va-index         pic 9(4) binary value 0.
      04 DM-va-second        pic 9(4) binary value 0.
      04 DM-va-datatype      pic 9(4) binary value 0.
      04 DM-va-long-first    pic 9(9) binary value 0.
      04 DM-va-long-scrond   pic 9(9) binary value 0.

      04 DM-va-value-object    pic 9(9) binary value 0.
      04 DM-va-value-boolean   pic 9(4) binary value 0.
      04 DM-va-value-cardinal  pic 9(4) binary value 0.
      04 DM-va-value-classid   pic XX value "??".
      04 filler                pic XX value low-values.
      04 DM-va-value-integer   pic S9(9) binary value 0.
      04 DM-va-value-first     pic 9(4) binary value 0.
      04 DM-va-value-second    pic 9(4) binary value 0.
      04 DM-va-value-attribute pic 9(9) binary value 0.
      04 DM-va-value-method    pic 9(9) binary value 0.

      04 DM-va-value-string-putlen pic 9(4) binary value 0.
      04 DM-va-value-string-getlen pic 9(4) binary value 0.
      04 DM-va-value-string-size   pic 9(4) binary value 80.
      04 DM-va-value-string  pic X(80) value low-values.
      04 filler              pic XX value low-values.

4.5.4 Data Types in the Structures DM-Value and DM-ValueArray

If values are inquired from the DM with DM-Value or DM-ValueArray, the DM sets the structure element DM-datatype or DM-va-datatype according to the inquired attribute.

The following definitions are possible.

Identifier (ID)

COBOL Data Type

Meaning/Structure Element

DT- accel

pic 9 (4) binary

Accelerator reference. DM value-object / DM-va-value-object.
DT-anyvalue pointer Data of any data type. DM-value-pointer / DM-va-value-pointer

DT-application

pic 9 (4) binary

Application reference. DM-value-object / DM-va-value-object.

DT-attribute

pic 9 (4) binary

Data type for an attribute in the Dialog Manager.

DT-boolean

pic 9 (4) binary

Boolean value. DM-value-boolean / DM-va-value-boolean.

DT-class

pic XX

Describes the classes of the various objects. DM-value-classid / DM-va-value-classid.

DT-color

pic 9 (4) binary

Color reference. DM-value-object / DM-va-value-object.

DT-cursor

pic 9 (4) binary

Cursor reference. DM-value-object / DM-va-value-object.

DT-enum

pic 9 (4) binary

Enumeration type in the Dialog Manager. DM-value-cardinal / DM-va-value-cardinal.

DT-event

pic 9 (4) binary

Defines the type of an event. DM-value-cardinal / DM-va-value-cardinal.

DT-font

pic 9 (4) binary

Font reference. DM-value-object / DM-va-value-object.
DT-hash pointer Hash reference. DM-value-pointer / DM-va-value-pointer

DT-index

pic 9 (4) binary

Describes a two-dimensional index. Thus, always two elements have to be evaluated in the value structure. DM-value-first & DM-value-second / DM-va-value-first & DM-va-value-second.

DT-instance

pic 9 (4) binary

Instance reference. DM-value-object / DM-va-value-object.

DT-integer

pic 9 (4) binary

Number value. DM-value-integer / DM-va-value-integer.
DT-list pointer List reference. DM-value-pointer / DM-va-value-pointer
DT-matrix pointer Matrix reference. DM-value-pointer / DM-va-value-pointer

DT-object

pic 9 (4) binary

Object reference. DM-value-object / DM-va-value-object.
DT-refvec pointer Refvec reference. DM-value-pointer / DM-va-value-pointer

DT-rule

pic 9 (4) binary

Rule reference. DM-value-object / DM-va-value- object.

DT-scope

pic 9 (4) binary

Defines whether we see a default, a model or a normal object. DM-value-cardinal / DM-va-value-cardinal.

DT-string

pic X (??)

Transferring a string. DM-value-string / DM-va-value-string.

DT-text

pic 9 (4) binary

Text reference. DM-value-object / DM-va-value-object.

DT-tile

pic 9 (4) binary

Tile reference. DM-value-object / DM-va-value-object.

DT-timer

pic 9 (4) binary

Timer reference. DM-value-object / DM-va-value-object.

DT-undefined

none

Data Type is undefined.

DT-var

pic 9 (4) binary

Variable reference. DM-value-object / DM-va-value-object.
DT-vector pointer Vector reference. DM-value-pointer / DM-va-value-pointer

DT-void

none

Data Type is unknown or unspecified.

When setting attributes, there are several possible data types. Therefore, the element DM-datatype has to be set according to the used data type, so that the DM can read the value out of the corresponding element.

The possible values for DT-scope are:

1

default object

2

model

3

instance