TOP

ASN.1/C++ Compiler Directives Reference

Applies to: ASN.1/C++ 6.5

ASN1.DeferDecoding

Prevents the compiler from automatically decoding a specific component within a CHOICE, SEQUENCE, or SET when its containing type is marked for decoding. By default, all components of CHOICE, SET, or SEQUENCE are decoded with their containing type.

Format

--<ASN1.DeferDecoding absoluteReference>--

The class that absoluteReference refers to will be replaced by the OssOpen class, which the user application will encode and decode separately.

Remarks

The ASN1.DeferDecoding directive has no effect on PER encodings and it is not supported by OER, C-OER, or XER.

Example

--<ASN1.DeferDecoding Module.Type.setComponent>--
Module DEFINITIONS ::= BEGIN
    Type ::= SET {
        setComponent INTEGER,
        b BOOLEAN
    }
END

The following types are produced in the .h file for the ASN.1 above:

class OSS_PUBLIC Type   /* SET */
{
public:
. . .
    typedef OssOpen setComponent;
    typedef ossBoolean b;
    . . .

    setComponent & get_setComponent();
    const setComponent & get_setComponent() const;
    void set_setComponent(const setComponent &);
    
    b & get_b();
    b get_b() const;
    void set_b(b);
    . . .
};

typedef OSS_INT32 Type_setComponent_encodable;

See Also

↩Directives Index


ASN1.HugeInteger

Sets a special representation for INTEGERs whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.

Format

--<ASN1.HugeInteger absoluteReference>--

absoluteReference refers to an ASN.1 INTEGER type that will be represented using the OssHugeInt class.

Example

--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--

LengthModule DEFINITIONS ::= BEGIN
    LengthData ::= SEQUENCE {
        lengthOfSolarSystem  INTEGER,
        units  ENUMERATED
                {mm(0), cm(1), m(2), km(3), lightyears(4)} DEFAULT mm
    }
END

When the OSS ASN.1/C++ compiler compiles the example ASN.1 above, the following code is generated in the header file:

class OSS_PUBLIC LengthData   /* SEQUENCE */
{
public:
. . .
    typedef OssHugeInt lengthOfSolarSystem;
    typedef enum _enum1 units;
. . .

    lengthOfSolarSystem & get_lengthOfSolarSystem();
    const lengthOfSolarSystem & get_lengthOfSolarSystem() const;
    void set_lengthOfSolarSystem(const lengthOfSolarSystem &);

    units *get_units();
    const units *get_units() const;
    void set_units(units );
    int units_is_default() const;
    void set_default_units();
. . .
};

See Also

↩Directives Index


ASN1.Nickname

Assigns an alias to a name in an ASN.1 module for use in the generated code. By default, names in the generated code are derived from the input ASN.1 syntax.

Format

--<ASN1.Nickname absoluteReference nickname>--

absoluteReference specifies a name for one of the following:

  • Module
  • Type reference
  • Value reference
  • Macro reference
  • Object class reference
  • Object reference
  • Object set reference
  • Identifier or field name
  • Element of a SET or SEQUENCE
  • Anonymous component of a SET or SEQUENCE
  • Identifier in a NamedNumberList

The nickname parameter should follow the naming rules of the target programming language.

Examples

  1. In the following notation, the MTN nickname is used for the MyTypeName type, which is an element of the MySequence SEQUENCE within the MyModule module.
    --<ASN.1.Nickname MyModule.MySequence.MyTypeName MTN>--
  2. This example illustrates renaming type, value, object, object class, and object set references using ASN1.Nickname:
    --<ASN1.Nickname Module.UserData Monkey>--
    --<ASN1.Nickname Module.UserData.* Gorilla>-- 
    --<ASN1.Nickname Module.UserData.*.1 Gibbon>-- 
    --<ASN1.Nickname Module.UserData.*.fvalue Mandrill>--
            
    Module DEFINITIONS ::= BEGIN 
        UserData ::= SET OF SEQUENCE { 
            key    INTEGER, 
            fvalue OCTET STRING OPTIONAL 
        }
    END
  3. In the absolute reference of the Gibbon nickname, * refers to the SEQUENCE and the following 1 refers to the first element in that SEQUENCE, which is key. The ASN.1 syntax above is equivalent to the following:

    Module DEFINITIONS ::= BEGIN
        UserData ::= SET --<TYPENAME "Monkey">-- OF
            SEQUENCE {
                key     INTEGER --<FIELDNAME "Gibbon">--,
                fvalue  OCTET STRING --<FIELDNAME "Mandrill">-- OPTIONAL
            } --<TYPENAME "Gorilla">--
    END

    When compiled, both versions of the ASN.1 syntax create the following code in the generated .h file:

    class OSS_PUBLIC Monkey : public OssList  /* SET OF */
    {
    public:
        typedef Gorilla component;
    . . .
    };
    
    class OSS_PUBLIC Gorilla   /* SEQUENCE */
    {
    public:
    . . .
        typedef OSS_INT32 Gibbon;
        typedef OssString Mandrill;
    . . .
    };

  4. The following example demonstrates renaming ASN.1 identifiers or fields.
    --<ASN1.Nickname Module.PasswordChallengeRequestResponse.
    -- challengeRequestResponse.challengeResponse pcrrResponse>--
    
    Module DEFINITIONS ::= BEGIN
        PasswordChallengeRequestResponse ::= CHOICE {
            passwordInTheClear               INTEGER,
            challengeRequestResponse         SEQUENCE {
                challengeRequest   BOOLEAN  OPTIONAL,
                challengeResponse  INTEGER  OPTIONAL
            }
        }
    END
  5. ASN.1 compilation results in the following code:

    class OSS_PUBLIC __seq1   /* SEQUENCE */
    {
    public:
    . . .
        typedef ossBoolean challengeRequest;
        typedef OSS_INT32 pcrrResponse;
    . . .
    };

    NOTE: For this example, you could substitute OSS.FIELDNAME for ASN1.Nickname and get the same result.

  6. This example shows how to rename a SET OF or SEQUENCE OF element.
    --<ASN1.Nickname Module.UserData.* UserDataSeq>--
    
    Module DEFINITIONS ::= BEGIN
        UserData ::= SET OF SEQUENCE {
            key    INTEGER,
            value  OCTET STRING OPTIONAL
        }
    END
  7. In the ASN1.Nickname directive, * refers to the intermediate type created for the SEQUENCE.
    The ASN.1 Compiler generates code that includes:

    class OSS_PUBLIC UserData : public OssList  /* SET OF */
    {
    public:
        typedef UserDataSeq component;
    . . .
        component *at(OssIndex);
        const component *at(OssIndex) const;
    
        OssIndex prepend(const component & );
        OssIndex prepend(UserData *);
        OssIndex insert_after(OssIndex, const component & );
        OssIndex insert_after(OssIndex, UserData *);
    
        int remove_front();
        int remove_after(OssIndex);
    
        UserData *extract_after(OssIndex, OssIndex);
    };
    
    class OSS_PUBLIC UserDataSeq   /* SEQUENCE */
    {
    public:
    . . .
        typedef OSS_INT32 key;
        typedef OssString value;
    . . .
        key & get_key();
        key get_key() const;
        void set_key(key);
    
        value *get_value();
        const value *get_value() const;
        void set_value(const value &);
        int value_is_present() const;
        void omit_value();
    . . .
    };

  8. The following example shows how to rename a NamedNumberList identifier:
  9. --<ASN1.Nickname Module.E.enum1 "new_enum1">--
    
    Module DEFINITIONS ::= BEGIN
            E ::= ENUMERATED {enum1(1), enum2(2)}
    END

See Also

↩Directives Index


ASN1.PDU

Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs). By default, all unreferenced types (defined types not referenced by any other type) are considered PDUs by the compiler, so they can be encoded and decoded as complete units.

Format

--<ASN1.PDU type [, type] ...>--

type is an absolute reference that specifies which ASN.1 types should be treated as PDUs.

Example

--<ASN1.PDU Module.Type>--

Module DEFINITIONS ::= BEGIN
TypeRef ::= Type
Type ::= SET { b BOOLEAN }
END

In the example above, Type will be treated as a PDU, even if it is referenced in another type definition.
After ASN.1 compilation, the following is generated in the header file:

/* Universal PDU class */

class OSS_PUBLIC sample_PDU : public UniversalPDU {
public:
    sample_PDU();
    void set_TypeRef(TypeRef &);
    TypeRef *get_TypeRef() const;
    void set_Type(Type &);
    Type *get_Type() const;
. . .
};

