TOP

ASN.1/C Compiler Directives Reference

Applies to: ASN.1/C v11.3-11.3.1

This section lists the compiler directives and provides a thorough description of their function. The compiler directives on this page are grouped into two categories: standard directives (ASN1.*) and OSS directives (OSS.*).

--<ASN1.ConstraintFunction absoluteReference[functionName]>--

Specifies the name of a function in your application that is used to check a user-defined constraint.

Default Behavior

By default, the name of the constraining function is typereference_fn.

Example

In the following example, the application function isContrOdd() is used to check if the type OddInteger is odd. If no constraining function name is provided, by default, the name of the constraining function is OddInteger_fn.

  --<ASN1.ConstraintFunction Module.OddInteger isConstrOdd>--

  Module DEFINITIONS ::= BEGIN
    OddInteger ::= INTEGER (CONSTRAINED BY {-- odd --} )
  END

Remarks

This directive can be used only with types that have a CONSTRAINED BY clause.

The ASN1.ConstraintFunction directive must be placed before the user-defined type it references.

User-defined constraint-checking functions are generated only when the -userConstraints compiler option is enabled. Note that TOED does not support user-defined constraints.

See Also

OSS.FUNCNAME


--<ASN1.DeferDecoding absoluteReference>--

Changes the C-representation of a specific CHOICE, SEQUENCE, or SET component to the open type structure. The BER and DER decoders will not decode the component; its undecoded form is left in the "encoded" field of the structure.

Default Behavior

By default, all components of CHOICE, SET, or SEQUENCE are decoded with their containing type.

Example

In the following example, the defined type, Type_setComponent_encodable, can be later used in decoding setComponent. This type has a separate PDU tag generated for it.

ASN.1 .h
--<ASN1.DeferDecoding Module.Type.setComponent>--
  
  Module DEFINITIONS ::= BEGIN
     Type ::= SET {
             setComponent INTEGER,
                        b BOOLEAN 
             }
  END
#define          Type_PDU 1
#define          Type_setComponent_encodable_PDU 2

typedef struct Type {
    OpenType        setComponent;  /* Type_setComponent_encodable type */
    ossBoolean      b;
} Type;

typedef int             Type_setComponent_encodable;

Remarks

The ASN1.DeferDecoding directive:

  • Is supported for BER and DER. Do not use it with any other encoding rules.
  • Is supported by the TOED, SOED, and LED.
  • Affects the behavior of the encoder and decoder, but it has no effect on the actual generated encoding.
  • Cannot be applied to ANY or to open type components.

See Also


--<ASN1.HugeInteger absoluteReference>--

Sets a special representation for an INTEGER whose size is not supported by the operating system.

absoluteReference refers to INTEGER types represented using the HugeInteger representation. The HugeInteger representation consists of a structure that contains a pointer to a CHARACTER STRING and a length field.

Default Behavior

By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.

Example

  struct {
    unsigned short  length;
    unsigned char   *value;
  } integerType;

The INTEGER is stored in binary format in the series of octets referenced by the above value field.

ASN.1 .h
 --<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
typedef struct LengthData {
    unsigned char   bit_mask;
#       define      units_present 0x80
    struct _struct1 {
        unsigned short  length;
        unsigned char   *value;
    } lengthOfSolarSystem;
    enum _enum1 {
        mm = 0,
        cm = 1,
        m = 2,
        km = 3,
        lightyears = 4
    } units;  /* units_present not set in bit_mask implies value is mm */
} LengthData;

Remarks

The ASN1.HugeInteger directive requires a parameter and it cannot be applied to all integers.

See Also

OSS.HUGE


--<ASN1.Nickname absoluteReference nickname>--

Provides an alias to a name from an ASN.1 module indicated by absoluteReference that can be used in the generated code.

absoluteReference specifies a name for: a module, type reference, value 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, or an identifier in a named bit or number list.

Default Behavior

By default, the name used in the generated data structures is derived from the ASN.1 input file.

Example

In the following notation, the MTN nickname is used for the type MyTypeName, which is an element of MySequence within MyModule.

  --<ASN1.Nickname MyModule.MySequence.MyTypeName MTN>--

The following example illustrates how to name types and identifiers:

ASN.1 .h
  --<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   
typedef struct Monkey {
    struct Monkey   *next;
    struct Gorilla {
        unsigned char   bit_mask;
#           define      Mandrill_present 0x80
        int             Gibbon;
        struct {
            unsigned int    length;
            unsigned char   *value;
        } Mandrill;  /* optional; set in bit_mask Mandrill_present if present */
    } value;
} *Monkey;

"*" refers to the SEQUENCE type and "1" refers to the first element in the SEQUENCE (the key). In ASN.1:1990 you can omit identifiers for elements of a SEQUENCE, SET, or CHOICE, therefore you can use the number notation to give a name to every component of these constructs. Note that identifiers are mandatory in ASN.1:2021.

The following example shows how to name an item in a NamedNumberList:

ASN.1 .h
  --<ASN1.Nickname Module.E.enum1 " new_enum1">-- 
  --<ASN1.Nickname Module.B.bit1 " new_bit1">-- 
  --<ASN1.Nickname Module.I.int1 " new_int1">-- 
  
  Module DEFINITIONS ::= BEGIN 
     E ::= ENUMERATED {enum1(1), enum2(2)} 
     B ::= BIT STRING {bit1(4), bit2(8)}
     I ::= INTEGER {int1(10), int2(8)} 
  END 

typedef enum E {
     new_enum1 = 1,
    enum2 = 2
} E;

typedef struct B {
    unsigned int    length;  /* number of significant bits */
    unsigned char   *value;
} B;
#define                      new_bit1 0x08
#define                      new_bit1_byte 0
#define                     bit2 0x80
#define                     bit2_byte 1

typedef int             I;
#define                      new_int1 10
#define                     int2 8

Remarks

To rename a type defined with the TYPE NOTATION macro, place the ASN1.Nickname directive after the module where this type is defined.

See Also


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

Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs).

Default Behavior

By default, unreferenced types (user defined types that are not referenced by any other type) are considered PDUs by the compiler, and they can be encoded and decoded as complete units.

Example

In the following example, MyType is treated as a PDU, even if it is referenced in another type definition. Note that the types in the directive must be specified using the absolute reference notation.

  --<ASN1.PDU Module.MyType>--
  
    Module DEFINITIONS ::= BEGIN
       AnotherTypeRef ::= MyType
       MyType ::= SET { 
          b BOOLEAN 
       }
    END

See Also

OSS.PDU


--<ASN1.RealRepresentation binary | decimal | mixed [type1 [, type2, ...]]>--

Enables you to select the representation (binary, decimal, or mixed) for ASN.1 values of type REAL. This directive can be applied to particular REAL types, or can specify a default for all REAL types.

Use decimal to represent REAL as a CHARACTER STRING with the following format: "[-]nnnnn.nnnnn[E[-]nnnnn]".

Use mixed to represent REAL as a struct with both possible representations.

Default Behavior

By default, the REAL type is represented as C double (binary).

The list of affected types is specified using the absolute reference notation. If no type is specified, the ASN1.RealRepresentation directive sets the default representation for REAL types locally, on the module level, or globally, depending on its position.

Example

ASN.1 .h
  --<ASN1.RealRepresentation mixed Module.MyType.a1.b2>--
  Module DEFINITIONS ::= BEGIN
    MyType ::= SEQUENCE {
       a1 SET { b1 INTEGER, b2 REAL},
       a2 REAL
    } 
  END
typedef struct MyType {
    struct {
        int             b1;
        double          b2;
    } a1;
    double          a2;
} MyType;

See Also


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

Instructs the ASN.1 compiler to ignore ASN.1 items. The compiler does not generate code in the .h or .c file for this type. This directive is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.

absoluteReference can refer to: types, values, members of a CHOICE (except empty CHOICE types), OPTIONAL or DEFAULT fields in a SEQUENCE or a SET, information object class, information object that is not included in an information object set, information object set.

Default Behavior

By default, all parts of the ASN.1 input are included in the compiler-generated files.

Example

In the following example, after compiling the syntax, the compiler generates in the header file an empty structure S with an arbitrary placeholder:

ASN.1 .h
  --<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
#define          S_PDU 1

typedef struct S {
    char            placeholder;
} S;

Similar to the following example, if errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the OSS ASN.1 compiler automatically generates the ASN1.Remove directives in the .rmv file. The generated .rmv file can be passed on the command line (before any compiler option) to enable the compiler to automatically remove the types:

  --<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

Additionaly, you can prevent the ASN1.Remove directive from being automatically generated in the .rmv file. To do so, you must correct the ASN.1 specification manually until it compiles correctly.

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

--<ASN1.Remove Mod.s>--
"s" contains values for the component e marked for removal.
--<ASN1.Remove Mod.C>--
"C" references the type Int marked for removal.
--<ASN1.Remove Mod.a>--
"a" contains the reference to the defined value bit marked for removal.
--<ASN1.Remove Mod.A.a>--
The defined type Int for the component A.a is marked for removal.

Remarks

If you assign automatic tags when you remove components, the encodings are still compatible with applications that do not use the ASN1.Remove directive. To make sure an encoded value has not been modified, for encoding rules that depend on the number of possible components (PER, for example), removed components are counted when encoding.

When an ASN.1 item is marked for removal, any references to the item must also be removed.

Other directives applied to ASN.1 items marked for removal have no effect.

The ASN1.Remove applied to fields of a parameterized type removes the fields from each instance of the parameterized type. It is not recommended to apply ASN1.Remove to parameterized types.

Types referenced only by items marked for removal may become PDUs when the references are removed.


--<ASN1.Version 1990 | 1994 | 1997 | 2002 | 2008 | 2015 | 2021 moduleName [{ oid }]>--

