The syntax for fields of a sequential record, record field declarations, are declared as follows:

<field_type> <field_name> : <field options> ;

Primitive Field Types

The following primitive types are supported:

external MSP_BILLING_EVENT 
 { 
 msp_length l : external_only; 
 ascii v : dynamic_size(l); 
 };

external MySubUDR { 
  int  dataLength : static_size(1); 
  ascii secretData : dynamic_size(dataLength); 
 }; 
 external MyUDR { 
  int elementCount  : terminated_by(":"); 
  list<MySubUDR> myList : element_count(elementCount); 
  int userType  : terminated_by(0xA); 
 };

element_count(<expr>) 

The occupying size is calculated as follows:

1. If static_size is specified, this one is used.
    
2. If dynamic_size is specified, then this one is used.
    
3. If element_count is specified, then this one is used.
    
4. If terminated_by is specified, then this one is used. The field size includes the termination character but never takes up more than the total remaining size in the UDR. (The reason that this is not considered as a decoding error is to support the trailing_optional field option).
    
5. Otherwise (if the field type supports it) the field size is deduced directly from the type. This is supported by constructed types (sub-records) and the asn_length primitive type. 

The core field data always has the full occupying size for constructed fields (record fields). For primitive fields the size is specified as follows:

Field Options for Optional Fields

The following field options are used to specify when a field is present.

external SimpleSequential {
     int recordType : static_size(1);
     ascii secretData : dynamic_size(udr_size-1);
};

The other special value that depends on the record size is remaining_size, which is the size remaining until the end of the record. The previous example could have been written using remaining_size instead of udr_size, and is shown in the following example.

external SimpleSequential {
    int recordType : static_size(1);
    ascii secretData : dynamic_size(remaining_size);
};

Bit Blocks

Bit blocks are used when the data record contains fields that are not byte aligned. When declaring fields in bit blocks there are two ways to specify which bits to use for the field content. When using a bit_block of a single byte, it is possible to specify the most and least significant bit of the field using msb and lsb, as previously described. The alternative is to use the bit_size option to specify the number of bits spanned by the field.

You can also use the byte_alignment field option if you need to specify from which byte a field begins. This field option can only be used for decoding. For further information on byte_alignment, see the section above, Primitive Field Types.

The general syntax of the  bit blocks is as follows:

bit_block : <size specification> 
  [, present if(<cond>) ] { 
    <bit_block contents> 
};

bit_block : static_size(1) { 
       int LACLength  : msb(7), lsb(4); 
       int OwnerIDLength : msb(3), lsb(0); 
 };

bit_block 
       int hour : bit_size(5); 
       int minute: bit_size(6); 
       int second: bit_size(6); 
       int eventId: bit_size(3); 
 };

external BitBlock_ByteAlignment { 
     bit_block : static_size(5) { 
         byte    firstBit:    bit_size(1); 
         byte    secondBit:  bit_size(1), byte_alignment(4); 
     }; 
 }; 

Except for simple fields, a bit_block can contain repeat_block constructs in the contents part. For a description of repeat_block see the section below, Repeat Blocks.

Repeat Blocks

A repeat_block can be used to specify that a group of fields is to be repeated a specified number of times. Currently this construct can only be used inside bit_block structures or another repeat_block structure. However this is restricted to a maximum of two levels of repeat_block. See the example below.

You can also use the byte_alignment field option if you need to specify from which byte a field begins. This field option can only be used for decoding. For further information on byte_alignment, see the Primitive Field Types section above.

The general syntax of the repeat blocks is as follows:

repeat_block ( <repeat count> ) { 
    <repeat_block fields> 
};

external BitBlockTest {
   bit_block : dynamic_size(remaining_size){
    int string_count: bit_size(8); 
    repeat_block(string_count) {
       int string_length: bit_size(8);
       repeat_block(string_length) {
         int character: bit_size(8);
       };
     };
   };
};

external MyParentFormat {
  int field1 : static_size(4);
  MyEnclosedFormat field1;
};

set Construct

The set construct is used for decoding formats containing optional blocks of additional data. The syntax of the set Construct is declared as follows:

external MyFormat: 
     dynamic_size(recordSize) { 
   int recordSize: static_size(4); 
   set : dynamic_size( remaining_size ) { 
     MyPackage1 package1: optional; 
     MyPackage2 package2: optional; 
     list<MyPackage3> package3; 
   }; 
 };