/* Specific PDU classes */

class OSS_PUBLIC TypeRef_PDU : public ConcretePDU {
public:
    TypeRef_PDU();
    void set_data(TypeRef &);
    TypeRef *get_data() const;
. . .
};

class OSS_PUBLIC Type_PDU : public ConcretePDU {
public:
    Type_PDU();
    void set_data(Type &);
    Type *get_data() const;
. . .
};

See Also

↩Directives Index


ASN1.RealRepresentation

Selects a binary or decimal representation for ASN.1 REAL type values. This directive can be applied to specific REAL types, or set as default for all REAL types. By default, the REAL type is represented by the C++ double class (i.e., binary).

Format

--<ASN1.RealRepresentation realKind type [, type, ...]]>--

realKind refers to the desired representation and can be binary or decimal. Use binary to represent a REAL as a double in the generated .cpp and .h files. Use decimal to represent a REAL as a character string in "[-]nnnnn.nnnnn[E[-]nnnnn]" format (OssDecimal class). Each type is an absolute reference to a type or types affected by the directive. If no type is specified, the ASN1.RealRepresentation directive sets the default representation for REAL types at the local, module, or global level, according to its placement.

Remarks

For a global effect, use the ASN1.RealRepresentation directive without type references and place it before the first module in the ASN.1 input.

Example

--<ASN1.RealRepresentation decimal Module.Type.a1.b2>--

Module DEFINITIONS ::= BEGIN

    Type ::= SEQUENCE {
        a1 SET { b1 INTEGER, b2 REAL},
        a2 REAL
    }
END

The ASN.1 definition above is equivalent to the following:

Module DEFINITIONS ::= BEGIN

    Type ::= SEQUENCE {
        a1 SET { b1 INTEGER, b2 REAL --<DECIMAL>--},
        a2 REAL
    }
END

When compiled, both versions create the following code in the generated .h file:

class OSS_PUBLIC __set1   /* SET */
{
public:
. . .
    typedef OSS_INT32 b1;
    typedef OssDecimal b2;
. . .
};

class OSS_PUBLIC Type   /* SEQUENCE */
{
public:
. . .
    typedef __set1 a1;
    typedef double a2;
. . .
};

See Also

↩Directives Index


ASN1.Remove

Instructs the compiler to omit certain types or components from input ASN.1 modules when generating the output .h and .cpp files. Use this directive to exclude part of an ASN.1 specification without modifying the original ASN.1 source. By default, all of the input ASN.1 is included in the compiler-generated files.

Format

--<ASN1.Remove absoluteReference [, absoluteReference ] ...>--

absoluteReference can refer to any of the following:

  • Defined type
  • Defined value
  • Component of a CHOICE (excluding the last component specified)
  • OPTIONAL component in a SEQUENCE or SET
  • Component with a DEFAULT value in a SEQUENCE or SET
  • Information object class
  • Information object that is not included in an information object set
  • Information object set

Remarks

Even though components are omitted from the input ASN.1, the encodings that result are compatible with corresponding applications that do not use the ASN1.Remove directive. This is due to the following practices:

  • Automatic tags are assigned as if the removed components were present. In theory, automatic tags are assigned before removal.
  • Some encoding rules, such as PER, are sensitive to the number of possible components. By counting any removed components when encoding, an encoded value will be the same whether or not components have been removed.

When an ASN.1 item is marked for removal, also remove any references to the item using the ASN1.Remove directive. If errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the ASN.1/C++ Compiler automatically generates the needed ASN1.Remove directives in a file with a .rmv extension and the same prefix as the .gen file. The generated .rmv file can be passed to the command line, before any compiler options, so the compiler automatically removes the problematic types. NOTE: In certain circumstances, ASN1.Remove directives cannot be generated into the .rmv file. The user should then call the ASN.1 Compiler several times, correcting the syntax, until the notation ASN.1-compiles cleanly.

The listing file generated with the -listingFile command-line option omits removed items entirely. For a full listing that includes any removed items, use the -modListingFile command-line option.

Standard directives applied to or found within ASN.1 items marked for removal have no effect.

When the ASN1.Remove directive is applied to the fields of a parameterized type, those fields are removed from each instance of the parameterized type. Applying the ASN1.Remove directive to parameterized types is not recommended.

When fields are removed from a type referenced in the COMPONENTS OF type notation, those fields are removed from each type specified with the COMPONENTS OF type notation.

Types that are referenced only by items marked for removal could become PDUs after those items are removed.

Example

--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--

Mod DEFINITIONS ::= BEGIN
    S ::= SET {
        a SET OF SET OF SEQUENCE { 
            b Int
        }OPTIONAL
    }
    Int ::= INTEGER
    i Int ::= 10
END

After compiling the syntax above, only an empty S class is generated in the header file:

class OSS_PUBLIC S   /* SET */
{
public:
    void * operator new(size_t size);
    void operator delete(void *ptr);


    S();
    S(const S &);

    S & operator = (const S &);
    int operator == (const S &) const;
    int operator != (const S &) const;
. . .
};

Following is a more complex example:

--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--

Mod DEFINITIONS ::= BEGIN
  Int ::= INTEGER
  A ::= SEQUENCE {
          a    Int OPTIONAL,
          b    BIT STRING
  }
   a A ::= { a 1, b bit}
   bit BIT STRING ::= '0'B
   
   C ::= CHOICE {
          a Int
   }

   Set ::= SET {
         a SET {
               b SET {
                     c SET {
                           d SET OF SET {
                                 e INTEGER OPTIONAL
                           }
                     }
               }
         }
   }
   s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
END

The example above generates the following ASN1.Remove directives in the .rmv file:

--<ASN1.Remove Mod.s>--
s contains values for component e, which is marked for removal.
--<ASN1.Remove Mod.C>--
C references type Int, which is marked for removal.
--<ASN1.Remove Mod.a>--
a contains values for component A.a that references type Int, which is marked for removal. Also, a references value bit, which is marked for removal.
--<ASN1.Remove Mod.A.a>--
A.a references type Int, which is marked for removal.

↩Directives Index


ASN1.Version

Specifies the year of the ASN.1 standard in use for a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source. By default, the ASN.1 Compiler starts out in neutral mode, expecting any ASN.1 version. Once version-specific syntax is detected, the compiler exits neutral mode and checks for conformance to the detected version.

Format

--<ASN1.Version version moduleName [{ oid }]>--

version refers to a year that an ASN.1 standard was published by ITU-T (e.g., 1990, 1994, 1997, 2002, 2008, or 2015). moduleName is a mandatory operand that specifies the module to which the directive is applied. oid is an optional OBJECT IDENTIFIER for unique module identification.

Remarks

If the ASN1.Version directive conflicts with the -1990 | -2015 compiler option, the most recent version is used.

Example

--<ASN1.Version 1990 Module>--

Module DEFINITIONS --<ASN1VER 1994>-- ::= BEGIN
    a A ::= INTEGER {one(1), two(2)} : one
    A ::= ANY
    Type ::= SET {
        typeComponent INTEGER,
        b BOOLEAN
    }
END

In the example above, the ASN1.Version directive takes precedence over the OSS-specific legacy ASN1VER directive.

See Also

↩Directives Index


ASN1.WorkingSet

Selects those items in the ASN.1 input that are key to the application. All names (types, values, information objects, etc.) defined in the working set are directly available for use by the application. By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives present. See Default Determination of the Working Set below for details.

Format

--<ASN1.WorkingSet WSName absoluteReference [, absoluteReference] ...>--

WSName is the name of the working set. Although required for consistency with other ASN.1 Tools, it is otherwise ignored. absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. When a module name is referenced, the ASN1.WorkingSet directive has the same effect as that of the OSS.ROOT directive: all unreferenced types in this module are considered PDUs.

Remarks

Items in the ASN.1 specification that are not included in the working set are available to the application only when they are referenced from the working set.

A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set on its own.

To extend an existing working-set, specify another instance of the ASN1.WorkingSet directive containing the existing working-set name and the ASN.1 item to be added. In the following ASN.1, both module1 and module14 will be included in commonSet:

--<ASN1.WorkingSet commonSet module1>--
. . .
--<ASN1.WorkingSet commonSet module14>--

Examples

Including a type reference in a working set does not necessarily make it a PDU. In the following ASN.1, MyWorkingSet does not explicitly include A.Foo; it is included implicitly since A.Foo is referenced by A.Bar. The result is two types in the working set that reference each other; so neither is a PDU (unless the implementation makes them so).

