Dimension Create

Creates a new dimension. It uses the same parameters and has the same restrictions as Dimension Write. The dimension must not exist. If the dimension exists, the request fails with (ErrorID = 2).

These characters are not allowed for dimension names: [ ] \ / : * ? " < > | <TAB> <LF> <CR>.

The maximum length of a dimension name is 50 characters or 150 bytes. If a dimension name is greater than 50 characters, ErrorID = 75 is returned. If a dimension name is greater than 150 bytes, ErrorID = 197 is returned.

Spaces are trimmed automatically at the beginning and the end of the dimension name. The dimension is created using the trimmed dimension name. Other white spaces are not allowed and result in ErrorID = 75.

Request

In this example, replace \t with a tab before executing the request.

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="001" Class="Dimension" Method="Create">
    <Alea:Dimension Name="MyDimension" FirstBatch="true" LastBatch="true">
      <Alea:Description>My New Dimension</Alea:Description>
      <Alea:Elements>N\tMyElement1
N\tMyElement2</Alea:Elements>
    </Alea:Dimension>
  </Alea:Request>
</Alea:Document>

Answer

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="001">
    <Alea:Return>
      <Alea:Dimension Name="MyDimension">
        <Alea:Hierarchy Name="MyDimension" />
      </Alea:Dimension>
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

Example with implicit hierarchy and BreakOnError request

In this request, replace \t with an actual horizontal tabulator before executing the request.

<Alea:Document xmlns:Alea="http://www.misag.com">
  <Alea:Request RequestID="1" Class="Dimension" Method="Create">
    <Alea:Dimension Name="DimTest" FirstBatch="true" LastBatch="true" BreakOnError="false" Delimiter="\t">
      <Alea:Elements>N\tActual
N\tBudget
C\tVariance
R\tActual2\t[Actual] * 2
S\tStringElem
N\tFault[Elem
C\tVariance
\tActual
\tBudget\t-1</Alea:Elements>
    </Alea:Dimension>
  </Alea:Request>
</Alea:Document>

The Alea:Elements tag contains:

  • The list of the elements, with their type and name.
    • The possible types are N (base), C (consolidated), S (string), or R (rule).
    • Rule formulas.
  • The relations between elements.
    • Optionally, the element weight. The default is 1.
    • The alternate format is:

      !\tParent\tChild\t<weight>

Further characteristics of the Alea:Elements tag:

  • By default, the fields of a line are separated by a horizontal tabulator.
  • The separator can be changed using the Delimiter attribute of the Alea:Dimension tag.
  • Each line, except the last one, ends with a line break.
  • There must be no line breaks or spaces between the opening Alea:Elements tag and the first line.
  • There must be no line breaks or spaces between the last line and the closing Alea:Elements tag.

This request contains an element with the illegal character "[". Because BreakOnError is set to "false", the request does not fail, but writes the dimension omitting the corresponding element. The offending element is returned including the error code and line number.

Answer if BreakOnError="false"

Horizontal tabulators are returned as such, not as "\t".

<Alea:Document>
  <Alea:Request RequestID="1">
    <Alea:Return>
      <Alea:Dimension Name="DimTest">
        <Alea:Hierarchy Name="DimTest">
          <Alea:Elements LinesCount="1">196\t6\tN\tFault[Elem</Alea:Elements>
        </Alea:Hierarchy>
      </Alea:Dimension>
    </Alea:Return>
  </Alea:Request>
</Alea:Document>

If BreakOnError is set to "true", the entire request fails, and the dimension is not written. The default of BreakOnError is "false".

Answer if BreakOnError="true"

<Alea:Document>
  <Alea:Request RequestID="1">
    <Alea:Return>
      <Alea:Dimension Name="DimTest">
        <Alea:Hierarchy Name="DimTest" />
      </Alea:Dimension>
    </Alea:Return>
    <Alea:Error ErrorID="196" ErrorPosition="6" />
  </Alea:Request>
</Alea:Document>
Related topics