All the formats, MyPackage1-3, must be declared with the identified_by option. The optional packages may appear in any order in the input file, however it is confirmed they do not appear more than once. Currently all fields in a set construct must be declared optional.

If the field type in the set is a list type, the set may contain multiple records of the list element type. The list type fields are not optional. Instead, when no matching records are found, the list is empty.

If a size is not specified on the set level, Ultra cannot validate that all the data in the UDR has been decoded. The user is therefore recommended to specify the size, unless the set size in advance is unknown (for instance if the record is terminated by a terminator package or the set size calculation is needed for the record size calculation). The dynamic_size(remaining_size) specification used in the previous example is often correct.

switched_set Construct

The switched_set construct can often be used instead of the set construct. It has advantages (in performance and in ease of usage) especially when the separate sub-packages are simple. The syntax is however more complex compared to the basic set construct. The syntax of the switched_set construct is declared as follows:

switched_set( <switch field> )
  [: <size specification> ] {
    <prefix fields>
    <switch cases>
    [<default case>]
}; 

The size specification is allowed to contain normal size options. The other parts of the declaration are the prefix fields, decoded for each package in the set and the prefix fields. All the prefixes must have static sizes. The switch field must be one of the prefix fields.The syntax of the switch case is declared as follows:

case( <case value> ) [: include_prefix] {
        <case fields>
};

The case fields are normal field specifications with the additional possibility of declaring list fields for the case where a package can be present repeatedly. If include_prefix is specified, then the case body is decoded including the prefix fields. The syntax of the  default case is declared as follows:

default [: include_prefix] {
        <case fields>
};

The decoding of a switched_set is performed according to the following steps:

external SwitchedSetExample: terminated_by(0xA) { 
   // Size is remaining_size -1 (minus the terminator linefeed) 
    switched_set( packageId ): 
        dynamic_size( remaining_size - 1 ) { 
      ascii packageId: int(base10), static_size(1); 
      ascii packageLength: static_size(1), int(base10), 
         encode_value( case_size - 2 ); 
      case(1) { 
         list<ascii> list1: 
            dynamic_size( packageLength ); 
      }; 
      case(2): include_prefix { 
         ascii packageId_3: int(base10), static_size(1), 
               encode_value(3), external_only; 
         ascii packageLength_3: int(base10), static_size(1), 
               encode_value(case_size - 2), external_only; 
         ascii body_3: dynamic_size( packageLength_3 ); 
      }; 
      default: include_prefix { 
       list<ascii> defaultContent: 
             dynamic_size( packageLength + 2 ); 
      }; 
   }; 
 };

Encoding Specifications and Expressions

To support encoding to binary formats, it is often necessary to explicitly specify which value to be encoded in the external fields. Normally the value is taken from the corresponding internal field, however there are cases when this is not desirable. For instance, if there is no mapped internal field (because the external_only option has been used), or the value must be calculated from information about the encoding (for instance, udr_size). This is done through the encode_value option and there are several special constructs that may be used in the value expression (see the section above, Primitive Field Types).

If the size expressions are used, the field encoding has to be postponed until the size is known. To be able to do this, Ultra requires that any such fields are static_size. An example of these concepts is presented next.

external Ext: dynamic_size( udrSize ) { 
   ascii udrSize: int(base10), static_size(3), 
         align(right), padded_with("0"), 
                 encode_value( udr_size ); 
   ascii fieldSize: int(base10), static_size(3), 
         align(right), padded_with("0"), 
                 encode_value( field_present( strField ) ? 
                               field_size( strField ):0 ); 
   ascii strField: dynamic_size( fieldSize ), 
      present if( fieldSize > 0 ); 
 };

When processing an encode_value instruction, Ultra automatically decides how to convert the value depending on the result type of the expression. When deciding this, Ultra starts with the default internal type of the external field. In this case, the type is called defaultType and the expression type is encodeType, the encoding rules are:

If none of these rules apply, the format will not compile. To understand what this means, consider the following field definitions.

ascii strField1: static_size(1), encode_value("10");
  ascii strField2: static_size(1), encode_value(10);
  ascii intField1: static_size(1), int(base10), 
                   encode_value("10");  
  ascii intField2: static_size(1), int(base10), 
                   encode_value(10);