Enables you to specify the year of the ASN.1 standard used in a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source.

Default Behavior

By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.

Remarks

When ASN1.Version conflicts with the compiler option -1990 | -2021, the most recent version is used.

See Also


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

Enables you to select from the input ASN.1 schema a subset of types that can be used in your application. In other words, the ASN1.WorkingSet directive enables you to specify, using one directive, all PDUs (the types of the messages to encode and decode). Values, information objects, etc. defined in the working set are also represented in the compiler generated code.

The ASN1.WorkingSet directive replaces the default compiler behavior of assigning PDUs for non-referenced types. You can access certain parts of the ASN.1 specification that are not included in the working set by referencing them from the parts in the working set.

WSName is a working set name required for consistency between the ASN.1/C product and the ASN.1/C++ and ASN.1/Java products; otherwise it is ignored.

absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. If absoluteReference is a module name, this directive has the same effect as the OSS.ROOT directive.

Default Behavior

By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives that are present.

Example

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

  --<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

Remarks

You can extend a set by adding more than one module. For example, both module1 and module14 are included in commonSet:

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

The ASN1.WorkingSet directive does not affect pairs of cross referencing types. In the following example, when using a working set, neither Foo nor Bar will become a PDU:

  Foo ::= SEQUENCE OF Bar
  Bar ::= SEQUENCE {a INTEGER, b Foo}

A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set by itself.

The default determination of the ASN.1 compiler regarding the working set.

By default, the ASN.1 compiler computes the working set by considering four types of directives, in the following order of precedence:

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

Based on the presence and absence of these directives in the input, the ASN.1 compiler assumes one of the following four modes of operation:

Default working set (dws)
All input module names are included in the working set. Additionally, 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 (rd)
Only the last module is included in the working set. In this mode, when the -genDirectives command-line option is specified, no ASN1.WorkingSet or OSS.ROOT directive is included in the .gen file.
Working set (ws)
The ASN.1 compiler includes modules specified by the ASN1.WorkingSet and the OSS.ROOT directive in the working set. Additionally, when the -genDirectives command-line option is specified, all modules from the working set have the ASN1.WorkingSet directive generated in the .gen file, even if they were included via the OSS.ROOT directive. However, 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 mode (r)
Unless you specify the OSS.ROOT directive, no module is included in the working set. Additionally, when you specify the -genDirectives command-line option, 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.

The following table illustrates how the above four modes are used by the ASN.1 compiler (x = present, blank = absent):

Directive Type Types of Directives Present in Input
OSS.ROOT         x x x x x x x         x
Other OSS.* directive     x x   x     x x     x   x x
ASN1.WorkingSet             x x x x   x x x x  
Other ASN1.* directive x     x       x x   x     x x x
ASN.1 Compiler Mode dws rd rd rd r r ws ws ws ws ws ws ws ws ws ws

See Also

OSS.ROOT


--<OSS.ARRAY [[absoluteReference] | [asn1Type [, asn1type]...]]>--

Instructs the compiler to represent SET OF, SEQUENCE OF, and OBJECT IDENTIFIER types as arrays of values with a count field.

Default Behavior

By default, SET OF, and SEQUENCE OF types are represented as single linked lists, and OBJECT IDENTIFIERs are represented in structures with CHARACTER STRING pointers and length fields.

absoluteReference can be used to affect a particular instance of a type.

asn1Type can take the values of: SET OF, SEQUENCE OF, or OBJECT IDENTIFIER.

When used locally, the OSS.ARRAY directive does not accept operands and affects only the type placed next to it.

Example

The following example shows both the local and global use of the OSS.ARRAY directive.

BooleanArray, RealArray, and IntArray are represented as arrays by three different OSS.ARRAY directives. RealLinkedList defaults to the linked list representation because no OSS.ARRAY directive is applied to it:

  --<OSS.ARRAY SET OF>--
  --<OSS.ARRAY ArraySample.RealArray>--
  ArraySample DEFINITIONS ::= BEGIN
     IntArray       ::= SEQUENCE SIZE (5) --<ARRAY>-- OF INTEGER
     RealArray      ::= SEQUENCE SIZE (5) OF REAL
     RealLinkedList ::= SEQUENCE SIZE (5) OF REAL
     BooleanArray   ::= SET      SIZE (5) OF BOOLEAN
  END

Remarks

The OSS.ARRAY directive is not supported when the -helperNames option is specified.

See Also


--<OSS.ASN1VER absoluteReference 1990 | 1994 | 1997 | 2002 | 2008 | 2015 | 2021>--

Specifies the version of the ASN.1 standard for the input files.

Default Behavior

By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.

Example

The following example shows how to allow unnamed elements to be used in a SEQUENCE:

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

See Also


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

Enables representation of ASN.1 UTF8String types in C as unbounded arrays of two-byte characters, the same as the default representation of the ASN.1 BMPString types.

absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String. If used without arguments, this directive can only operate as a local directive.

Default Behavior

By default, the ASN.1 UTF8String type is represented as a NULL terminating CHARACTER STRING.

Example

In the following example, TwoByteGlobal and TwoByteLocal are set to the BMPString representation.

Note that the length fields in TwoByteLocal and TwoByteGlobal specify the number of characters in the string and not the number of bytes.

ASN.1 .h
  --<OSS.BMPSTRING Module.TwoByteGlobal>--
  Module DEFINITIONS ::= BEGIN
     Nullterm         ::= UTF8String
     TwoByteLocal     ::= UTF8String --<BMPSTRING>--
     TwoByteGlobal    ::= UTF8String
  END
typedef unsigned char   *Nullterm;

typedef struct TwoByteLocal {
    unsigned int    length;
    unsigned short  *value;
} TwoByteLocal;

typedef struct TwoByteGlobal {
    unsigned int    length;
    unsigned short  *value;
} TwoByteGlobal;

Remarks

The BMPString and UniversalString representations of UTF8String are incompatible with the OSS.OBJHANDLE (or the OSS.NOCOPY) directive.

With the BMPString and UniversalString representations, character data is automatically converted to UTF-8 format before encoding. Also, it is converted from UTF-8 format after decoding.

No attempt is made at run time to ensure that the generated C variable contains a valid UTF-8 converted CHARACTER STRING. Data octets are passed to the encoder unchanged. Also, when decoding, unmodified data octets are used to fill the C variable. Before you call the encoder, you must make sure the UTF-8 data is valid and then, you must interpret the UTF-8 data received from the decoder.

See Also


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

Instructs the ASN.1 compiler to place a user-defined comment at the beginning of the .c and .h files generated by the compiler.

commentText is the comment that appears at the beginning of the generated files.

Default Behavior

By default, no user-defined comment is generated.

Example

For the following input:

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

The compiler generates the following header file with comments:

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

Remarks

Comments from ASN.1 files are transferred by the compiler to the header file as well.

OSS.COMMENT can be specified only 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 rest will be ignored.


--<OSS.CommentPreservation [ON | OFF]>--

Controls the transfer of ASN.1 comments to the generated header file. Using this directive, you can enable comment transfer for certain sections of your ASN.1 source and disable it for other sections.

Default Behavior

By default, ASN.1 comments are transferred to the generated header file.

Remarks

This directive affects all lines of ASN.1 source that follow it until another OSS.CommentPreservation directive is encountered.

The OSS.CommentPreservation OFF is included as the first directive of any:


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

The OSS.DataCallback compiler directive associates a field of a SEQUENCE or SET type, an alternative of a CHOICE type, or an element of a SEQUENCE OF or a SET OF type with your callback function. This directive is useful when using partial decoding.

Remarks

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.

FunctionName is the user-defined name for the callback function.

When specified locally, the OSS.DataCallback directive must be placed next to the field definition. For example:

age INTEGER(1..100) --<DataCallback "FunctionName">--,

It's possible for a named type to appear more than once in a PDU. When an OSS.DataCallback directive is applied to such a field, the decoder will call the same callback function for each occurrence. The callback, however, cannot differentiate a call for one field from a call for the other since they are both associated with the same function. To discern the difference, consider the OSS.InfoCallback directive.

See Also


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

Specify the representations for the ASN.1 REAL type.

Default Behavior

By default, REAL is represented as a double.

Example

OSS.MIXED sets the following representation:

   enum MixedReal_kind {BINARY, DECIMAL};
   typedef struct {
      enum MixedReal_kind kind;
         union {
            double base2;
            char  *base10;
         } u;
      } MixedReal;

By constraining the base of the REAL type to 2, the binary representation is represented as a double by default. By constraining the base to 10, the decimal representation is represented as null-terminated char* by default.

ASN.1 .h
  --<OSS.DECIMAL>--
  
  Module DEFINITIONS ::= BEGIN
     Decimal    ::= REAL (WITH COMPONENTS {..., base (10)})
     Binary     ::= REAL (WITH COMPONENTS {..., base (2)})
     BinaryAlso ::= REAL
     Mixed      ::= REAL --<MIXED>--
  END
typedef char            *Decimal;

typedef char            *Binary;

typedef char            *BinaryAlso;

typedef MixedReal       Mixed;

The global directive --<OSS.DECIMAL>-- overrides the default representation of the base 2 constraint. However, it does not take precedence over the local --<MIXED>-- directive.

ASN.1 .h
  --<OSS.DECIMAL>--
  
  Module DEFINITIONS ::= BEGIN
     Decimal     ::= REAL (WITH COMPONENTS {..., base (10)})
     DecimalAlso ::= REAL (WITH COMPONENTS {..., base (2)})
     DecimalToo  ::= REAL
     Mixed       ::= REAL --<MIXED>--
  END
typedef char            *Decimal;