--<ASN1.WorkingSet MyWorkingSet A.Bar>--

A DEFINTIONS ::= BEGIN
    Foo ::= SEQUENCE OF Bar
    Bar ::= SEQUENCE {a INTEGER, b Foo OPTIONAL}
    Z ::= BOOLEAN
END

In this example, Type1, Type2, and Type4 are directly available to the application as PDUs; Type3 is not.

--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
    Type1 ::= SET {
        typeComponent INTEGER,
        b BOOLEAN 
    }
    Type2 ::= INTEGER
END

Module3 DEFINITIONS ::= BEGIN
    Type3 ::= SET {
        aComponent INTEGER,
        b BOOLEAN
    }
    
    Type4 ::= IA5String
END

Default Determination of the Working Set

The ASN.1 Compiler derives the working set by considering four types of directives, in the following order:

  1. ASN1.WorkingSet directives
  2. Other standard directives
  3. OSS.ROOT directives
  4. Other OSS-specific directives

Based on the presence or absence of these directives in the input, the ASN.1 Compiler assumes one of these four modes:

Default working set
All input module names are included in the working set. When the -genDirectives command-line option is specified, the compiler generates an ASN1.WorkingSet directive for each module name in the .gen file.
Root default
Only the last module is included in the working set. When the -genDirectives command-line option is specified, there are no ASN1.WorkingSet or OSS.ROOT directives included in the .gen file.
Working set
The working set includes only modules explicitly specified by the ASN1.WorkingSet and the OSS.ROOT directives. Additionally, when the -genDirectives command-line option is specified, the resulting .gen file contains ASN1.WorkingSet directives for all modules in the working set, even those included by the OSS.ROOT directive. In certain circumstances, especially when the -root option or the global OSS.ROOT directive is specified, both ASN1.WorkingSet and OSS.ROOT directives are generated in the .gen file.
Root
No module is included in the working set unless it is specified in an OSS.ROOT directive. When the -genDirectives command-line option is specified, the compiler generates an OSS.ROOT directive with one or more module name arguments (one argument for each module in the working set) in the .gen file.

Different sets of directives in the ASN.1 input determine which ASN.1 Compiler mode is used, as shown in the following table. 1 means a directive is present, 0 means a directive is absent, and 1/0 indicates that a directive can be present or absent with no effect on mode selection.

Directive Types Present in Input ASN.1 Compiler Mode
ASN1.WorkingSet Other ASN1.* Directives OSS.ROOT Other OSS.* Directives
0 1 0 0 Default Working Set
0 0 0 0 Root Default
0 1/0 0 1
1 1/0 1 1/0 Working Set
0 1 1 1/0
1 1/0 0 1/0
0 0 1 1/0 Root

See Also

↩Directives Index


OSS.ASN1VER

Specifies which version of the ASN.1 standard is in use in the ASN.1 input. By default, the ASN.1 Compiler starts out in neutral mode, expecting any ASN.1 version. Once version-specific syntax is detected, the compiler exits neutral mode and checks for conformance to the detected version.

Format

--<OSS.ASN1VER [absoluteReference] version>--

When specified globally, absoluteReference refers to the name of an ASN.1 module or a module component that should be treated as if it is in ASN.1: version syntax. version refers to a year that an ASN.1 standard was published by ITU-T and can be: 1990, 1994, 1997, 2002, 2008, or 2015. If specified globally without an absolute reference, OSS.ASN1VER sets the ASN.1 version for the entire ASN.1 input. When specified locally, this directive does not accept an absolute reference and only affects the type it is placed next to.

Example

The OSS.ASN1VER directive in this example instructs the compiler to allow the unnamed elements in the NoNames SEQUENCE elements. With ASN.1: 2015, all elements of a CHOICE, SEQUENCE, or SET require an identifier.

--<OSS.ASN1VER MyModule.NoNames 1990>--
MyModule DEFINITIONS ::= BEGIN
    NoNames ::= SEQUENCE {
        BOOLEAN,
        BOOLEAN,
        INTEGER
    }
END

See Also

↩Directives Index


OSS.BMPSTRING

Represents a UTF8String type in C++ as the OssBMPString class.

Format

--<OSS.BMPSTRING [absoluteReference]>--

absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String.

Remarks

OSS.BMPSTRING functions only as a local directive when used without arguments.

When specified globally, this directive expects an absolute reference for a UTF8String type that requires OssBMPString representation. When specified locally, OSS.BMPSTRING does not accept any arguments and affects only the type it is placed next to.

With BMPString and UniversalString representations, character data is automatically converted to UTF-8 format before XER/CXER/E-XER encoding and is converted from UTF-8 format after XER/CXER/E-XERdecoding.

Example

--<OSS.BMPSTRING Module.TwoByteGlobal>--
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--

Module DEFINITIONS  ::= BEGIN
    Default         ::= UTF8String
    TwoByteLocal    ::= UTF8String --<BMPSTRING>--
    TwoByteGlobal   ::= UTF8String
    FourByteLocal   ::= UTF8String --<UNIVERSALSTRING>--
    FourByteGlobal  ::= UTF8String
END

The above syntax shows OSS.BMPSTRING used with and without arguments. TwoByteGlobal is set to OssBMPString representation by specifying OSS.BMPSTRING globally with an absolute reference. TwoByteLocal is set using the directive at the local level. OSS.BMPSTRING is not applied to Default, so it is set to the default OssString representation. FourByteLocal and FourByteGlobal are set to OssUniversalString representation by the OSS.UNIVERSALSTRING directive. Part of the generated header file for the above notation is shown below:

typedef OssString Default;

typedef OssBMPString TwoByteLocal;

typedef OssBMPString TwoByteGlobal;

typedef OssUniversalString FourByteLocal;

typedef OssUniversalString FourByteGlobal;

See Also

↩Directives Index


OSS.COMMENT

Instructs the ASN.1 Compiler to place a user-defined comment near the beginning of the generated .cpp and .h files. By default, user-defined comments are not generated.

Format

--<OSS.COMMENT "commentText">--

commentText is the comment, enclosed in quotation marks, that will appear at the top of the generated files.

Remarks

The OSS.COMMENT directive can only be specified globally and can occur only once in the ASN.1 input. If two or more OSS.COMMENT statements are found, the last one encountered is used and the others are ignored.

Example

--<OSS.COMMENT "!ALERT! PDU should be encrypted before sending.">--

AccessData DEFINITIONS ::= BEGIN
    TopSecret ::= SEQUENCE {
            username        IA5String,
            password        IA5String,
            accessLevel     INTEGER
    }
END

When the ASN.1 syntax above is compiled, the comment is generated at the top of the .h and .cpp files, just below the copyright information:

/***************************************************/
/* !ALERT! PDU should be encrypted before sending.*/
/***************************************************/

↩Directives Index


OSS.DataCallback

Associates SEQUENCE or SET fields, CHOICE alternatives, or SEQUENCE OF or SET OF elements with your callback method when using partial decoding. This directive affects only generated decoding functions. The -enablePartialDecode and -partialDecodeOnly options cause the <module_name>_Callback class to be incorporated into the generated header and code files; other definitions are unaffected.

Format

When specified globally, either in an ASN.1 file before the module definition or in a separate directives file, the OSS.DataCallback directive takes an absolute reference to a field:

--<OSS.DataCallback [absoluteReference] ["]MethodName["]>--

MethodName is the user-defined name for the callback method.

When specified locally, the OSS.DataCallback directive is placed next to the field definition, as shown in the following example:

age INTEGER(1..100) --<OSS.DataCallback "MethodName">--

When OSS.DataCallback is applied to a field of a named type, the decoded PDU could include several fields of this type. The decoder will call the same callback method for each one, and cannot differentiate a call for one field from a call for another since both are associated with the same method. Consider using the OSS.InfoCallback directive to discern the difference.

See Also

↩Directives Index


OSS.DECIMAL

Sets the representation for an ASN.1 REAL type. By default, REAL is represented as a double in C++.

Format

--<OSS.DECIMAL [absoluteReference]>--

absoluteReference refers to a component in the ASN.1 syntax to be represented by the OssDecimal class.

Remarks

When the OSS.DECIMAL directive is used, the OssDecimal class is generated. The internal representation is a null-terminated character string of the form: [-]nnnnn.nnnnn[E[-]nnnnn]. The character string pointer can also be set to point to the special OSS_PLUS_INFINITY, OSS_MINUS_INFINITY and ossNaN variables.

