dimension Command

The dimension administrative object provides the ability to associate units of measure with an attribute, and then convert displayed values among any of the units defined for that dimension.

For conceptual information on this command, see MQL: Dimensions.

This page discusses:

User Level

Business Administrator

Add Dimension

Before attributes can be defined with a dimension, the dimension must be created. You can define a dimension if you are a business administrator with Attribute access, using the add dimension command.

Syntax

add dimension NAME [ADD_ITEM {ADD_ITEM}];
  • ADD_ITEM provides additional information about the dimension you are defining.

The Add Dimension clauses are:

description VALUE
icon FILENAME
[!|not]hidden
property NAME [to ADMINTYPE NAME] [value STRING]
unit UNITNAME [UNIT_ITEM {UNIT_ITEM}]

Unit Clause

The Unit clauses are:

unitdescripton UNITDESC
label UNITLABEL
multiplier MULTIPLIER
offset OFFSET
[!|not]default
property NAME [to ADMINTYPE NAME] [value STRING]
setting NAME VALUE

Label Clause

The Label clause provides a description of the units. For example, if the unit is F, the label could be degrees Fahrenheit.

Multiplier Clause

The Multiplier clause provides the value to multiple against the normalized value when calculating the value for units other than the default units.

Default Clause

The Default clause of the Add Unit command defines the unit as the default for the dimension. Default units are the normalized units–the units used to store the attributes value in the database and with a multiplier of 1 and offset of 0.

Settings Clause

Settings are allowed on a unit.

History Clause

The history keyword adds a history record marked “custom” to the dimension that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

Example

This Add Dimension command creates the dimension Length with units “in”, as the default, then adds units for cm, ft, and meter with the appropriate multipliers. For this dimension, no offset is required,

add dimension Length unit in default \
 unit cm multiplier 0.393700787 \
 unit ft multiplier 12 \
 unit meter multiplier 39.3700787;

Copy Dimension

You can clone the definition with the Copy Dimension command. This command lets you duplicate defining clauses with the option to change the value of clause arguments.

Syntax

copy dimension SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];
  • SRC_NAME is the name of the dimension definition (source) to copied.
  • DST_NAME is the name of the new definition (destination).
  • MOD_ITEMs are modifications that you can make to the new definition. For more information, see Modify Dimension.

History Clause

The history keyword adds a history record marked “custom” to the dimension that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects.

Modify Dimension

After a dimension is defined, you can change the definition with the Modify Dimension command. This command lets you add or remove defining clauses and change the value of clause arguments. 

modify dimension NAME [MOD_ITEM {MOD_ITEM}];
  • NAME is the name of the dimension you want to modify.
  • MOD_ITEM is the type of modification you want to make.

You can make the following modifications to an existing dimension definition. Each is specified in a Modify Dimension clause, as listed in the following table. You only need to specify fields to be modified.

Modify Dimension Clauses Specifies
name NEW_NAME The current dimension name changes to the new name entered.
icon FILENAME The image is changed to the new image in the file specified.
description VALUE The current description value, if any, is set to the value entered.
hidden The hidden option is changed to specify that the object is hidden.
nothidden The hidden option is changed to specify that the object is not hidden.
add unit UNITNAME [UNIT_ITEM {UNIT_ITEM}] The new unit UNITNAME is added to the dimension.
remove unit UNITNAME The unit is removed from the dimension.

You cannot remove a unit from a dimension if it is the default unit and has been applied to an attribute, or if it has any business object instantiations that use it as the input unit.

modify unit UNITNAME [UNIT_NAME] {UNIT_ITEM}] The unit is modified in accordance with the accompanying Unit clause.
modify unit UNITNAME system SYSTEMNAME to unit UNITNAME For the named system association, replace the first named unit with the second named unit
modify unit UNITNAME remove property NAME to ADMIN The named property is removed from the unit
modify unit UNITNAME remove property NAME The named property is removed from the unit.
modify unit UNITNAME remove setting NAME The named setting is removed from the unit.
modify unit remove system SYSTEMNAME to unit UNITNAME The named unit is removed from the named system, but not removed from the dimensions
property NAME [to ADMINTYPE NAME] [value STRING] The named property of the dimension is modified.
add property NAME [to ADMINTYPE NAME] [value STRING] The named property is added to the dimension.
remove property NAME [to ADMINTYPE NAME] [value STRING] The named property is removed from the dimension.
history STRING Adds a history record marked "custom" to the dimension that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

Assume you have the following dimension definition:

dimension Length
  description "Absolute length of item"
  unit "Meter"
  label
  multiplier 1.0
  offset 0.0
  unit "Centimeter"
  label
  multiplier .01
  offset 0.0;

To add meters as a unit of the dimension, you can modify this dimension with the following command:

modify dimension Lengthadd unit "Meter" ;

After this command is processed, the dimension definition for the Units attribute is:

dimension Length
  description "Absolute length of item"
  unit "Meter"
  label
  multiplier 1.0
  offset 0.0
  unit "Centimeter"
  labelmultiplier .01
  offset 0.0
  unit "Foot"
  label
  multiplier 0.3048
  offset 0.0;

The system modifier allows units to be grouped and associated with other units within a dimension. For example, if you have a Length dimension, you can group meter, centimeter, and millimeter with a system modifier named Metric, and feet and inches with a system modifier English. When specifying a system for a unit, you also specify which units of that system you want the current unit to be converted into. When converting lengths from English to Metric, you might want inches to be converted into centimeters, while feet are converted into meters as shown in this example dimension definition:

dimension Length
  unit In
    label      Inches
    multiplier 1.0
    offset     0.0
    system metric to unit Cm
  unit Ft
    label      Feet
    multiplier 12.0
    offset     0.0
    system metric to unit Meter

Delete Dimension

If a dimension is no longer required, you can delete it by using the Delete Dimension command.

delete dimension NAME;
  • NAME is the name of the dimension to be deleted.

You can only delete a dimension if it has not been applied to any attributes.

Searches the list of defined dimensions. If the name is found, that dimension is deleted if it has not been applied to any attribute. If the name is not found, an error message is displayed.

For example, to delete the Length dimension, enter the following command:

delete dimension Length;

After this command is processed, the dimension is deleted and you receive an MQL prompt for another command.