typedef char            *DecimalAlso;

typedef char            *DecimalToo;

typedef MixedReal       Mixed;

Remarks

OSS.DECIMAL sets the representation as a null-terminated CHARACTER STRING with the following format:

"[-]nnnnn.nnnnn[E[-]nnnnn]".

Note that the string pointer can point to the OSS_PLUS_INFINITY, OSS_MINUS_INFINITY , and OSS_NOT_A_NUMBER variables.

Important Note

double is provided as the default representation. However, the ASN.1 standard 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 done to avoid losing precision in conversions to and from their floating point representation.

To ensure that no precision is lost, you can constrain the type REAL to base 2 or base 10. To ensure that the C representation can encode and decode without conversion, you can use the MIXED directive.

The -helperNames option overrides the OSS.MIXED directive.

See Also


--<OSS.DECODEONLY [absoluteReference]>--
--<OSS.ENCODEONLY [absoluteReference]>--

Instructs the compiler to generate only encoder or decoder routines, when using the Time-Optimized Encoder/Decoder. The OSS.DECODEONLY and OSS.ENCODEONLY directives can be applied to a named PDU type. These directives have no effect when the type is not used as a PDU (for example, if it is the type of a SEQUENCE or SET field). The compiler issues a warning in this case.

The OSS.DECODEONLY and OSS.ENCODEONLY directives have been deprecated, use the OSS.NODECODE | OSS.NOENCODE directive instead.

Default Behavior

By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.

Remarks

When you use the Space-Optimized Encoder and Decoder, this directive has no effect because the information generated in the control table is used for encoding and decoding.


--<OSS.DefineName absoluteReference ["]userDefinedName["]>--

Enables you to specify names for generated #defined components within CHOICE, SEQUENCE, or SET structures.

absoluteReference refers to a particular field in a CHOICE, SEQUENCE, or a SET. It is mandatory.

userDefinedName specifies the name to be assigned. It is mandatory.

Default Behavior

By default, the compiler generates names for #defined components.

Example

ASN.1 .h
  --<OSS.DefineName Module.Type.field1 myName>--
  Module DEFINITIONS ::= BEGIN
     Type ::= CHOICE {
        field1  BOOLEAN,
        field2  REAL
     }
  END
typedef struct Type {
    unsigned short  choice;
#       define      myName_chosen 1
#       define      field2_chosen 2
    union {
        ossBoolean      field1;  /* to choose, set choice to myName_chosen */
        double          field2;  /* to choose, set choice to field2_chosen */
    } u;
} Type;

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

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

Default Behavior

By default, the compiler uses the definite length form. Applying these directives to non-PDU types has no effect.

Example

In the following example, ByteStream is encoded using the indefinite length form because no other directives are applied to it. DataPacket is encoded using the definite length form because the local OSS.DEFINITE directive is present:

  --<OSS.INDEFINITE>--
  Module DEFINITIONS ::= BEGIN
     ByteStream ::= OCTET STRING
     DataPacket ::= SEQUENCE {name IA5String, id INTEGER } --<DEFINITE>--
  END

Remarks

These directives do not affect the generated header file.

Except for the Time-Optimized BER encoder and the Lean BER encoder, all provided decoders (Space-Optimized/Lean/Time-Optimized) support the indefinite length form of encoding.


--<OSS.DLINKED [[absoluteReference] | [SET OF [, SEQUENCE OF]]]>-- 

Instructs the compiler to represent SET OF and SEQUENCE OF types as doubly-linked lists of values.

Default Behavior

By default, SET OF and SEQUENCE OF types are represented as singly-linked lists of values.

Example

In the following example, IndDL and StrDL are represented as doubly-linked lists:

ASN.1 .h
  --<OSS.DLINKED SET OF>--
  
  Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
     IntDL ::= [1] SET SIZE (5) OF INTEGER
     IntAR ::= [2] SET SIZE (15) --<ARRAY>-- OF INTEGER
     StrDL ::= [3] SET OF IA5String
  END
typedef struct IntDL {
    struct IntDL    *next;
    struct IntDL    *prev;
    int             value;
} *IntDL;

typedef struct IntAR {
    unsigned short  count;
    int             value[15];
} IntAR;

typedef struct StrDL {
    struct StrDL    *next;
    struct StrDL    *prev;
    char            *value;
} *StrDL;

Remarks

The -helperNames option overrides the OSS.DLINKED directive.

See Also


--<OSS.DLINKED-PLUS [[absoluteReference] | [SET OF [, SEQUENCE OF]]]>--

Instructs the compiler to represent SET OF and SEQUENCE OF types as doubly-linked-plus lists of nodes. Doubly-linked-plus representations are similar to doubly-linked representations, except for the extra structure for keeping pointers to the head and tail nodes, as well as the number of nodes in the list.

Default Behavior

By default, when the -helperNames option is specified or implied, SET OF and SEQUENCE OF types with elements whose types are structured or pointered, are represented as a doubly-linked-plus list of values. SET OF and SEQUENCE OF types with elements whose types are not structured and not pointered (INTEGER without HUGE, REAL with DOUBLE, BOOLEAN, NULL, and ENUMERATED, for example) are represented as unbounded structures.

Remarks

The OSS.HelperListAPI directive overrides the OSS.DLINKED-PLUS directive and uses instead the DLINKED-PLUS representation.

See Also


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

Instructs the compiler to generate a separate DTD (XML Data Type Definition) with the filename (NewName.dtd) specified by you, for any particular PDU referenced by absoluteReference.

Default Behavior

By default, no DTDs are produced by the ASN.1 compiler.

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

Remarks

When the -dtd option is specified, a data type definition for each PDU in the input is generated in a separate file whose name is derived from the PDU name.

To make the XER output produced by ossEncode() editable in an XML tool that is not specific to ASN.1, you can use data type definitions.

To enable the ossEncode() function to generate a reference to your DTD in the XER encoding, use the ossSetXmlDTD() API function.

See Also

-dtd


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

Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures.

Default Behavior

By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal form and no typedef is generated.

Example

In the following example, a separate PDU tag is generated for the type marked with the OSS.ENCODABLE directive. Data is represented as open type and a typedef is created for the associated OCTET STRING:

ASN.1 .h
  A DEFINITIONS ::= BEGIN
     A ::= SEQUENCE {
         id   [0] INTEGER,
         data [1] OCTET STRING --<ENCODABLE>--
     }
  END
#define          A_PDU 1
#define          A_data_encodable_PDU 2

typedef struct A {
    int             id;
    OpenType        data;  /* A_data_encodable type */
} A;

typedef struct A_data_encodable {
    unsigned int    length;
    unsigned char   *value;
} A_data_encodable;

OpenType is defined as follows in the asn1hdr.h file:

  typedef struct {
  int            pduNum;
  long           length;       /* length of encoded */
  void          *encoded;
  void          *decoded;
  
  #ifdef OSS_OPENTYPE_HAS_USERFIELD
  void          *userField;
  
  #endif
  } OpenType;

The userField can carry any type of information. This field is generated only when the -extendOpenType compiler option is specified and is ignored by the encoder/decoder.

Remarks

When applied to a component of a CHOICE, SEQUENCE, or a SET, it compels the compiler to represent the component as open type. The type that would normally have been generated as a field in the struct is generated as a typedef and can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded.

The OSS.ENCODABLE directive is not supported for tagged types. For tagged types, you can use the ASN1.DeferDecoding directive.

This directive is not supported by PER, OER, XER or E-XER.

See Also

ASN1.DeferDecoding


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

Instructs the compiler to encode BOOLEAN types as numeric values of 0 and 1 instead of "true" and "false", when GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instructions are present. This is especially useful for reducing the size of the encoded XML documents and for exchanging information with decoders that understand only numeric BOOLEAN values.

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

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

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

Remarks

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

  • All elements of a SET or SEQUENCE whose tags are not defined in the ASN.1 compiler input are ignored.
  • 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 Named bits are encountered in the input stream, the decoder ignores them.

The 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.


--<OSS.ExtensibleUseType>--

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

Default Behavior

By default, data described above is decoded as data matching the first alternative, and all unknown elements or attributes are ignored. In the presence of the OSS.ExtensibleUseType directive, the decoder treats such data as unknown extension rather than a value of the first CHOICE alternative.

Example

  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

The following example shows different scenarios of decoding the XML document:

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