When specified globally, this directive expects an absolute reference for a REAL type that requires OssDecimal representation. If specified globally without an absolute reference, OSS.DECIMAL sets the representation for all REAL types within its scope. When specified locally, this directive does not take any arguments and affects only the type it is placed next to.

NOTE: Constraining the base of a REAL type to 2 implies the binary representation, which is represented as a double. Constraining the base to 10 implies the decimal representation, which is represented as the ASN.1/C++ OssDecimal class.

WARNING: double is the default representation because OSS determined that this is what most users want. However, this is inconsistent with the ASN.1 standard, which implies that values encoded in base 10 must be represented in a format suitable for base 10 and values encoded in base 2 must be represented in a format suitable for base 2. This is to prevent loss of precision when converting to and from their floating point representations. To ensure no loss of precision occurs, constrain REAL types to base 2 or base 10.

Example

The following example demonstrates using OSS.DECIMAL at the global and local levels.

--<OSS.DECIMAL>--

Module DEFINITIONS ::= BEGIN
    Decimal         ::= REAL (WITH COMPONENTS {..., base (10) } )
    DecimalAlso     ::= REAL (WITH COMPONENTS {..., base (2) } )
    DecimalToo      ::= REAL
    DecimalOnceMore ::= REAL --<DECIMAL>--
END

When the syntax above is compiled, the following is generated in the .h file:

typedef OssDecimal Decimal;

typedef OssDecimal DecimalAlso;

typedef OssDecimal DecimalToo;

typedef OssDecimal DecimalOnceMore;

The --<OSS.DECIMAL>-- global directive overrides the default representation of the base 2 constraint.

See Also

↩Directives Index


OSS.DEFINITE | OSS.INDEFINITE

Instructs the compiler to use the definite or indefinite length form when encoding PDUs.

Format

--<OSS.DEFINITE [absoluteReference]>--
--<OSS.INDEFINITE [absoluteReference]>--

absoluteReference refers to an ASN.1 component in the specification that is a PDU.

Remarks

When specified globally, these directives require an absolute reference to the targeted PDU. If these directives are applied to non-PDU ASN.1 types there is no effect. When specified globally without an absolute reference, OSS.DEFINITE and OSS.INDEFINITE sets the type of length encoding for all PDUs in their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.

The TOED and LED BER encoders do not currently support the indefinite length form of encoding. On the other hand, all of the decoders (SOED, TOED, LED) do support the indefinite length form of encoding.

Example

The following example illustrates local and global use of these directives. When compiled with the -soed option, the OSS.INDEFINITE directive sets a global default for indefinite length encoding. Consequently, ByteStream is encoded using the indefinite length form, since no other directives are applied to it. However, DataPacket will be encoded using the definite length form due to the local DEFINITE directive placed next to it. The directives do not affect the generated header file.

--<OSS.INDEFINITE>--

Module DEFINITIONS ::= BEGIN
        ByteStream ::= OCTET STRING
        DataPacket ::= SEQUENCE {
            username    IA5String,
            userID      INTEGER
        } --<DEFINITE>--
END

Default Behavior

The compiler uses the definite length form.

↩Directives Index


OSS.DTD

Instructs the compiler to generate a separate DTD (XML Data Type Definition) for a specified PDU. By default, no DTDs are produced by the ASN.1 Compiler unless the -dtd option is specified.

Format

--<OSS.DTD [absoluteReference "NewName.dtd"]>--

absoluteReference refers to a PDU in the ASN.1 input for which to generate a separate XML DTD. NewName is an optional argument that specifies a filename for the generated DTD. Although the OSS.DTD directive can appear anywhere white space is allowed, the OSS prefix and a full absolute reference is required.

Remarks

When the -dtd compiler option is specified, a DTD for each PDU in the input is generated into a separate file whose name is derived from that of the PDU.

NOTE: You can use DTDs to make XER output produced by encode() editable in a non-ASN.1-specific XML tool. Also, you can use the setXmlDTD() method of the OssControl class to have the encode() method generate a reference to your DTD in the produced XER encoding.

Example

In the following example, two separate DTD files, StringType.dtd and AnotherNameForInt.dtd, are produced for their PDUs.

--<OSS.DTD XModule.StringType>--
--<OSS.DTD XModule.IntType "AnotherNameForInt.dtd">--

XModule DEFINITIONS ::= BEGIN
    StringType ::= UTF8String
    IntType ::= INTEGER
    studentName ::= <StringType>John H. Doe</StringType>
    studentAge ::= <IntType>23</IntType>
END

See Also

↩Directives Index


OSS.ENCODABLE

Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures. When OSS.ENCODABLE is applied to a CHOICE, SEQUENCE, or SET component, that component will be represented as an open type. Also, the type that would normally have been generated as a field in its class is generated as a typedef, which can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded. By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal forms.

Format

--<OSS.ENCODABLE [absoluteReference]>--

Remarks

When specified globally, this directive requires an absolute reference to the targeted CHOICE, SEQUENCE, or SET component. When specified locally, this directive does not take any arguments and affects only the type that it is placed next to.

Do not apply the OSS.ENCODABLE directive to a tagged type.

This directive does not work when PER is in use.

Example

OSS.ENCODABLE is applied at the local level in the following syntax:

Module DEFINITIONS ::= BEGIN
    A ::= SEQUENCE {
        id    [0] INTEGER,
        data  [1] OCTET STRING --<ENCODABLE>--
    }
END

During compilation, the following is generated in the header file:

class OSS_PUBLIC A   /* SEQUENCE */
{
public:
. . .
    typedef OSS_INT32 id;
    typedef OssOpen data;

    A();
    A(const A &);
    A(id, const data &);

    A & operator = (const A &);
    int operator == (const A &) const;
    int operator != (const A &) const;

    id & get_id();
    id get_id() const;
    void set_id(id);

    data & get_data();
    const data & get_data() const;
    void set_data(const data &);
. . .
};

typedef OssString A_data_encodable;

The class generated for the SEQUENCE uses OssOpen (open type) for the data component.

See Also

↩Directives Index


OSS.ExerNumericBoolean

BOOLEAN types are encoded as numeric values of 0 and 1, instead of "true" and "false", when a GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instruction is present. This is useful for

  • Reducing the size of encoded XML documents.
  • Exchanging information with decoders that understand only numeric BOOLEAN values.

Format

--<OSS.ExerNumericBoolean [absoluteReference]>--

absoluteReference refers to the affected type.

Example

In the following example, the value p0 is encoded as <Presence>0</Presence> and not as <Presence>absent</Presence>:

  --<OSS.ExerNumericBoolean Test.Presence>--
  
  Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
     Presence ::= BOOLEAN
     p0 Presence ::= FALSE
     
     ENCODING-CONTROL XER
     GLOBAL-DEFAULTS MODIFIED-ENCODINGS
     TEXT Presence:false AS "absent"
     TEXT Presence:true AS "present"
  END

↩Directives Index


OSS.EXTENSIBLE | OSS.INEXTENSIBLE

Enables or disables decoder support for the rules of extensibility. At compile time, an internal flag is set that is associated with SEQUENCE, SET, and BIT STRING types.

Format

--<OSS.EXTENSIBLE [absoluteReference]>--
--<OSS.INEXTENSIBLE [absoluteReference]>--

Remarks

When specified globally, these directives can take an absolute reference, which refers to the affected BIT STRING, SEQUENCE, or SET type. If specified globally without an absolute reference, the OSS.EXTENSIBLE and OSS.INEXTENSIBLE directives determine how the decoder handles extensible elements. If specified locally, these directives do not take any arguments and affect only the type they are placed next to.

When decoding a PDU, consider the following rules of extensibility:

  • Ignore all elements of a SET or SEQUENCE whose tags are not defined in the ASN.1 Compiler input.
  • When using named bits, bits that have no names assigned in the ASN.1 source file are ignored. For example, if a BIT STRING defines named bits, and bits other than those named bits are encountered in the input stream, the decoder ignores them.

The OSS.EXTENSIBLE directive functions the same as the ASN.1 formal extension marker (...). You can use either the directive or the extension marker, but not both.

These directives do not affect C++ representation in the header file.

Example

This example shows global and local use of the directives; the local OSS.INEXTENSIBLE overrides the global OSS.EXTENSIBLE for Sample1.Name2.

--<OSS.EXTENSIBLE>--

Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN

    Name1 ::= SEQUENCE {
        a INTEGER,
        b VisibleString
    }

    Name2 ::= SET {
        c INTEGER,
        d VisibleString
    } --<INEXTENSIBLE>--
