Using Mapping Services › Query MDO Components

Query MDO Components

Once an MDO is connected to a map, it is possible to query its structure (as present in the MDO), or its definition (as defined in the map). The syntax used is part of an &ASSIGN, where the results of the query must be placed into NCL variables.

&ASSIGN OPT={ NAMES |
              TAGS |
              TYPE |
              LENGTH |
              #ITEMS |
              NAMEDVALUES |
              VALIDVALUES }
        VARS=vars...
      { PRESENT_IN | DEFINED_IN | MANDATORY }
        MDO=mdo_name

When the PRESENT_IN keyword is specified the information is returned only for those components that are found to be present within the MDO. When the DEFINED_IN keyword is used, the information is returned for all those components defined within the connected map, regardless of their presence or absence in the MDO itself. If the MANDATORY keyword is used then only those defined components that are mandatory are selected.

The various options and their meanings are as follows:

OPT=NAMES (or OPT=NAME)

Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options and returns the component names associated with the target mdo_name as follows:

• If only an MDO stem name is specified (for example, MDO=abc), then the name of the connected map is returned as the defined component name, but only if the MDO exists.
• If mdo_name is a compound name (for example, MDO=a.b.c), the name of the last component in the name list is returned (that is, c), depending upon the PRESENT_IN, DEFINED_IN, or MANDATORY option.
• If the mdo_name is a compound generic name (for example, MDO=a.b.c.*), multiple names can be returned, where each name returned is a subcomponent of the nominated component. For example, for MDO=a.b.c.*, all components defined within “c” are returned. This format is useful in determining the names of all components that are either present in, or defined within, a given structure. It is also useful in determining which component is within a structure that is a CHOICE type. However, for SEQUENCE OF and SET OF items, it is possible to have null named components because the SEQUENCE or SET OF items are processed by index value only.

  A compound variable indexed name (for example, MDO=a.b{*}.c, or MDO=a.b.{*}) is not supported on this query.

OPT=TAGS

Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options and returns the component tags used by Mapping Services associated with the target mdo_name. Component selection is as for OPT=NAMES.

OPT=TYPE

Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options and returns the component type defined within the map and associated with the target mdo_name. Component selection is as for OPT=NAMES.

OPT=LENGTH

Applies only when PRESENT_IN is specified and returns the local form data length within the MDO of the target components. Component selection is as for OPT=NAMES.

OPT=#ITEMS

Applies only when PRESENT_IN is specified, and returns the number of items within a nominated component as follows:

• If mdo_name is a stem name (for example, MDO=stem) or a compound name (for example, MDO=a.b.c), then a count of 0 is returned if the component does not exist. Otherwise, it is 1.
• If mdo_name is a compound generic name (for example, MDO=a.b.c.*), a count of 0 is returned if the nominated component a.b.c is one of the following:
  • Does not exist
  • Exists but is empty
  • Exists but is not constructed

  Otherwise, it provides the number of components present within the structure a.b.c.

• If mdo_name is a compound variable indexed name (for example, MDO=a.b{*} or MDO=a.b.{*}), the number of components present in the SET OF or SEQUENCE OF structure is returned. If the structure does not exist or is empty, 0 is returned. The variable index must be in the last name segment.

OPT=NAMEDVALUES

Applies to components that have named values associated with their type. These types are limited to BIT STRING, INTEGER, and ENUMERATED. Other types return null results. No generic indexes or generic names are allowed on this option.

If DEFINED_IN is specified a list of the named values defined in the map for the specified component is returned.

PRESENT_IN is invalid for OPT=NAMEDVALUES.

OPT=VALIDVALUES

Applies to string types that can have their character set constrained to particular characters or strings. This option only works with the defined keyword. If a string type (for example, GraphicString) has been constrained to a particular set of characters or strings, then this option returns the valid characters or strings in the target variable. If there are no constraints then no values are returned on assignment. The &ZVARCNT system variable is set to indicate the number of target variables set by the assignment.

Example 1: Query MDO Components

The following component is defined:

datax GraphicString ("ABCD" | "xyz" | "QQQ")

You use the following statement to query the component:

&ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax

The following variables are returned:

&X1=ABCD
&X2=xyz
&X3=QQQ

Example 2: Query MDO Components

The following component is defined:

datax GraphicString (FROM ( "A"c | "C" | "Y"C | "X" ))

You use the following statement to query the component:

&ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax

The following variables are returned:

&X1=A
&X2=C
&X3=Y
&X4=X