Without ExtensibleUseType, unknown content is skipped:

  value T ::= base : {
     i 1

With ExtensibleUseType and without -relaySafe, the XML subtree is skipped:

  value T ::= <unknown>

The decoded value contains the following data:

  choice == 0

With ExtensibleUseType and -relaySafe, the XML subtree is relayed:

  value T ::= <unknown>

The decoded 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>
 

Remarks

If the input ASN.1 schema is compiled with the -relaySafe option, the XML sub-element that corresponds to an unknown extension is preserved in the special unknown alternative field and can be safely relayed to other parties.

In the absence of the -relaySafe option, the XML sub-element is skipped and the presence of the decoded CHOICE type indicates the use of an unknown alternative.

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

See Also

OSS.SelfCompleteWildcard


--<OSS.ExtractType absoluteReference>--
--<OSS.InlineType absoluteReference>--

Instructs the compiler to code a nested structure either using a typedef defined outside the structure or inline within the structure.

absoluteReference is mandatory and must refer to a CHOICE, SEQUENCE, SEQUENCE OF, SET, or SET OF type that is affected by these directives.

Default Behavior

By default, for identical nested structures, the compiler generates a shared independent typedef. Unique nested structures, by default, are coded inline in the header file.

Example

In the following example, Type1 has an inline nested structure, Type2 and Type3 have typedef structures:

ASN.1 .h
  --<OSS.ExtractType Mod.Type1.nested>--
  
  Mod DEFINITIONS ::= BEGIN
     Type1 ::= SET {
     nested SET OF INTEGER
     }
  END
typedef struct _setof1 {
    struct _setof1  *next;
    int             value;
} *_setof1;

typedef struct Type1 {
    struct _setof1  *nested;
} Type1;

 --<OSS.InlineType Mod.Type1.1>--
 
 Mod DEFINITIONS ::= BEGIN
    Type1 ::= SET {SET OF INTEGER}
    Type2 ::= SET {SET OF INTEGER}
    Type3 ::= SET {SET OF INTEGER}
 END
typedef struct Type1 {
    struct _setof1 {
        struct _setof1  *next;
        int             value;
    } *setOf;
} Type1;

typedef struct _setof2 {
    struct _setof2  *next;
    int             value;
} *_setof2;

typedef struct Type2 {
    struct _setof2  *setOf;
} Type2;

typedef struct Type3 {
    struct _setof2  *setOf;
} Type3;

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

Instructs the ASN.1 compiler to use the specified newName for a value, field in a structure, or user-defined type.

newName must be a valid C variable name (the compiler modifies other derived names if they conflict with the specified one).

Default Behavior

By default, names are derived from the ASN.1 definition.

Example

ASN.1 .h
 --<OSS.FIELDNAME MyMo.Item.available inStock>--
 --<OSS.TYPENAME MyMo.Name Title>--
 
 MyMo DEFINITIONS ::= BEGIN
    Name ::= IA5String
    Item ::= SEQUENCE {
       available BOOLEAN,
       count     INTEGER
    }
 END
typedef char            *Title;

typedef struct Item {
    ossBoolean      inStock;
    int             count;
} Item;

See Also

ASN1.Nickname


--<OSS.FLOAT [absoluteReference]>--
--<OSS.DOUBLE [absoluteReference]>--

Specifies the C data type used to represent the ASN.1 REAL type.

Default Behavior

By default, the ASN.1 REAL type is represented using the C double data type.

Example

In the following example, the OSS.FLOAT directive is used, therefore the local OSS.DOUBLE directive overrides the global default set:

ASN.1 .h
 --<OSS.FLOAT>--
 --<OSS.DOUBLE Module.DataFolder.b>--
 
 Module DEFINITIONS ::= BEGIN
    DataFolder ::= SEQUENCE {
       a REAL --<DOUBLE>--,
       b REAL,
       c REAL
    }
  END
typedef struct DataFolder {
    double          a;
    double          b;
    float           c;
} DataFolder;

Remarks

When the -helperNames option is specified, the OSS.FLOAT directive is not supported.

See Also


--<OSS.FUNCNAME [absoluteReference] ["]FunctionName["]>--

Specifies a name for a function that verifies the user-defined constraints.

Default Behavior

By default, the name of the C function (that the encoder and decoder calls before encoding and after decoding a user-constrained value) is derived from the name of the type or identifier with which the constraint is associated. For example:

   Y ::= INTEGER (CONSTRAINED BY { -- Must be a power of 2 -- })

For the above syntax, the default constraint-checking function name is:

   Y_fn

Example

ASN.1 .h
  --<OSS.FUNCNAME Module.DataCard.c "checkForPowerOf2">--
  
  Module DEFINITIONS ::= BEGIN
     DataCard ::= SEQUENCE {
        a BOOLEAN,
        b BOOLEAN,
        c INTEGER (CONSTRAINED BY { -- Must be a power of 2 --})
     }
   END
typedef struct DataCard {
    ossBoolean      a;
    ossBoolean      b;
    int             c; /* Must be a power of 2 */
} DataCard;

/* checkForPowerOf2 is user-defined constraint function for ASN.1 item * Module.DataCard.c */
extern int DLL_ENTRY checkForPowerOf2(struct ossGlobal *, int *, void **);

User-defined constraint-checking functions are only generated when the -userConstraints compiler option is specified.

User-defined constraints are not supported by the TOED.


See Also

ASN1.ConstraintFunction

--<OSS.HeaderName moduleReference "headerFilename">--

Enables you to specify a name for the header file generated for a particular ASN.1 module. This directive is used with the split-headers mode of the ASN.1 compiler.

Default Behavior

By default, the names of these header files are derived from their module references.

Example

  --<OSS.HeaderName MyModule "myInteger.h">-- 
  
  MyModule DEFINITIONS ::= BEGIN
     A ::= INTEGER
  END

See Also


--<OSS.HelperListAPI [[absoluteReference] | [asn1Type [, asn1Type] ...]]>--
--<OSS.NoHelperListAPI [[absoluteReference] | [asn1Type [, asn1Type] ...]]>--

Controls the generation of helper list APIs when the -helperNames option is specified, and affects types with the DLINKED-PLUS representation.

Example

In the the following example, the ASN.1 specification is compiled with -helperNames option. The helper list API functions are generated only for Quest_answers:

ASN.1 .h
  --<OSS.DLINKED-PLUS M.Quest.answers>--
  --<OSS.HelperListAPI M.Quest.answers>--
  
  M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
     Quest ::= SEQUENCE {
        questions SEQUENCE OF IA5String,
        answers SEQUENCE OF BOOLEAN
     }
  END
typedef struct Quest {
    struct Quest_questions *questions;
    struct Quest_answers *answers;
} Quest;
...

typedef struct Quest_answers {
    struct Quest_answers_node *head;
    struct Quest_answers_node *tail;
    unsigned int    count;
} Quest_answers;

typedef struct Quest_answers_node {
    struct Quest_answers_node *next;
    struct Quest_answers_node *prev;
    ossBoolean      value;
} Quest_answers_node;

/* ************************************************** */
/* Helper List API functions for 'Quest_answers' list */
/* ************************************************** */

/* creates an empty list */
struct Quest_answers * DLL_ENTRY oss_Quest_answers(OssGlobal *_world);
...

/* unlinks and frees node of list */
   ossBoolean DLL_ENTRY oss_Quest_answers_unlink(OssGlobal *_world, struct Quest_answers * _list, Quest_answers_node * _node);

Remarks

The -helperListAPI | -noHelperListAPI compiler options override these directives.

See Also

OSS.DLINKED-PLUS


--<OSS.HelperMacro [absoluteReference]>--
--<OSS.NoHelperMacro [absoluteReference]>--

Instructs the ASN.1 compiler whether to generate helper macros for the referenced types, when the -helperNames compiler option is specified.

Example

ASN.1 .h
  --<OSS.HelperMacro>--
  --<OSS.NoHelperMacro M.Item.size>--
  
  M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
     Size ::= SEQUENCE {
        length INTEGER,
        width INTEGER,
        height INTEGER
     }
     Item ::= SEQUENCE {
        color IA5String,
        size Size
     }
  END
typedef struct Size {
    int             length;
    int             width;
    int             height;
} Size;
...

typedef struct Item {
    char            *color;
    Size            size;
} Item;
/* allocates memory for Item_PDU */
#define oss_Item_new_pdu(world) (Item *)ossGetInitializedMemory(world, sizeof(Item))

/* gets "color" field value */
#define oss_Item_color_get(inp)  (inp)->color

/* sets "color" field value */
#define oss_Item_color_set(outp, color_)  (outp)->color = (color_)

/* allocates memory for a string of given length */
#define oss_Item_color_new(world, length_) oss__CharStr_new(world, length_)

/* allocates memory and returns a copy of an input string */
#define oss_Item_color_copy(world, value_) oss__CharStr_copy(world, value_)

Remarks

The -helperMacros | -noHelperMacros compiler options override these directives.

See Also

-helperNames


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

Replaces the default INTEGER representation to accommodate large INTEGERs.

Example

ASN.1 .h
  HugeInt DEFINITIONS ::= BEGIN
     A ::= INTEGER --<HUGE>--
  END
typedef struct A {
   unsigned short length;
   unsigned char *value;
} A; 

Remarks

When specified globally, the absoluteReference operand should refer to an ASN.1 INTEGER type that will be represented using the HugeInteger representation. Also, when OSS.HUGE is applied globally with no parameters, it applies to all integers in the schema.

When specified locally, the OSS.HUGE directive takes no operands and affects the type that it is placed next to.

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

Value constraints applied to INTEGER types with the OSS.HUGE directive cannot exceed 64bit. Otherwise, the ASN.1 compiler issues error messages.

See Also

ASN1.HugeInteger


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

Specifies the name of one or more configuration files that you can add to the ASN.1 input. This is useful when defining different sets of compiler directives that can be included or excluded, depending on the application.

Default Behavior

By default, no configuration files are inserted into the ASN.1 input.

Example

In the following example, directives from file1.cfg and file2.cgf are inserted at the location of the OSS.INCLUDES directive:

   --<OSS.INCLUDES "file1.cfg", "file2.cfg" >--
   Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
   ...

Remarks

This directive can be specified only globally and must have at least one configuration filename as operand. The configuration file must contain global directives.

Directives obtained by specifying the OSS.INCLUDES directive can be used only on a single ASN.1 module definition and override any conflicting directives in the asn1dflt file.


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

This directive is provided for those cases where an OSS.DataCallback directive is applied to a type which occurs in multiple locations in a message.

Example

For this definition:

M DEFINITIONS AUTOMATIC TAGS ::= BEGIN

PackageInfo ::= SEQUENCE {
    from         Address,
    to           Address,
    posted       DATE 
}

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

a directive like this

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

would cause myZipcode() to be called for both PackageInfo.from.zipcode and PackageInfo.to.zipcode, but myZipcode() wouldn't be able to differentiate the two fields. OSS.InfoCallback offers a way. By employing:

--<OSS.InfoCallback M.PackageInfo.from "fromAddress">--

you instruct the compiler to generate a prototype for the fromAddress() callback function. This function, which you provide, is called by the decoder twice, once before starting the partial decoding of the from field and again after finishing its decoding.

See Also


--<OSS.JEREncodeFunction absoluteReference "yourJEREncodeFunctionName" [parameterAbsoluteReference]>--

Enables you to specify the data formatter function for encoding ASN.1 types using the JSON Encoding Rules (JER). The function that you provide is called each time the JER encoder adds the encoding of the type affected by this directive to the output buffer; instead of generating the JSON encoding for the type, the encoder passes its C value to the user-defined function and expects the encoded value to be returned.

parameterAbsoluteReference specifies an additional ASN.1 type to be used as a parameter of the encoding function; the encoder submits the last instance of the parameter type found in the input PDU value to the user-provided function each time it is called.

yourJEREncodeFunctionName has the following prototype:

int DLL_ENTRY yourJEREncodeFunctionName(
struct ossGlobal *world, yourType *in, [yourParameter *param,] OssBuf *out, OssSafeMallocp safemalloc);

Remarks

When the OSS.JEREncodeFunction directive is applied to an ASN.1 type, the values of this type are not encoded according to the ITU-T X.697/ISO 8825-xx standard; instead, each value is provided to the formatter function for encoding according to custom application requirements.

Also, you can provide an optional C value for the function parameter (NULL is provided when no parameter values are found in the input PDU when calling the JER encoding function). The function must populate the length and value fields of the OssBuf *out structure and return success (one of the values OSS_FORMAT_OK_STATIC or OSS_FORMAT_OK) or an error code (any positive integer).

OSS_FORMAT_OK_STATIC instructs the encoder not to free the memory referenced by the value field of the OssBuf (it is assumed that this memory is not allocated on the heap).

OSS_FORMAT_OK instructs the encoder to free the memory. The JER encoding function can dynamically allocate the output memory only by calling the safemalloc function.

Note that the OSS.JEREncodeFunction directive is available only when the -soed or -toed compiler option is specified.


--<OSS.LENGTHSIZE SHORT | INT | LONG>--

Changes the default representation for the count and length fields of the structures generated by the ASN.1 compiler.

The OSS.LENGTHSIZE directive does not take an absolute reference, but has a global effect.

Default Behavior

By default, when no size constraints are specified, the count and length fields are either short (for the OBJECT IDENTIFIER type) or int (for all other types). When a size constraint is present, these fields use the smallest representation that can accommodate all the required values.

Example

In the following example, the short data type for the length field is used instead of (the default) int:

ASN.1 .h
  --<OSS.LENGTHSIZE SHORT>--
  
  Module DEFINITIONS ::= BEGIN
     A ::= OCTET STRING
  END
typedef struct A {
    unsigned short  length;
    unsigned char   *value;
} A;

Remarks

Size constraints override the OSS.LENGTHSIZE directive.

In some cases, the operand LONG has the same effect as the operand INT.

OSS.LENGTHSIZE is not supported when the -helperNames option is specified.


--<OSS.LINKED [[absoluteReference] | [asn1Type [, asn1Type]...]]>--

Instructs the compiler to represent SET OF, SEQUENCE OF, or OBJECT IDENTIFIER types as singly-linked lists of values. For SET OF and SEQUENCE OF, this directive is useful when their default representation is modified by other directives.

Example

ASN.1 .h
  --<OSS.DLINKED SET OF>--
  --<OSS.LINKED Module.InfoCards>--
  
  Module DEFINITIONS ::= BEGIN
     DataCards ::= SET OF INTEGER
     InfoCards ::= SET SIZE (18) OF IA5String
  END
typedef struct DataCards {
    struct DataCards *next;
    struct DataCards *prev;
    int             value;
} *DataCards;

typedef struct InfoCards {
    struct InfoCards *next;
    char            *value;
} *InfoCards;

Remarks

The -helperNames compiler option overrides the OSS.LINKED directive.

See Also


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

Identifies types or components for which constraint checking should be disabled. The directive disables all constraint checking for the type, including checking of the default permitted alphabet for CHARACTER STRING types. For ENUMERATED types, it disables the subtype constraints, but it does not disable checking for valid enumerators.

Default Behavior

By default, constraint checking is enabled.

Example

For the following example, if -constraint is not specified, all constraints for the type S are disabled. If -userConstraints is specified, constraint checking of user-constraints is enabled.

 --<OSS.NoConstrain Module.S>--
 
 Module DEFINITIONS ::= BEGIN
    S ::= INTEGER (1..10 | 300) (CONSTRAINED BY { })
 END
 

In the following 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 the type is composed of types marked with OSS.NoConstrain.

 --<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, although the -constraint option is specified, the automatic encoding and decoding is not performed at run time:

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

Remarks

The OSS.NoConstrain directive cannot be specified locally. Also, it 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.

If -userConstraints is used with OSS.NoConstrain, all constraints except for user-constraints are disabled for the specified type or field.

See Also


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

Informs the ASN.1 compiler to treat items marked with the ASN.1 DEFAULT tag as items marked with the OPTIONAL tag.

Default Behavior

Types marked with the DEFAULT tag use the specified default value when absent from the encoding.

Remarks

When specified globally without absoluteReference , the OSS.NODEFAULTVALUE directive affects all types marked with the DEFAULT keyword.

Example

ASN.1 .h
  --<OSS.NODEFAULTVALUE Module.DataCard.a>--
  
  Module DEFINITIONS ::= BEGIN
     DataCard ::= SEQUENCE {
        a [0] BOOLEAN DEFAULT TRUE,
        b [1] BOOLEAN DEFAULT TRUE,
        c [2] BOOLEAN
     }
  END
typedef struct DataCard {
    unsigned char   bit_mask;
#       define      a_present 0x80
#       define      b_present 0x40
    ossBoolean      a;  /* optional; set in bit_mask a_present if present */
    ossBoolean      b;  /* b_present not set in bit_mask implies value is
                         * TRUE */
    ossBoolean      c;
} DataCard;

--<OSS.NOENCODE [absoluteReference]>-- | --<OSS.NODECODE [absoluteReference]>--

Instructs the compiler to not generate decoder or encoder routines for the operand of the directive when using the Time-Optimized Encoder/Decoder.

The OSS.NOENCODE and OSS.NODECODE compiler directives reduce the amount of generated code. The directives can be applied either to a named PDU type or to a SEQUENCE or SET field or a CHOICE alternative, as follows:

  • When OSS.NOENCODE or OSS.NODECODE is applied to a named PDU type, the compiler will not generate the PDU encoder or decoder for the type. In this case, the directives can be used instead of the OSS.ENCODEONLY and OSS.DECODEONLY directives, which have been deprecated. Note that when the type is not used as a PDU type (for example, it is used as a SEQUENCE or SET field type), the directives have no effect on the named type (a warning is issued).
  • When OSS.NOENCODE or OSS.NODECODE is applied to a SEQUENCE or SET field, the field must be an OPTIONAL (not a DEFAULT) root field or an extension addition.

Considerations when using the OSS.NOENCODE directive

  1. The fields marked with OSS.NOENCODE are not encoded.
  2. The encoder reports an error when the value to be encoded contains a CHOICE alternative marked with OSS.NOENCODE.
  3. OSS.NOENCODE can be applied to an OPTIONAL (not a DEFAULT) root field or to an extension field. When it is applied to extension fields, the following restrictions guarantee that the resulting encoding is valid:
    • When the directive is applied to a mandatory extension field, it must also be applied to all subsequent extension fields.
    • When the directive is applied to a mandatory field of an extension group, it must also be applied to all fields in the group and to all subsequent extension fields.

NOTES:

  1. Unless the directive satisfies the conditions mentioned in the third case, the CXER encoder ignores the OSS.NOENCODE directive applied to DEFAULT extensions because default fields are always encoded by CXER.
  2. The AVN encoder ignores the OSS.NOENCODE directive unless it is applied to a top-level PDU type.

Considerations when using the OSS.NODECODE directive

  1. OSS.NODECODE can be applied either to an OPTIONAL (not a DEFAULT) root field or to an extension addition.
  2. The fields marked with OSS.NODECODE are not decoded.
  3. The decoder reports an error if it encounters a CHOICE alternative marked with the OSS.NODECODE directive. Depending on the presence of the -compactNoDecode option, the compiler can generate two versions of the decoding functions:
    • A compact version that reports an error when a field marked with the OSS.NODECODE directive is present in the input encoding (except for open type fields and extension additions, because the decoder easily skips these fields).
    • A more permissive but less compact version that can skip any field marked by the OSS.NODECODE directive.

The following restriction applies to the compact version: the OSS.NODECODE directive must be applied either to all fields of an extension group or to none of the fields of an extension group.

Default Behavior

By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.

Remarks

When you use the Space-Optimized Encoder and Decoder, the OSS.NOENCODE and OSS.NODECODE directives have no effect.


--<OSS.NonUnionOpenType absoluteReference>--

Generates a predefined structure OpenType as the C representation for the ASN.1 open type, where the decoded value is represented as the untyped pointer.

Default Behavior

By default, in the C representation for an ASN.1 open type, the decoded value is represented as a union of PDU type alternatives.


--<OSS.NULLTERM [absoluteReference] >--
--<OSS.NULLTERM asn1Type[, asn1Type...]>--

Instruct the compiler to represent CHARACTER STRING, GeneralizedTime, and UTCTime types in the target language as null-terminated variable length strings.

asn1Type provides the names of the ASN.1 built-in CHARACTER STRING types. The argument cannot be used for time types.

Default Behavior

By default, string types (GeneralString, GraphicString, IA5String, NumericString, PrintableString, TeletexString, UTF8String, VideotexString, and VisibleString) and TIME type are represented as null-terminated strings. Also, multi-octet strings like BMPString and UniversalString typically contain embedded NULLs. The OSS.NULLTERM directive has no effect on these types.

Example

ASN.1 .h
  --<OSS.NULLTERM PrintableString>--
  
     NameDefault ::= PrintableString
typedef char *NameDefault;
 --<OSS.NULLTERM Sample1.TimeNULL>--
 
    TimeDefault ::= GeneralizedTime
    TimeNULL    ::= GeneralizedTime 
 typedef GeneralizedTime TimeDefault;
 typedef char *TimeNULL;

Remarks

If the -helperNames option is not specified, time types (GeneralizedTime and UTCTime) by default, are represented as structures of INTEGERs.

If -helperNamesis specified, time types are represented as NULLTERM. The OSS.NULLTERM directive changes the representation to a string.

When NULLTERM is specified and a size constraint subtype is not present, the POINTER directive is used implicitly.

When using the null-terminated representation, you must ensure that the CHARACTER STRING does not contain embedded null characters that will affect the encoding and decoding.

See Also


--<OSS.OBJECTID [[ENCODED] | [length]]>--
--<OSS.ENCODED>--

Allows the compiler to represent OBJECT IDENTIFIER types as structures with lengths in octets and addresses of arrays of characters containing the BER-encoded contents of the OBJECT IDENTIFIER. In other words, OBJECT IDENTIFIER types can be represented having node values that exceed the maximum INTEGER representation on a given machine. The encoded value is derived according to the ITU-T Rec.X.690 (2021) document (clause 8.19).

length specifies the size [2 to 32,767] in octets of the CHARACTER STRING containing the BER-encoded contents of the OBJECT IDENTIFIER.

ENCODED allows the string to contain the OBJECT IDENTIFIER value of arbitrary length.

Default Behavior

By default, OBJECT IDENTIFIER types are represented as structures with CHARACTER STRING pointers and length fields, giving the size of the CHARACTER STRING in bytes.

Example

The following example demonstrates the local and global use of the OSS.OBJECTID and OSS.ENCODED directives. The default representation is the same as the ENCODED representation:

ASN.1 .h
 --<OSS.OBJECTID ENCODED>--

 Module DEFINITIONS ::= BEGIN
    ObjectIDRep  ::= [1] OBJECT IDENTIFIER --<OBJECTID 82>--
    EncodedRep   ::= [2] OBJECT IDENTIFIER --<ENCODED>--
    UnboundedRep ::= [3] OBJECT IDENTIFIER --<UNBOUNDED>--
    DefaultRep   ::= [4] OBJECT IDENTIFIER
 END
typedef struct ObjectID {
    unsigned short  length;
    unsigned char   *value;
} ObjectID;

typedef struct ObjectIDRep {
    unsigned short  length;
    unsigned char   value[82];
} ObjectIDRep;

typedef ObjectID        EncodedRep;

typedef struct UnboundedRep {
    unsigned short  count;
    unsigned short  *value;
} UnboundedRep;

typedef ObjectID        DefaultRep;

Remarks

The OSS.ENCODED directive can only be used locally and is equivalent to the OSS.OBJECTID ENCODED directive.

The -helperNames option overrides the OSS.OBJECTID directive representation.


--<OSS.OBJHANDLE absoluteReference>--
--<OSS.NOCOPY absoluteReference>--

Enable you to encode portions of a PDU from a file or, when the file memory manager is used, to decode portions of a PDU to a file. When the default memory manager is used, the OSS.OBJHANDLE (OSS.NOCOPY) directive instructs the decoder to use a pointer to the encoded data during decoding instead of making a copy of the encoded data.

OSS.OBJHANDLE and OSS.NOCOPY are synonym directives. Both can be used on OCTET STRING, BIT STRING, restricted CHARACTER STRING types, or types with the ASN1.DeferDecoding directive applied, to specify special handling at run time.

Note that OSS.OBJHANDLE is permitted only on restricted CHARACTER STRING types with a single byte per character, BIT STRING, OCTET STRING, ANY, ANY DEFINED BY, and open types.

Example

In the following example, the .h file contains code that informs the encoder and decoder about the special handling of the type labeled SpecialHandling:

ASN.1 .h
 --<OSS.OBJHANDLE Module.SpecialHandling>--
 
 Module DEFINITIONS ::= BEGIN
    NoSpecialHandling ::= IA5String
    SpecialHandling   ::= IA5String
 END
typedef char            *NoSpecialHandling;

typedef struct SpecialHandling {
    unsigned int    length;
    char            *value;
} SpecialHandling;

Remarks

OSS.OBJHANDLE has no effect during run time if PER encoding is used. If other encoding rules are used (BER and DER, for example), the OSS.OBJHANDLE directive is fully implemented. For example, ossDecode() and ossCpyValue() do not allocate regular memory for fields of a PDU marked with the OSS.OBJHANDLE directive. Similarly, ossFreePDU() does not de-allocate memory for such fields.

See Also

ASN1.DeferDecoding


--<OSS.ONECHAR [[absoluteReference] | [asn1Type [, asn1Type]...]]>--

Instructs the compiler to limit the representation of a restricted CHARACTER STRING to one character.

asn1Type refers to a CHARACTER STRING type.

Default Behavior

By default, CHARACTER STRING types can have an indefinite length or a length specified by a subtype constraint.

Example

ASN.1 .h
  --<OSS.ONECHAR UniversalString>--
  --<OSS.ONECHAR Module.SingleCharBMP>--
  
  Module DEFINITIONS ::= BEGIN
     SingleCharUTF ::= UTF8String --<ONECHAR>--
     SingleCharUni ::= UniversalString
     SingleCharBMP ::= BMPString
     RegularBMP    ::= BMPString
  END
typedef unsigned char SingleCharUTF;
typedef int SingleCharUni;
typedef unsigned short SingleCharBMP;
typedef struct RegularBMP {
   unsigned int length;
   unsigned short *value;
} RegularBMP;

Remarks

This directive is especially useful for generating initialized C values for special characters, such as those in the ASN1-CHARACTER-MODULE, as defined in ISO/IEC 8824-1:1994.

The -helperNames option overrides the OSS.ONECHAR directive.


--<OSS.PADDED [[absoluteReference] | [asn1Type [, asn1Type]...]]>--

Indicates that character string, BIT STRING, and OCTET STRING types should be represented in the target language as fixed-length padded strings when the SizeConstraint subtype or the NamedBitList for the BIT STRING type, is used. The character string types are blank-padded and BIT STRING types are zero-padded. In other words, all strings specified with the OSS.PADDED directive are the same size; short character strings and BIT STRINGs can have trailing spaces or zeros, respectively.

Default Behavior

By default, character string types are represented as NULLTERM strings. BIT STRING and OCTET STRING types are represented as UNBOUNDED strings when the SizeConstraint subtype or NamedBitList is present.

Example

In the following example, UnPaddedStr is one character larger than PaddedStr because of the NULL terminated-character.

ASN.1 .h
--<OSS.PADDED Module.PaddedBitStr>--
 
 Module DEFINITIONS ::= BEGIN
    PaddedBitStr    ::= BIT STRING (SIZE (10))
    UnboundedBitStr ::= BIT STRING (SIZE (10))
 END
typedef unsigned short  PaddedBitStr;

typedef struct UnboundedBitStr {
    unsigned short  length;  /* number of significant bits */
    unsigned char   *value;
} UnboundedBitStr;

Remarks

The OSS.PADDED directive is not supported when the -helperNames option is specified.

See Also


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

Indicate whether an ASN.1 type can be sent or received as a protocol data unit. By default, all unreferenced types (defined types that are not referenced by any other type) are considered PDUs by the compiler and can be encoded or decoded as complete units.

When specified globally, these directives can take an absolute reference that specifies which component of the ASN.1 syntax is intended. If specified globally without an absolute reference, the OSS.PDU and OSS.NOPDU directives set a default for all types within their scope.

When specified locally, these directives do not take any arguments and only affect the type they are placed next to.

Example

The following ASN.1 notation demonstrates the local and global use of the OSS.PDU directive.

--<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

After passing the above notation through the ASN.1 compiler, the following is generated:

#define          MiddleAgeClubCard_PDU 1
#define          NameString_PDU 2
#define          PhoneString_PDU 3

typedef char            NameString[41];

typedef char            PhoneString[16];

typedef unsigned short  AgeInt;

typedef struct MiddleAgeClubCard {
    NameString      name;
    PhoneString     phoneNumber;
    AgeInt          age;
} MiddleAgeClubCard;

The #defines shown above mark which types are PDUs. Notice how AgeInt is not marked to be a PDU, since it is referenced in the SEQUENCE MiddleAgeClubCard and doesn't have a PDU directive applied to it.

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 (when compiling your ASN.1 syntax) or include the global OSS.ROOT directive in your ASN.1 specification.

See Also

ASN1.PDU


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

The OSS.NOPOINTER specifies that memory must be allocated inline for an ASN.1 type.

The OSS.POINTER specifies that a pointer to the type must be created without inline allocation for the type.

Default Behavior

By default, all C CHARACTER STRING data types without a size constraint use the OSS.POINTER representation. Other types use inline allocation.

Example

ASN.1 .h
  --<OSS.POINTER>--
  --<OSS.NOPOINTER MyModule.IntNoPoint >--
   
  MyModule DEFINITIONS ::= BEGIN
     IntNoPoint ::= INTEGER
     IntPoint ::= INTEGER
  END 
typedef int             IntNoPoint;

typedef int             *IntPoint;

Remarks

The OSS.POINTER directive affects the following simple types: BOOLEAN, INTEGER without OSS.HUGE directive, NULL, and REAL.

The -helperNames option overrides the OSS.NOPOINTER directive.


--<OSS.Preserve absoluteReference>--

Instructs the ASN.1 compiler to generate header files for non-PDU types which typically are ignored. All types that are referenced by the type selected will also have data structures generated for them.

Example

In the following example, without the -root option, the definitions in the non-root module Mod1 would not be generated. When using the OSS.Preserve directive, the following code is generated:

ASN.1 .h
  --<OSS.Preserve Mod1.ShortString>--
  
  Mod1 DEFINITIONS ::= BEGIN
     CompanyName ::= ShortString
     ShortString ::= PrintableString
  END
 
  Mod2 DEFINITIONS ::= BEGIN
     Name ::= IA5String
     Age  ::= INTEGER
  END
#define          Name_PDU 2
#define          Age_PDU 3

typedef char            *ShortString;

typedef char            *Name;

typedef int             Age;

Remarks

This directive is useful in the split-headers mode as it enables you to put selected type definitions in a particular module header file.

See Also


--<OSS.PrintFunctionName absoluteReference "myPrintFunctionName">--

Enables you to specify your own data formatter function for printing values of primitive types. This function is called during ossPrintPDU(), ossPrintPER(), etc.

The data formatter function must have the following prototype:

void DLL_ENTRY myPrintFunctionName (struct ossGlobal * handle, char * toPrint);

toPrint is a string that represents the ASN.1 value.

Default Behavior

By default, a generic internal data format and display utility is used.

ASN.1 primitive type String format
INTEGER | ENUMERATED decimal number
OCTET STRING
BIT STRING
'xx...xx'H
'xx...xx'B
REAL {mantissa, base, exponent}
restricted CHARACTER STRING quoted string
UTC/GeneralizedTime quoted string
OID-IRI/RELATIVE-OID-IRI quoted string

The OSS.PrintFunctionName directive can be used with one of the following OSS API function names to convert OCTET STRING type values to ASCII, IP address, TBCD, BCD, or a special time stamp format:

--<OSS.PrintFunctionName MyModule.Seq.name "ossPrintOctetAsASCII">--
--<OSS.PrintFunctionName MyModule.Seq.ip "ossPrintOctetAsIPAddress">--
--<OSS.PrintFunctionName MyModule.Seq.tbcd "ossPrintOctetAsTBCDString">--
--<OSS.PrintFunctionName MyModule.Seq.bcd "ossPrintOctetAsBCDString">--
--<OSS.PrintFunctionName MyModule.Seq.time "ossPrintOctetAsTimeStamp">--

  
  MyModule DEFINITIONS ::= BEGIN
    Seq ::= SEQUENCE {
       name OCTET STRING,
       ip   OCTET STRING,
       tbcd OCTET STRING,
	   bcd  OCTET STRING,
	   time OCTET STRING

    }
 END
 

Remarks

The OSS ASN.1 Tools includes the following commonly used replacement print functions: ossPrintOctetAsIPAddress(), ossPrintOctetAsASCII(), ossPrintOctetAsTBCDString(), ossPrintOctetAsBCDString(), and ossPrintOctetAsTimeStamp().


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

Identifies ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. In addition, the scope of non-root modules is to supply external references to root modules.

Default Behavior

By default, the last ASN.1 input file specified on the command line contains the root module.

Example

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

Remarks

OSS.ROOT 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.

See Also

-root


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

Instructs the compiler whether to generate a sample application containing code for PDU types and values identified by it.

The pdus or values parameters are used to apply the directive to all PDUs or values.

count:number specifies the default number of items created by the compiler for sample values of SEQUENCE OF and SET OF types. If count:number is not specified, the number of items is 1.

selection refers to a CHOICE alternative. By default, the compiler selects the first CHOICE alternative for the values in the sample code. If there are several such directives assigned to different alternatives of the same CHOICE type, the compiler creates as many sample values as specified.

Example

The compiler generates sample code for all values, except for 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

In the following example, the compiler generates a sequence of three sample values for a CHOICE:

  --<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 }

