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=mdoName

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 mdoName as follows:

  • If only an MDO stem name is specified (for example, MDO=abc) then the name of the currently connected map is returned as the defined component name on this query, but only if the MDO exists.
  • If the mdoName 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 mdoName is a compound generic name (for example, MDO=a.b.c.*), multiple names can be returned, where each name returned is a sub-component of the nominated component. For example, for MDO=a.b.c.*, all components defined within "c" are returned. This 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 mdoName. 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 mdoName. 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 component(s). 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 mdoName 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 mdoName 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:
    • a. Does not exist
    • b. Exists but is empty
    • c. Exists but is not constructed

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

  • If mdoName 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, or 0 if the structure does not exist or is empty. 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 will 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. It only works in conjunction 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

If there is a component defined as follows:

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

then &ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax will return 3 variables set as follows:

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

Example 2: Query MDO Components

If there is a component defined as follows:

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

then &ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax will return 4 variables set as follows:

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