END

Default Behavior

The OSS.INEXTENSIBLE directive is implied.

↩Directives Index


OSS.ExtensibleUseType

Affects how unknown values of extensible CHOICE types with a final XER USE-TYPE encoding instruction are decoded. Each unknown value contains the xsi:type attribute with an unrecognized value.

Format

--<OSS.ExtensibleUseType>--

Remarks

By default, the CHOICE data described above is decoded as data that matches the first alternative; all unknown elements or attributes are ignored. When OSS.ExtensibleUseType is present, the decoder treats such data as an unknown extension rather than a value of the first CHOICE alternative. If the input ASN.1 specification was compiled with the –relaySafe option, the entire XML sub-element that matches the unknown extension is preserved in the special "unknown alternative" field by the decoder and can be safely relayed to other parties. If -relaySafe was not used, the entire XML sub-element is skipped and the decoded CHOICE type indicates the use of an unknown alternative.

This directive is useful when dealing with unknown elements and attributes from the USE-TYPE content model at a low level. The decoder skips them by default, so to analyze such data, use the -relaySafe option and apply OSS.ExtensibleUseType to the CHOICE type to access the encoded XML data.

Example

ASN.1 specification

Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN

T ::= [USE-TYPE] CHOICE {
    base SEQUENCE {i INTEGER},
    e1 SEQUENCE {i INTEGER, b BOOLEAN},
    ...
    } --<ExtensibleUseType>--

    ENCODING-CONTROL XER
    GLOBAL-DEFAULTS MODIFIED-ENCODINGS
    GLOBAL-DEFAULTS CONTROL-NAMESPACE
     "http://www.w3.org/2001/XMLSchema-instance" PREFIX "xsi"
END

Example XML document

<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
<i>1</i>
<j>2</j>
</T>

Decoding the above XML produces different results depending on whether ExtensibleUseType and -relaySafe are used:

  • Without ExtensibleUseType, unknown content is skipped:
    value T ::= base :
      {
        i 1
      }
  • With ExtensibleUseType and without -relaySafe, the entire XML subtree is skipped
    value T ::= <unknown>

    and the decoded CHOICE value contains the following data:

    choice == 0
  • With ExtensibleUseType and -relaySafe, the XML subtree is relayed
    value T ::= <unknown>
    and the decoded CHOICE value contains the following data:
    choice == ossUnknownAlt_chosen
    u.ossUnknownAlt contains 
      <T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
        <i>1</i>
        <j>2</j>
      </T>

See Also

↩Directives Index


OSS.FIELDNAME | OSS.TYPENAME

Instructs the ASN.1 Compiler to generate a specific name for a field in a class or for a user-defined type. By default, elements in a class and user-defined types have names derived from their ASN.1 notation.

Format

--<OSS.FIELDNAME [absoluteReference] [newName]>--
--<OSS.TYPENAME [absoluteReference] [newName]>--

newName is a valid C++ identifier.

Remarks

Use OSS.FIELDNAME to specify the name of a SET, SEQUENCE, or CHOICE component to be generated in the header file, instead of one derived by default from the component's ASN.1 identifier.

Use OSS.TYPENAME to specify the name of a user-defined type to be generated in the header file, instead of one derived from the ASN.1 input by default.

When specified globally, these directives require an absolute reference that refers to the ASN.1 component to be renamed in the generated header file, along with newName. When specified locally, only newName is needed, enclosed in quotation marks.

NOTE: These directives have an absolute effect: the ASN.1 Compiler will not change the specified names, even if they are invalid. If the name you specify conflicts with one that the compiler derived from an ASN.1 identifier or type reference, the compiler alters that other name.

Example

The following ASN.1 illustrates local and global use of these directives:

--<OSS.TYPENAME Module.RenamedStr "asciiStr">--

Module DEFINITIONS ::= BEGIN
    DefaultName         ::= [1] SET OF INTEGER
    RenamedInt          ::= [2] SET OF INTEGER
    DefaultStruct       ::= [3] SEQUENCE {
        lunchPrepared   BOOLEAN,
        cost            REAL
    }
    RenamedStruct       ::= [4] SEQUENCE {
        lunchPrepared   BOOLEAN --<FIELDNAME "lunchReady">--,
        cost            REAL
    }

    DefaultNameStr     ::= [5] IA5String
    RenamedStr         ::= [6] IA5String
END

When ASN.1-compiled, the following is generated in the header file:

class OSS_PUBLIC __shared1 : public OssList  /* SET OF */
{
public:
    typedef OSS_INT32 component;
. . .
};

typedef __shared1 DefaultName;

typedef __shared1 RenamedInt;

class OSS_PUBLIC DefaultStruct   /* SEQUENCE */
{
public:
. . .
    typedef ossBoolean lunchPrepared;
    typedef double cost;

    DefaultStruct();
    DefaultStruct(const DefaultStruct &);
    DefaultStruct(lunchPrepared, cost);

    DefaultStruct & operator = (const DefaultStruct &);
    int operator == (const DefaultStruct &) const;
    int operator != (const DefaultStruct &) const;

    lunchPrepared & get_lunchPrepared();
    lunchPrepared get_lunchPrepared() const;
    void set_lunchPrepared(lunchPrepared);

    cost & get_cost();
    cost get_cost() const;
    void set_cost(cost);
. . .
};

class OSS_PUBLIC RenamedStruct   /* SEQUENCE */
{
public:
. . .
    typedef ossBoolean lunchReady;
    typedef double cost;

    RenamedStruct();
    RenamedStruct(const RenamedStruct &);
    RenamedStruct(lunchReady, cost);

    RenamedStruct & operator = (const RenamedStruct &);
    int operator == (const RenamedStruct &) const;
    int operator != (const RenamedStruct &) const;

    lunchReady & get_lunchReady();
    lunchReady get_lunchReady() const;
    void set_lunchReady(lunchReady);

    cost & get_cost();
    cost get_cost() const;
    void set_cost(cost);
. . .
};

typedef OssString DefaultNameStr;

typedef OssString asciiStr;

See Also

↩Directives Index


OSS.GenericOpenType

Causes the specified ASN.1 open type to be represented by the OssOpen class. By default, the C++ representation of an ASN.1 open type depends on the constraints applied to it.

Format

--<OSS.GenericOpenType absoluteReference>--

Example

--<OSS.GenericOpenType Module.S.value>--

Module DEFINITIONS ::= BEGIN
    C ::= CLASS {
&code INTEGER,
&Type
    }

    Object C ::= {
        { &code 1, &Type INTEGER } |
        { &code 2, &Type UTF8String }
    }

    S ::= SEQUENCE {
        key C.&code ({Object}),
        value C.&Type ({Object}{@key})
    }
END

During ASN.1 compilation of the notation above, the following is generated in the header file:

class OSS_PUBLIC S   /* SEQUENCE */
{
public:
    void * operator new(size_t size);
    void operator delete(void *ptr);

    typedef OSS_INT32 key;
    typedef OssOpen value;
. . .
};

↩Directives Index


OSS.HUGE

Applies the OssHugeInt representation to integers whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine-dependent integers.

Format

--<OSS.HUGE [absoluteReference]>--

Remarks

When specified globally, absoluteReference refers to an INTEGER that requires OssHugeInt representation. When specified locally, OSS.HUGE takes no operands and affects only the type it is placed next to.

When an INTEGER type with OSS.HUGE applied is constrained to be non-negative, a type value is treated as an unsigned number rather than as a two's complement binary integer. For the BER/DER encoder, this ensures that unsigned HUGE INTEGER values are encoded correctly by prepending an extra 0 octet when the high order bit of the value is 1.

Value constraints on an INTEGER type with OSS.HUGE applied cannot exceed a 64-bit integer as the ASN.1 compiler will issue an error message.

Example

HugeInt DEFINITIONS ::=
      BEGIN
          A ::= INTEGER --<HUGE>--
      END

ASN.1-compiling the ASN.1 notation above generates the following code in the header file:

typedef OssHugeInt A;

See Also

↩Directives Index


OSS.INCLUDES

Specifies one or more configuration files, containing global compiler directives, to be inserted where OSS.INCLUDES is specified. This is useful when defining different sets of compiler directives to be included or excluded, depending on the application.

Format

--<OSS.INCLUDES "configFilename"[, "configFilename"...]>--

This directive can only be specified globally and requires at least one configuration filename; the configuration file specified can contain only global directives.

Remarks