Remarks

Compared to the -sampleCode command-line option, the OSS.SampleCode directive provides more control over the sample code that is created.

You can use the OSS.SampleCode directive more than once in the ASN.1 input.

The OSS.NoSampleCode directive can be used to exclude PDUs or values from the sample application.

Applying OSS.SampleCode results in the same sample code as when using the -sampleCode command-line option.

The -noSampleCode | -sampleCode options override the OSS.SampleCode | OSS.NoSampleCode directives.

See Also

-sampleCode | -noSampleCode


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

Instructs the E-XER decoder to preserve the wildcard body in the decoded value as it was in the original XML document. Applies to types with the XER ANY-ELEMENT encoding instruction.

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>

n1:wildcard is an element wildcard, the decoder produces:

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

Without the SelfCompleteWildcard directive:

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

Remarks

When decoding from plain memory with the SOED and when using LED, the wildcard contents are directly copied to the output C value. When decoding from files and sockets with the SOED, 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 applies:

  • Namespaces declared in outer XML elements are not declared again in the decoded wildcard value.
  • The original order of namespaces and attributes is preserved when namespaces are declared before attributes.

When the wildcard contents are normalized according to the W3C Canonical XML specification, the decoded wildcard value matches the original XML value. This enables you to validate the digital signature of a wildcard after decoding.

