> ## 2 Specialized Decodes

> When performance is of highest priority and one is interested in a limited part of the ASN.1 encoded message, before one decide what to do with the rest of it, one may want to decode only this small part. The situation may be a server that has to decide to which addressee it will send a message. The addressee may be interested in the entire message, but the server may be a bottleneck that one want to spare any unnecessary load. Instead of making two entire decodes, one in the server and one in the addressee, it is only necessary to make one specialized decode(in the server) and another decode(in the addressee). The following specialized decodes exclusive decode and selected decode support to solve this and similar problems.

> ### 2.1 Exclusive Decode

> The basic idea with exclusive decode is that you specify which parts of the message you want to exclude from beeing decoded. These parts remain encoded and are returned in the value structure as binaries. They may be decoded in turn by passing them to a certain `decode_part/2` function. The performance gain is high when the message is large and you can do an exclusive decode and later on one or several decodes of the parts or a second entire decode instead of two or more entire decodes.

> #### 2.1.1 How To Make It Work

> So far this functionality is only provided when using the optimized BER version that uses binaries, that is when compiling with the options `ber_bin` and `optimzie`.

> In order to make exclusive decode work you have to do the folowing:

> - First,decide the name of the function for the exclusive decode.
> - Second, write instructions that must consist of the name of the exclusive decode function, the name of the ASN.1 specification and a notation that tells which parts of the message structure will be excluded from decode. These instructions shall be included in a configuration file.
> - Third, compile with the additional option `"{asn1config,Configuration_File}"`. This configuration file is not the same as used for compilation of a set of files. See section Writing an Exclusive Decode Instruction.

> #### 2.1.2 User Interface

> The run-time user interface for exclusive decode consists of two different functions. First, the function for an exclusive decode, whose name the user decides in the configuration file. Second, the compiler generates a `decode_part/2` function when exclusive decode is choosen. This function decodes the parts that were left undecoded during the exclusive decode. Both functions are described below.

> If the exclusive decode function has for example got the name `decode_TypeA_exclusive` and an ASN.1 encoded message `Bin` shall be exclusive decoded, the call is:

>     {ok,Excl_Message} = 'MyModule':decode_TypeA_exclusive(Bin)

> The result `Excl_Message` has the same structure as an ordinary decode would have, except for the parts of the top-type that were not decoded. The undecoded parts will be on their place in the structure on the format `{Type_Key,Undecoded_Value}`.

> Each undecoded part that shall be decoded must be fed into the `decode_part/2` function,like:

>     {ok,Part_Message} = 'MyModule':decode_part(Type_Key,Undecoded_Value)

> #### 2.1.3 Writing an Exclusive Decode Instruction

> This instruction is written in the configuration file on the format:

>     Exclusive_Decode_Instruction = {exclusive_decode,{Module_Name,Decode_Instructions}}.

>     Module_Name = atom()

>     Decode_Instructions = [Decode_Instructrion]+

>     Decode_Instruction = {Exclusive_Decode_Function_Name,Type_List}

>     Exclusive_Decode_Function_Name = atom()

>     Type_List = [Top_Type,Element_List]

>     Element_List = [Element]+

>     Element = {Name,parts} |
>               {Name,undecoded} |
>               {Name,Element_List}

>     Top_Type = atom()

>     Name = atom()

> Observe that the instruction must be a valid Erlang term ended by a dot.

> In the `Type_List` the "path" from the top type to each undecoded sub-components is described. The top type of the path is an atom, the name of it. The action on each component/type that follows will be described by one of `{Name,parts}, {Name,undecoded}, {Name,Element_List}`

> The use and effect of the actions are:

> - `{Name,undecoded}` Tells that the element will be left undecoded during the exclusive decode. The type of Name may be any ASN.1 type. The value of element Name will be returned as a tuple,as mentioned above , in the value structure of the top type.
> - `{Name,parts}` The type of Name may be one of SEQUENCE OF or SET OF. The action implies that the different components of Name will be left undecoded. The value of Name will be returned as a tuple, as above , where the second element is a list of binaries. That is because the representation of a SEQUENCE OF/ SET OF in Erlang is a list of its internal type. Any of the elements of this list or the entire list can be decoded by the `decode_part` function.
> - `{Name,Element_List}`This action is used when one or more of the sub-types of Name will be exclusive decoded.

> Name in the actions above may be a component name of a SEQUENCE or a SET or a name of an alternative in a CHOICE.

> #### 2.1.4 Example

> In the examples below we use the definitions from the following ASN.1 spec:

>     Seq DEFINITIONS AUTOMATIC TAGS ::=

>     BEGIN

>     A ::= SEQUENCE {
>       a  INTEGER DEFAULT 15,
>       b  [0] B DEFAULT {a  12, b  TRUE}
>     }

>     C ::= [11] EXPLICIT D
>     B ::= [12] C
>     D ::= SEQUENCE {
>       a  INTEGER,
>       b  BOOLEAN
>     }

>     F ::= CHOICE {
>       fa INTEGER,
>       fb E
>     }