If a directive in a configuration file conflicts with a directive that is defined either in another configuration file or within the ASN.1 module, the last directive (scanning left to right, top to bottom) takes precedence. All directives defined within an ASN.1 source or INCLUDES file take precedence over those defined in the asn1dflt file.

Directives obtained from a configuration file read by OSS.INCLUDES override any conflicting directives in the asn1dflt file.

Example

When the following example is compiled, directives from file1.cfg and file2.cfg are inserted at the location of the OSS.INCLUDES directive. The OSS.INCLUDES directive is not mentioned in the generated header file.

--<OSS.INCLUDES "file1.cfg", "file2.cfg" >--

Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
    Name1 ::= INTEGER
    Name2 ::= BOOLEAN
END

↩Directives Index


OSS.InfoCallback

Use this helper directive when an OSS.DataCallback directive is applied to a type that occurs in multiple locations in a message.

Format

--<OSS.InfoCallback [absoluteReference] ["]MethodName["]>--

MethodName is the user-defined name for the callback method.

Example

For the following ASN.1

M DEFINITIONS AUTOMATIC TAGS ::= BEGIN

Subscriber ::= SEQUENCE {
   name         VisibleString,
   company      Company,
   homeAddress  Address
}

Company ::= SEQUENCE {
   name    VisibleString,
   address  Address
}

Address ::= SEQUENCE {
   zipcode      INTEGER( 0..99999 ),
   addressline  VisibleString( SIZE (1..64) )
}
END

a directive such as

--<OSS.DataCallback M.Address.zipcode "myZipcode">--

would cause myZipcode() to be called for both Subscriber.homeAddress.zipcode and Company.address.zipcode, but myZipcode() would be unable to differentiate the two fields. OSS.InfoCallback offers a way. By employing

--<OSS.InfoCallback M.Subscriber.homeAddress "homeAddressField">--

you instruct the compiler to generate a prototype for the homeAddressField() callback method inside the <module_name>_Callback class. This method, which you provide, is called by the decoder twice: once before starting the partial decoding of the homeAddress field and again after finishing its decoding.

See Also

↩Directives Index


OSS.NoConstrain

Identifies those types or components for which constraint checking should be disabled. The directive turns off all constraint checking for the type, which includes checking the default permitted alphabet for character strings. For ENUMERATED types, OSS.NoConstrain disables subtype constraints but does not disable enumerator validation. By default, constraint checking is turned on.

Format

--<OSS.NoConstrain [absoluteReference]>--

When specified globally, absoluteReference refers to an ASN.1 type with a defined constraint. OSS.NoConstrain cannot be specified locally.

Remarks

OSS.NoConstrain has no effect if -constraint is explicitly specified, except in the following situations:

  • The directive is applied to a CHARACTER STRING (unrestricted) or an EMBEDDED PDV type.
  • The directive is applied to a BIT STRING or OCTET STRING type constrained by contents constraint. In this case it disables automatic encoding and decoding of the contained type.

Example

Provided -constraint is not specified for the following example, all constraints for S are disabled and S will behave as a simple INTEGER.

--<OSS.NoConstrain Module.S>--

Module DEFINITIONS ::= BEGIN
    S ::= INTEGER (1..10 | 300)
END

In this example, PrintableString abc is passed at run-time without issuing a constraint violation error. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because it is composed of types that have OSS.NoConstrain applied.

--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
 
Mod DEFINITIONS ::= BEGIN
    ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
    abc ABConly ::= "The wrong string"
    
    ShortString ::= PrintableString (SIZE(1 | 3 ))
    shStr ShortString ::= "The long string"
    
    ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
    shABC ShortABCs ::= "ABCDD"
END

For the following example, automatic encoding and decoding will not be performed at run-time even if the -constraint option is specified on the command line:

--<OSS.NoConstrain ContConstr.O>--
ContConstr DEFINITIONS::= BEGIN
    O ::= OCTET STRING (CONTAINING INTEGER)
END

See Also

↩Directives Index


OSS.NODEFAULTVALUE

Informs the ASN.1 Compiler that items with the ASN.1 DEFAULT tag shall be handled as if they have the OPTIONAL tag instead. By default, types with the DEFAULT tag use the specified default value when absent from the encoding.

Format

--<OSS.NODEFAULTVALUE [absoluteReference]>--

When specified globally, absoluteReference can be present and refers to an ASN.1 type with a DEFAULT tag. When specified globally without an operand, the OSS.NODEFAULTVALUE directive affects all types with the DEFAULT tag. When specified locally, the OSS.NODEFAULTVALUE directive takes no operands and affects only the type that it is placed next to.

Example

--<OSS.NODEFAULTVALUE Module.DataCard.a>--
Module DEFINITIONS ::= BEGIN
    DataCard ::= SEQUENCE {
        a [0] BOOLEAN DEFAULT TRUE,
        b [1] BOOLEAN DEFAULT TRUE,
        c [2] BOOLEAN
    }
END

When ASN.1-compiling the above notation, the following is generated in the header file. Note that a is represented as an OPTIONAL component because OSS.NODEFAULTVALUE is applied to it. On the other hand, b is still handled as a component with a default value.

class OSS_PUBLIC DataCard   /* SEQUENCE */
{
public:
. . .
    typedef ossBoolean a;
    typedef ossBoolean b;
    typedef ossBoolean c;

    static const b default_b;

    static b get_default_b();

    DataCard();
    DataCard(const DataCard &);
    DataCard(a, b, c);
    DataCard(c);

    DataCard & operator = (const DataCard &);
    int operator == (const DataCard &) const;
    int operator != (const DataCard &) const;

    a *get_a();
    const a *get_a() const;
    void set_a(a);
    int a_is_present() const;
    void omit_a();

    b *get_b();
    const b *get_b() const;
    void set_b(b);
    int b_is_default() const;
    void set_default_b();

    c & get_c();
    c get_c() const;
    void set_c(c);
. . .
};

↩Directives Index


OSS.PDU | OSS.NOPDU

Instructs the compiler to send or receive ASN.1 types as Protocol Data Units. By default, unreferenced types (defined types not referenced by other types) are considered PDUs and can be encoded and decoded as complete units.

Format

--<OSS.PDU [absoluteReference]>--
--<OSS.NOPDU [absoluteReference]>--

When specified globally, absoluteReference specifies the ASN.1 components that the directive will be applied to. When specified globally without an operand, the OSS.PDU and OSS.NOPDU directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.

Remarks

The OSS.PDU and ASN1.PDU directives only affect types contained in root modules. To treat all input modules as root modules, either specify the -root compiler option or add the global OSS.ROOT directive in your ASN.1 specification.

Example

--<OSS.PDU Module.NameString>--
  
Module DEFINITIONS ::= BEGIN
    MiddleAgeClubCard ::= SEQUENCE {
        name            NameString,
        phoneNumber     PhoneString,
        age             AgeInt
    }
    NameString ::=  IA5String (SIZE (40))
    PhoneString ::= NumericString (SIZE (15)) --<PDU>--
    AgeInt ::= INTEGER (45..54)

END

When the notation above is ASN.1-compiled, the following is generated in the header file:

typedef OssString NameString;

typedef OssString PhoneString;

typedef OSS_UINT32 AgeInt;

class OSS_PUBLIC MiddleAgeClubCard   /* SEQUENCE */
{
. . .
};

/* Universal PDU class */

class OSS_PUBLIC sample_PDU : public UniversalPDU {
public:
    sample_PDU();
    void set_MiddleAgeClubCard(MiddleAgeClubCard &);
    MiddleAgeClubCard *get_MiddleAgeClubCard() const;
    void set_NameString(NameString &);
    NameString *get_NameString() const;
    void set_PhoneString(PhoneString &);
    PhoneString *get_PhoneString() const;
. . .
};

/* Specific PDU classes */

class OSS_PUBLIC MiddleAgeClubCard_PDU : public ConcretePDU {
public:
    MiddleAgeClubCard_PDU();
    void set_data(MiddleAgeClubCard &);
    MiddleAgeClubCard *get_data() const;
. . .
};

class OSS_PUBLIC NameString_PDU : public ConcretePDU {
public:
    NameString_PDU();
    void set_data(NameString &);
    NameString *get_data() const;
. . .
};

class OSS_PUBLIC PhoneString_PDU : public ConcretePDU {
public:
    PhoneString_PDU();
    void set_data(PhoneString &);
    PhoneString *get_data() const;
. . .
};

See Also

↩Directives Index


OSS.POINTER | OSS.NOPOINTER