The directive is also useful to increase the E-XER decoding speed of wildcards when knowing that they are self-complete and that they do not use namespace or entity declarations from an outer XML document.

See Also

OSS.ExtensibleUseType


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

Determine the representation of INTEGER types.

Default Behavior

By default, if no subtype constraints are present, the OSS.INT directive is implied.

Directive Representation Notes
OSS.SHORT 16 bit  
OSS.INT 32 bit 16 bit on older OS
OSS.LONG 32 bit  
OSS.LONGLONG 64 bit  32 bit on platform that do not support 64 bit INTEGERs

Example

In the following example, LONG_LONG is defined in the file asn1hdr.h and is C compiler-specific representation of a 64-bit INTEGER:

ASN.1 .h
   --<OSS.SHORT>--
   --<OSS.INT Module.GlobalINTInt>--
   
   Module DEFINITIONS ::= BEGIN
      GlobalDefaultInt ::=  INTEGER
      GlobalINTInt ::= INTEGER
      LONGInt ::=  INTEGER --<LONG>--
      LONGLONGInt ::=  INTEGER --<LONGLONG>--
   END
typedef short           GlobalDefaultInt;

typedef int             GlobalINTInt;

typedef long            LONGInt;

typedef LONG_LONG       LONGLONGInt;

Remarks