>     E ::= SEQUENCE {
>       a INTEGER,
>       b SEQUENCE OF D,
>       c BOOLEAN OPTIONAL,
>       d CHOICE {
>         a SEQUENCE OF A,
>         b INTEGER
>       }
>     }

>     END

> If D is a top type and we want to exclude component `a` from decode the Type_List in the instruction in the configuration file will be `['D',[{a,undecoded}]]`. If we call the decode function `decode_D_exclusive` the Decode_Instruction will be `{decode_D_exclusive,['D',[{a,undecoded}]]}`.

> We also have another top type F whose sub component d in type E and the parts of component b shall be left undecoded. For this type we name the function `decode_F_fb_exclusive`. The whole Exclusive_Decode_Instruction configuration is as folows:

>     {exclusive_decode,{'Seq',
>             [{decode_F_fb_exclusive,['F',[{fb,[{b,parts},{d,undecoded}]}]]},
>              {decode_D_exclusive,['D',[{a,undecoded}]]}]}}.

> Compiling Seq.asn including the configuration file is done like:

>     unix> erlc -bber_bin +optimize +"{asn1config,'Seq.asn1config'}" Seq.asn

>     erlang> asn1ct:compile('Seq',[ber_bin,optimize,{asn1config,'Seq.asn1config'}]).

> The module can be used like:

>     1> D_Msg = {'D',123,true}.
>     {'D',123,true}
>     2> {ok,D_Bytes} = 'Seq':encode('D',D_Msg).
>     {ok,[<<48>>,
>          [6],
>          [<<128>>,
>           [1],
>           123],
>          [<<129>>,
>           [1],
>           255]]}
>     3> {ok,Exclusive_Msg_D} = 'Seq':decode_D_exclusive(list_to_binary(D_Bytes)).
>     {ok,{'D',{'D_a',<<128,1,123>>},
>              true}}
>     4> 'Seq':decode_part('D_a',<<128,1,123>>).
>     {ok,123}
>     5> F_Msg = {'F',{fb,{'E',35,[{'D',3,true},{'D',4,false},{'D',5,true},{'D',6,true},{'D',7,false},{'D',8,true},{'D',9,true},{'D',10,false},{'D',11,true},{'D',12,true},{'D',13,false},{'D',14,true}],false,{a,[{'A',16,{'D',17,true}}]}}}}.
>     {'F',{fb,{'E',35,
>                   [{'D',3,true},
>                    {'D',4,false},
>                    {'D',5,true},
>                    {'D',6,true},
>                    {'D',7,false},
>                    {'D',8,true},
>                    {'D',9,true},
>                    {'D',10,false},
>                    {'D',11,true},
>                    {'D',12,true},
>                    {'D',13,false},
>                    {'D',14,true}],
>                   false,
>                   {a,[{'A',16,{'D',17,true}}]}}}}
>     6> {ok,F_Bytes}='Seq':encode('F',F_Msg).
>     {ok,[<<161>>,
>          [127],
>          [<<128>>, ...

>     8> {ok,{fb,{'E',Int,{Type_Key_SeqOf,Val_SEQOF},BoolOpt,{Type_Key_Choice,Val_Choice}}}}='Seq':decode_F_fb_exclusive(list_to_binary(F_Bytes)).
>     {ok,{fb,{'E',35,
>                  {'E_b',[<<48,6,128,1,3,129,1,255>>,
>                          <<48,6,128,1,4,129,1,0>>,
>                          <<48,6,128,1,5,129,1,255>>,
>                          <<48,6,128,1,6,129,1,255>>,
>                          <<48,6,128,1,7,129,1,0>>,
>                          <<48,6,128,1,8,129,1,255>>,
>                          <<48,6,128,1,9,129,1,255>>,
>                          <<48,6,128,1,10,129,1,0>>,
>                          <<48,6,128,1,11,129,1,255>>,
>                          <<48,6,128,1,12,129,1,255>>,
>                          <<48,6,128,1,13,129,1,0>>,
>                          <<48,6,128,1,14,129,1,255>>]},
>                  false,
>                  {'E_d',<<163,21,160,19,48,17,2,1,16,160,12,172,10,171,8,48,6,128,1,...>>}}}}
>     10> 'Seq':decode_part(Type_Key_SeqOf,Val_SEQOF).
>     {ok,[{'D',3,true},
>          {'D',4,false},
>          {'D',5,true},
>          {'D',6,true},
>          {'D',7,false},
>          {'D',8,true},
>          {'D',9,true},
>          {'D',10,false},
>          {'D',11,true},
>          {'D',12,true},
>          {'D',13,false},
>          {'D',14,true}]}
>     11> 'Seq':decode_part(Type_Key_SeqOf,hd(Val_SEQOF)).
>     {ok,{'D',3,true}}
>     12> 'Seq':decode_part(Type_Key_Choice,Val_Choice).
>     {ok,{a,[{'A',16,{'D',17,true}}]}}

Copyright © 1991-2003 Ericsson Utvecklings AB