Instructs the compiler to generate ownership-transferring functions for a component of a type used as a component of a constructed type (i.e., SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF). For OSS.POINTER, this component is represented internally by a pointer to the value, which eliminates excessive copying of large memory blocks. By default, memory for a component is allocated inline, within the container, as is the case with OSS.NOPOINTER.

Format

--<OSS.POINTER [absoluteReference]>--
--<OSS.NOPOINTER [absoluteReference]>--

When specified globally, absoluteReference specifies the ASN.1 component that the directive will be applied to. When specified globally without an operand, the OSS.POINTER and OSS.NOPOINTER directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.

Remarks

These directives have no effect on the following types: BOOLEAN, ENUMERATED, INTEGER, NULL, REAL, and the GeneralizedTime, UTCTime, and ISO 8601 time types. Nothing is gained by having ownership-transferring functions for these types because their values copy as fast as, or faster than, pointers are copied.

Unlike in ASN.1/C, OSS.POINTER and OSS.NOPOINTER do not affect the representation of the type itself. These directives are effective only when the type is used as a component of a constructed type.

Example

--<OSS.POINTER>--
--<OSS.NOPOINTER Module.InlineGlobal>--
Module DEFINITIONS ::= BEGIN
    InlineLocal ::= [1] IA5String --<NOPOINTER>--
    InlineGlobal ::= [2] IA5String
    PointeredGlobal ::= [3] IA5String

    Sequence ::= SEQUENCE {
        a InlineLocal,
        b InlineGlobal,
        c PointeredGlobal
    }
END

When the notation above is ASN.1-compiled, the following is generated in the header file. Notice how the local OSS.NOPOINTER directive overrides the global OSS.POINTER directive.

typedef OssString InlineLocal;

typedef OssString InlineGlobal;

typedef OssString PointeredGlobal;

class OSS_PUBLIC Sequence   /* SEQUENCE */
{
public:
. . .
    typedef OssString a;
    typedef OssString b;
    typedef OssString c;
. . .

    a & get_a();
    const a & get_a() const;
    void set_a(const a &);

    b & get_b();
    const b & get_b() const;
    void set_b(const b &);

    c & get_c();
    const c & get_c() const;
    void set_c(const c &);
    void set_c(c *);
    c *release_c();
private:
    a a_field;
    b b_field;
    c *c_field;
};

↩Directives Index


OSS.ROOT

Identifies the ASN.1 module(s) that is used as the root module(s). In a root module, all unreferenced types are considered PDUs. Also, non-root modules exist only to supply external references to root modules. By default, the last ASN.1 input file specified on the command-line contains the root module.

Format

--<OSS.ROOT  [moduleName[{objectIdentifier}] ...]>--

OSS.ROOT can only be specified globally and takes one or more operands to identify ASN.1 modules. The operand can be a module reference (moduleName), or a module reference followed by a built-in objectIdentifier value. If no operands are provided, all input modules are considered root modules.

Example

--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--

See Also

↩Directives Index


OSS.SampleCode | OSS.NoSampleCode

Instructs the compiler to generate a sample application containing code for the specified PDU types and value references, providing more control over the sample code being created than –sampleCode does. There can be more than one OSS.SampleCode directive in the ASN.1 input.

Format

OSS.SampleCode accepts two different syntax formats, as follows:

--<OSS.SampleCode [pdus] | [values] | [absoluteReference]>--

Use this format to select PDU types and value references for inclusion in the sample code. When absoluteReference is present, it refers to a PDU type, an ASN.1 module, or a PDU value reference; otherwise, the directive is ignored. The pdus and values parameters are accepted only when the directive is specified globally and is applied to an ASN.1 module or to all ASN.1 input; no absoluteReference is specified.

--<OSS.SampleCode count:number | selection [absoluteReference]>--

Use this format to control how the compiler creates sample values for some ASN.1 types.

count:number refers to the entire ASN.1 syntax, an ASN.1 module, or a SEQUENCE OF/SET OF type. number designates how many items the compiler can use to create values for SEQUENCE OF/SET OF types in the sample code. If count:number is not specified for a SEQUENCE OF/SET OF type, the number of items defaults to 1.

selection refers to a CHOICE alternative used by the compiler when creating values for the matching CHOICE type in the sample code. If selection is not specified for a CHOICE type, the first CHOICE alternative is used by default. If several directives are assigned to different alternatives of the same CHOICE type, the compiler creates as many sample values as needed to cover all the selected alternatives.

Use the OSS.NoSampleCode directive to exclude PDU types and value references from the sample application. It has the following format:

--<OSS.NoSampleCode [absoluteReference]>--

When absoluteReference is present, it refers to a PDU type, an ASN.1 module, or a PDU value reference; otherwise, the directive is ignored. The pdus and values parameters are accepted only when the directive is specified globally and is applied to an ASN.1 module or to all ASN.1 input; no absoluteReference is specified.

Remarks

When OSS.SampleCode is applied to the entire ASN.1 input, it has the same effect as the –sampleCode command-line option.

The –noSampleCode command-line option overrides all OSS.SampleCode directives.

The –sampleCode command-line option overrides all OSS.NoSampleCode directives.

Example

For the following ASN.1 syntax, the compiler generates sample code for all value references, except those defined in Module2:

--<OSS.ROOT>--
--<OSS.SampleCode values>--
--<OSS.NoSampleCode Module2>--

Module1 DEFINITIONS ::= BEGIN
   A ::= OCTET STRING
   value1 A ::= '00'H
END

Module2 DEFINITIONS ::= BEGIN
   B ::= INTEGER
   value2 B ::= 1
END

The following ASN.1 syntax demonstrates custom generation of sample values:

--<OSS.SampleCode pdus Module>--
--<OSS.SampleCode selection Module.S.b>--

Module DEFINITIONS ::= BEGIN
   S ::= CHOICE {
      a IA5String,
      b SEQUENCE --<SampleCode count:3>-- OF INTEGER
   }
END

The compiler creates the sample application containing test code for the following value:

samplevalue1-S S ::= b : {
    0,
    0,
    0
}

See Also

↩Directives Index


OSS.SelfCompleteWildcard

Instructs the compiler to mark affected types with a special flag in the control table. When this flag is found at runtime, the E-XER decoder attempts to preserve the wildcard body in the decoded value exactly as it was in the original XML document.

Format

--<OSS.SelfCompleteWildcard [absoluteReference>]--

OSS.SelfCompleteWildcard can be applied to types with a final XER ANY-ELEMENT encoding instruction. It can be specified for a single type, for a module, or globally.

Remarks

When decoding using the EncodedBuffer class, the wildcard contents are copied directly to the output value. When decoding using EncodedFile or EncodedSocket, the decoder can reconstruct the outermost tag of a wildcard, performing whitespace normalization within it and declaring all namespaces before all attributes. In either case, the following is true:

  • Namespaces declared in outer XML elements are not re-declared in the decoded wildcard value.
  • The original order of namespaces and attributes is preserved, provided that the namespaces were declared before the attributes.

If the wildcard contents were normalized according to the W3C Canonical XML specification, the decoded wildcard value will match the original XML value, which enables post-decoding validation of the wildcard's digital signature.

You can use OSS.SelfCompleteWildcard to speed up E-XER decoding of wildcards if you know in advance that they self-complete and do not use namespace or entity declarations from the outer XML document.

Example

--<OSS.SelfCompleteWildcard M.Root.w>--
M DEFINITIONS XER INSTRUCTIONS ::= BEGIN

Root ::= SEQUENCE {
    w [ANY-ELEMENT] UTF8String (CONSTRAINED BY {}) }

ENCODING-CONTROL XER
    GLOBAL-DEFAULTS MODIFIED-ENCODINGS
    NAMESPACE ALL AS "urn:Root" PREFIX "r"

END

For the following XML document

<Root xmlns="urn:Root">
<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>
</Root>

where n1:wildcard is an element wildcard, the decoder produces what is literally the original:

<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>

Without OSS.SelfCompleteWildcard the decoder produces:

<n1:wildcard xmlns:n2="urn:n2" xmlns:n1="urn:n1" xmlns="urn:Root" n2:at2="2" n1:at1="1"/>

See Also

↩Directives Index


OSS.SHORT | OSS.INT | OSS.LONG | OSS.LONGLONG

These directives determine the representation of INTEGER types. Representations for a typical system are shown in the following table:

Directive Representation Notes
OSS.SHORT 16-bit  
OSS.INT 32-bit 16-bit on older operating systems such as MS-DOS
OSS.LONG 32-bit  
OSS.LONGLONG 64-bit Same as OSS.LONG (32-bit) on platforms that do not support 64 bit INTEGERs