When constraints are applied to INTEGER types, the compiler chooses the smallest representation that can carry all the required values, thus ignoring such directives, except when a directive is specified with an absoluteReference or locally (inline).

See Also

OSS.LENGTHSIZE


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

Instructs the compiler to omit certain letters from long names to reduce their size to 31 characters in the header file. This directive accommodates maximum name length requirements that exist on certain C compilers. The OSS ASN.1 compiler ensures that all shortened names are unique by adding _# suffixes, when necessary.

Default Behavior

By default, shortenToLength is 31 and must be 16 or greater.

Example

ASN.1 .h
  --<OSS.SHORTENNAMES>--
   
  Mod DEFINITIONS ::= BEGIN
     WeWereTryingToThinkOfaNameButWeCouldNotFindaSuitableOne ::= INTEGER
     NormalName ::= BOOLEAN
  END
typedef int             WWTTTONBWCNFSOn;

typedef ossBoolean      NormalName;

See Also

-shortenNames


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

Instructs the compiler to represent GeneralizedTime or UTCTime types as structures and not as strings.

This directive has three forms. When specified globally, the absoluteReference operand should refer to a specific ASN.1 GeneralizedTime or UTCTime type that you want to represent as a structure.

--<OSS.TIMESTRUCT absoluteReference>--

Alternatively, you can use the asn1Type argument to provide the name of an ASN.1 built-in type (GeneralizedTime or UTCTime) whose default representation should be set to the structure. If the asn1Type argument is absent, both the GeneralizedTime and UTCTime types will be represented as a structure.

--<OSS.TIMESTRUCT [asn1Type]>--

When specified locally, the TIMESTRUCT directive takes no operands and affects only the type that it is placed next to.

--<TIMESTRUCT>--

Example

ASN.1 With -helperNames
  --<OSS.TIMESTRUCT Mod.Utc>--
  
  Mod DEFINITIONS ::= BEGIN
     Utc ::= UTCTime
     Gen ::= GeneralizedTime
  END
#define          Utc_PDU 1
#define          Gen_PDU 2

typedef UTCTime         Utc;

typedef char            *Gen;

Remarks

The -helperNames and -lean options override the OSS.TIMESTRUCT directive.

See Also

OSS.NULLTERM


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

Instructs the ASN.1 compiler to generate a separate XML stylesheet with your filename for any particular PDU. This directive gives you more control over the default XML stylesheets generated by the ASN.1 compiler.

When absoluteReference is not specified, a stylesheet is generated for every PDU in the input syntax.

Example

For the following syntax, two separate stylesheet files (StringType.xsl and AnotherNameForInt.xsl) are generated. They contain default 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

Remarks

When the -xsl option is specified, a stylesheet for each PDU is generated into a separate file whose name is derived from that of the PDU.

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

See Also


--<OSS.TypeIndex>--

This directive is a deprecated internal directive that is generated into the .spl file when the -splitHeaders or -splitForSharing option is used.


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

Disables printing of specific informatory and warning messages. This is useful when compiling abstract syntaxes that contain specifications which are not fully compliant with the ASN.1 standard.

messageID specifies which message needs to be suppressed. The messageID can be either the full message identifier (A0178W) or just the numeric part of the message number (178).

Default Behavior

By default, informatory and warning messages suppressed when -noRelaxedMode is turned on.

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. The following warning message is not generated for the above syntax:

  "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


--<OSS.Truncate absoluteReference maxLimit>--

Enables you to increase the decoding speed of certain large PDUs by skipping extra trailing elements in SET OF or SEQUENCE OF types.

absoluteReference refers to SET OF or SEQUENCE OF types for which all elements with an index greater than maxLimit are ignored.

maxLimit is an integer number between 1 and 16384.

Example

In the following example, by using the generated control-table/code-file, the decoder will only process 3000 elements of type Records. This type of truncation is useful when the information you need should not be at the end of the list of elements or will not be included in a large list of elements:

   --<OSS.Truncate Mod.Records 3000>--
   
   Mod DEFINITIONS ::= BEGIN
   
   Records ::= SEQUENCE OF Employee
   Employee ::= SEQUENCE {
      name IA5String,
      position IA5String,
      salary REAL
   }
   END

--<OSS.UNBOUNDED [absoluteReference] | [asn1Type [,asn1Type...]>--

Instructs the compiler to represent CHARACTER STRING types, BIT STRING types, and OCTET STRING types as length/pointer pairs and SET OF and SEQUENCE OF types as count/pointer pairs.

Default Behavior

By default, CHARACTER STRING types (GeneralString, GraphicString, IA5String, NumericString, PrintableString, TeletexString, UTF8String, VideotexString, VisibleString) are represented as null-terminated strings.

For BIT STRING types, the default representation is the UNBOUNDED representation when the SizeConstraint subtype is specified and a NamedBitList is present.

For OCTET STRING types, the default representation is the VARYING representation when the SizeConstraint subtype is specified.

For SET OF and SEQUENCE OF types, the default is the LINKED representation.

Example

ASN.1 .h
  --<OSS.UNBOUNDED Module.SeqOfIntU>--
  --<OSS.UNBOUNDED IA5String>--
  
  Module DEFINITIONS ::= BEGIN
     SeqOfInt  ::= SEQUENCE OF INTEGER
     SeqOfIntU ::= SEQUENCE OF INTEGER
     Ia5Str    ::= IA5String --<NULLTERM>--
     Ia5StrU   ::= IA5String
     UTF8Str   ::= UTF8String
     UTF8StrU  ::= UTF8String --<UNBOUNDED>--
     OctetStrU ::= OCTET STRING
  END
typedef struct SeqOfInt {
struct SeqOfInt *next;
int value;
} *SeqOfInt;

typedef struct SeqOfIntU {
   unsigned int count;
   int *value;
} SeqOfIntU;

typedef char *Ia5Str;

typedef struct Ia5StrU {
   unsigned int length;
   char *value;
} Ia5StrU;

typedef char *UTF8Str;
   
typedef struct UTF8StrU {
   unsigned int length;
   char *value;
} UTF8StrU;
           
typedef struct OctetStrU {
   unsigned int length;
   unsigned char *value;
} OctetStrU;

Remarks

The local --<NULLTERM>-- directive overrides the global default set by the --<OSS.UNBOUNDED IA5String>-- directive.

The default representation for the OCTET STRING type is UNBOUNDED.

When a SizeConstraint subtype is specified, the count or length field of the UNBOUNDED representation is either short, int, or long, depending on which is the smallest to fit the largest value. When the SizeConstraint subtype is absent, the count or length field is always int.

See Also


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

Instructs the compiler to represent UTF8String types as unbounded arrays of four-byte characters (UCS-4), the same as the representation of the UniversalString.

Default Behavior

By default, UTF8String types are represented as NULL terminating CHARACTER STRINGs

Example

ASN.1 .h
 --<OSS.UNIVERSALSTRING Module.FourByteGlobal>--
 
 Module DEFINITIONS ::= BEGIN
    Nullterm ::= UTF8String
    FourByte ::= UTF8String
    TwoByte  ::= UTF8String --<BMPSTRING>--
 END
typedef char *Nullterm;

typedef struct TwoByte {
   unsigned int length;
   unsigned short *value;
} TwoByte;

typedef struct FourByte {
   unsigned int length;
   int *value;
   } FourByte;

See Also

OSS.BMPSTRING


--<OSS.UseThis absoluteReference1 absoluteReference2>--

Enables you to reduce the size of the ASN.1 compiler-generated header file by eliminating similar C typedefs. This is useful for multiple instances of parameterized and constrained types which do not satisfy all the requirements for typesharing.

absoluteReference1 refers to the component of the ASN.1 specification that will be substituted.

absoluteReference2 refers to the component that will be used in the substitution.

Example

ASN.1 With OSS.UseThis Without OSS.UseThis
  --<OSS.UseThis Module.S1.a Module.S2>--
  
  Module DEFINITIONS ::= BEGIN
     S1 ::= SET {
        a SET OF INTEGER
     }
     S2 ::= SET OF INTEGER
  END
 typedef struct S2 {
   struct S2 *next;
   int value;
 } *S2;
 
 typedef struct S1 {
   struct S2 *a;
 } S1;
 typedef struct _setof1 {
   struct _setof1 *next;
   int value;
 } *_setof1;
 
 typedef struct S1 {
   struct _setof1 *a;
 } S1;
 
 typedef struct S2 {
   struct S2 *next;
   int value;
 } *S2;

Remarks

With the OSS.UseThis directive, you can substitute only ASN.1 types. Fields are not allowed.


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

Enables the compiler to generate a user field defined locally that can be used only for a particular application. User fields can appear in ASN.1 SEQUENCE or SET types and must be either marked as OPTIONAL or DEFAULT. These fields make it easier to handle compiler-generated C data structures. The OSS.USERFIELD directive instructs the encoder to skip the field and the decoder to perceive an error upon receipt of a value which appears in the same context and has the same tag as the user field.

Default Behavior

By default, no user field is generated.

Example

For the following example, the encoder and decoder ignores the controlGroup field:

ASN.1 .h
  --<OSS.USERFIELD Module.DataCard.controlGroup>--
  
  Module DEFINITIONS ::= BEGIN
     DataCard ::= SEQUENCE {
        controlGroup BOOLEAN DEFAULT FALSE,
        ame PrintableString,
        numberOfCars INTEGER (1..5)
     }
  END
typedef struct DataCard {
    unsigned char   bit_mask;
#       define      controlGroup_present 0x80
    ossBoolean      controlGroup;  /* user field */
    char            *ame;
    unsigned short  numberOfCars;
} DataCard;

Remarks

The compiler cannot generate bit masks for optional user fields.

The compiler subjects user fields to the same ASN.1 restrictions as non-user fields. For example, an OPTIONAL element of a SET or SEQUENCE must have a tag that is different from the element which follows it, regardless of whether either of these elements is a user field.


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

Specifies whether a C variable should be generated and initialized in the .c file for each ASN.1 value.

Example

ASN.1 C
  --<OSS.NOVALUE Module.ID>--
  
  Module DEFINITIONS ::= BEGIN
     Name ::= IA5String
     ID ::= INTEGER
        myName Name ::= "John"
        myID ID ::= 12345
  END
 Name myName = "John";

--<OSS.VARYING [[absoluteReference] | [asn1Type [,asn1Type]...]]>--

Specifies the length-prefixed variable-length string representation for CHARACTER STRING types with a size constraint, BIT STRING types with a named bit list, and OCTET STRING types.

Example

ASN.1 .h
  --<OSS.VARYING MyMo.VaryingStr>--
  
  MyMo DEFINITIONS ::= BEGIN
     DefaultStr ::= VisibleString (SIZE(10))
     VaryingStr ::= VisibleString (SIZE(10))
  END
typedef char            DefaultStr[11];

typedef struct VaryingStr {
    unsigned short  length;
    char            value[10];
} VaryingStr;

Remarks

The -helperNames option overrides the OSS.VARYING directive.

See Also


--<OSS.XEREncodeFunction absoluteReference "yourXEREncodeFunctionName"
[parameterAbsoluteReference]>--

Enables you to specify the data formatter function for encoding ASN.1 types using XML Encoding Rules. The function that you provide is called each time the XER Encoder adds the encoding of the type affected by this directive to the output buffer; instead of generating the XER encoding for the type, the encoder passes its C value to the user-defined function and expects the encoded value to be returned.

parameterAbsoluteReference specifies an additional ASN.1 type to be used as a parameter of the encoding function; the encoder submits the last instance of the parameter type found in the input PDU value to the user-provided function each time it is called.

yourXEREncodeFunctionName has the following prototype:

  int DLL_ENTRY 
  yourXEREncodeFunctionName(
     struct ossGlobal *world,
     yourType *in, 
     [yourParameter *param,] 
     OssBuf *out,
     OssSafeMallocp safemalloc);

Remarks

When the OSS.XEREncodeFunction directive is applied to an ASN.1 type, the values of this type are not encoded according to the ITU-T X.693/ISO 8825-4 standard; instead, each value is provided to the formatter function for encoding according to custom application requirements.

Also, you can provide an optional C value for the function parameter (NULL is provided when no parameter values are found in the input PDU when calling the XER encoding function). The function must populate the length and value fields of the OssBuf *out structure and return success (one of the values OSS_FORMAT_OK_STATIC or OSS_FORMAT_OK) or an error code (any positive integer).

OSS_FORMAT_OK_STATIC instructs the encoder not to free the memory referenced by the value field of the OssBuf (it is assumed that this memory is not allocated on the heap).

OSS_FORMAT_OK instructs the encoder to free the memory. The XER encoding function can dynamically allocate the output memory only by calling the safemalloc function.


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

Copyright © 2024 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.