By default, when no subtype constraints are present, the OSS.INT directive is implied. When a subtype constraint is present, the compiler chooses the smallest representation able to carry all required values.

Format

--<OSS.SHORT [absoluteReference]>--
--<OSS.INT [absoluteReference]>--
--<OSS.LONG [absoluteReference]>--
--<OSS.LONGLONG [absoluteReference]>--

When specified globally, only INTEGERs without subtype constraints are affected. absoluteReference refers to an ASN.1 INTEGER type. When specified globally without an absolute reference, OSS.SHORT, OSS.INT, OSS.LONG, and OSS.LONGLONG set the default for all INTEGER types within their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to. They also override any choices that the ASN.1 compiler would have made based on a subtype constraint.

Remarks

When no subtype constraints are present, the OSS.INT directive is implied. When a subtype constraint is present, the compiler chooses the smallest representation able to carry all required values.

Neither the Time-Optimized Encoder/Decoder nor the Lean Encoder/Decoder supports OSS.SHORT, OSS.INT, or OSS.LONG; these directives can be used only with the –soed compiler option. When the -lean or -toed (default) option is used, the ASN.1/C++ compiler generates 32-bit integers, along with 64-bit integers if OSS.LONGLONG is specified.

If a platform does not support 64-bit integers, the OSS.LONG and OSS.LONGLONG directives have the same effect.

Example

--<OSS.SHORT>--
--<OSS.INT Module.GlobalINTInt>--

Module DEFINITIONS ::= BEGIN
    GlobalDefaultInt  ::= INTEGER
    GlobalINTInt      ::= INTEGER
    LONGInt           ::= INTEGER --<LONG>--
    LONGLONGInt       ::= INTEGER --<LONGLONG>--
END

During compilation of the above syntax, the following is generated in the header file:

typedef short int GlobalDefaultInt;

typedef int GlobalINTInt;

typedef long int LONGInt;

typedef LONG_LONG LONGLONGInt;

Although OSS.SHORT set the global default representation for INTEGER types, only GlobalDefaultInt was affected. The representations of the GlobalINTInt, LONGInt, and LONGLONGInt INTEGER types were set by OSS.INT, OSS.LONG, and OSS.LONGLONG respectively.

↩Directives Index


OSS.SHORTENNAMES

Instructs the compiler to omit certain letters from long names so they are less than 31 characters in length in the header file. The directive accommodates maximum name length requirements that exist on some C++ compilers. The OSS ASN.1/C++ Compiler insures that all shortened names are unique by adding _# suffixes, when necessary. By default, name shortening is turned off.

Format

--<OSS.SHORTENNAMES [shortenToLength]>--

This directive can only be specified globally. The optional shortenToLength operand is an integer that specifies the length (16 or greater) that long variable names will be shortened to. When no operands are specified, all long names in the ASN.1 input are shortened to 31 characters.

Example

--<OSS.SHORTENNAMES>--

Mod DEFINITIONS ::= BEGIN
   WeWereTryingToThinkOfaNameButWeCouldNotFindaSuitableOne ::= INTEGER
   NormalName                                              ::= BOOLEAN
END

When the above syntax is ASN.1-compiled, the following is generated in the .h file:

typedef int WWTTTONBWCNFSOn;
typedef ossBoolean NormalName;

See Also

↩Directives Index


OSS.Stylesheet

Gives you more control over the XML stylesheets produced by the ASN.1 compiler. This directive instructs the ASN.1 compiler to generate a separate XML stylesheet with your specified filename for any PDU. By default, unless the -xsl option is specified, stylesheets are not produced. When -xsl is specified, a stylesheet for each input PDU is generated into a separate file with a name derived from that PDU.

Format

--<OSS.Stylesheet [absoluteReference [OptionalNewName.xsl]]>--

absoluteReference refers to any PDU in the input ASN.1 that you want to generate a separate XML stylesheet for. When absoluteReference is not specified, a stylesheet is generated for every PDU in the input.

Remarks

Stylesheets can be used to make the XER output of the encode() method more visually appealing when viewed in a web browser.

You can use the setXmlStylesheet() method of OssControl to have the encode() method generate a reference to your stylesheet in the produced XER encoding.

The OSS.Stylesheet directive can appear anywhere white space is allowed; however, the OSS prefix and an absolute reference is required.

Example

For the following syntax, two separate stylesheet files are generated: StringType.xsl and AnotherNameForInt.xsl. Each contains default browser style information for their respective PDUs.

--<OSS.Stylesheet XModule.StringType>--
--<OSS.Stylesheet XModule.IntType "AnotherNameForInt.xsl">--

XModule DEFINITIONS ::= BEGIN
    StringType ::= UTF8String
    IntType    ::= INTEGER
    studentName ::= <StringType>John H. Doe</StringType>
    studentAge  ::= <IntType>23</IntType>
END

See Also

↩Directives Index


OSS.SUPPRESS

Disables printing of specific informatory and warning messages. This is useful when compiling abstract syntaxes that are known to contain specifications that do not comply with the ASN.1 standard. By default, informatory and warning messages are not suppressed.

Format

--<OSS.SUPPRESS messageID[, messageID ...]>--

messageID identifies the message to be suppressed. It can be the full message identifier, such as A0178W, or only its numeric portion: 178. OSS.SUPPRESS can only be used globally and can take one or more messageIDs.

Example

In the following example, message A0178W warns that the first digit of a number in a module definition should be non-zero:

--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN
    Age ::= INTEGER
    legalAge Age ::= 021
END

Note that the OSS.SUPPRESS directive does not affect the C++ representation. Its only effect is to suppress the following warning message:

"filename.asn", line 4 (Sample): A0178W: The first digit should not be zero unless the number is a single digit.
    legalAge Age ::= 021
                     ^

See Also

↩Directives Index


OSS.UNIVERSALSTRING

Instructs the compiler to represent UTF8String types in C++ as OssUniversalString types. By default, UTF8Strings are represented as OssStrings.

Format

--<OSS.UNIVERSALSTRING [absoluteReference]>--

When specified globally, absoluteReference refers to some UTF8String in the ASN.1 syntax. OSS.UNIVERSALSTRING has no effect if specified globally without an operand. When specified locally, this directive takes no operands and affects only the type it is placed next to.

Example

--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--

Module DEFINITIONS ::= BEGIN

    Default         ::= [1] UTF8String
    TwoByteLocal    ::= [2] UTF8String --<BMPSTRING>--
    FourByteGlobal  ::= [3] UTF8String
    FourByteLocal   ::= [4] UTF8String --<UNIVERSALSTRING>--
END

ASN.1 compiling the above notation generates the following in the header file:

typedef OssString Default;

typedef OssBMPString TwoByteLocal;

typedef OssUniversalString FourByteGlobal;

typedef OssUniversalString FourByteLocal;

See Also

↩Directives Index


OSS.VALUE | OSS.NOVALUE

These directives specify whether an initialized C++ object in the .cpp file and an associated extern statement in the .h file should be generated for each ASN.1 value reference. By default, OSS.VALUE is implied.

Format

--<OSS.VALUE absoluteReference>--
--<OSS.NOVALUE absoluteReference>--

When specified globally, absoluteReference refers to an ASN.1 user-defined type used in a value reference. When specified globally without arguments, these directives set the default for all value references within their scope. When specified locally, no arguments are accepted and the directives affect only the value references they are placed next to.

Example

The following ASN.1 notation shows local and global use of OSS.VALUE and OSS.NOVALUE. The local OSS.VALUE directive overrides the global OSS.NOVALUE directive):

--<OSS.NOVALUE Module.IdInt>--

Module DEFINITIONS ::= BEGIN
        ASCIIStr                       ::= IA5String
        name ASCIIStr                  ::= "John"
        age INTEGER --<SHORT>--        ::= 57
        IdInt                          ::= INTEGER
        idNumAbsent IdInt              ::= 767543
        idNumPresent IdInt --<VALUE>-- ::= 354876
END

When the above syntax is passed through the compiler, the following is generated in the header file:

/* External definitions for named values */
        
extern OSS_PUBLIC const OssString& name;

const short age = 57;

const int idNumPresent = 354876;

In addition, extern constant references are initialized in the .cpp file. Notice that there is neither an extern object nor any initialization for idNumAbsent.

↩Directives Index


This documentation applies to release 6.5 and later of the OSS® ASN.1 Tools for C++.

Copyright © 2017 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C++ is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C++ are available to you.