|
Overview |
Compiler Options |
Compiler Directives |
C++ Representation |
Errors |
Cross-Compiling |
Advanced Topics
Changes the C++-representation of a specific CHOICE, SEQUENCE, or SET component to an instance of the OssOpen class. The BER and DER decoders will not decode the component; its undecoded form is left in the "encoded" field of the structure.
--<ASN1.DeferDecoding absoluteReference>--
The class that absoluteReference refers to will be replaced by the OssOpen class, which the user application will encode and decode separately.
The ASN1.DeferDecoding directive:
We stand with Ukraine --<ASN1.DeferDecoding Module.Type.setComponent>--
Module DEFINITIONS ::= BEGIN
Type ::= SET {
setComponent INTEGER,
b BOOLEAN
}
END
The following types are produced in the .h file for the ASN.1 above:
class OSS_PUBLIC Type /* SET */
{
public:
. . .
typedef OssOpen setComponent;
typedef ossBoolean b;
. . .
setComponent & get_setComponent();
const setComponent & get_setComponent() const;
void set_setComponent(const setComponent &);
b & get_b();
b get_b() const;
void set_b(b);
. . .
};
typedef OSS_INT32 Type_setComponent_encodable;
Sets a special representation for INTEGERs whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.
--<ASN1.HugeInteger absoluteReference>--
absoluteReference refers to an ASN.1 INTEGER type that will be represented using the OssHugeInt class.
--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
lengthOfSolarSystem INTEGER,
units ENUMERATED
{mm(0), cm(1), m(2), km(3), lightyears(4)} DEFAULT mm
}
END
When the OSS ASN.1/C++ compiler compiles the example ASN.1 above, the following code is generated in the header file:
class OSS_PUBLIC LengthData /* SEQUENCE */
{
public:
. . .
typedef OssHugeInt lengthOfSolarSystem;
typedef enum _enum1 units;
. . .
lengthOfSolarSystem & get_lengthOfSolarSystem();
const lengthOfSolarSystem & get_lengthOfSolarSystem() const;
void set_lengthOfSolarSystem(const lengthOfSolarSystem &);
units *get_units();
const units *get_units() const;
void set_units(units );
int units_is_default() const;
void set_default_units();
. . .
};
The ASN1.HugeInteger directive requires a parameter and it cannot be applied to all integers.
Assigns an alias to a name in an ASN.1 module for use in the generated code. By default, names in the generated code are derived from the input ASN.1 syntax.
--<ASN1.Nickname absoluteReference nickname>--
absoluteReference specifies a name for one of the following:
The nickname parameter should follow the naming rules of the target programming language.
--<ASN1.Nickname MyModule.MySequence.MyTypeName MTN>--
--<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
}
ENDIn the absolute reference of the Gibbon nickname, * refers to the SEQUENCE and the following 1 refers to the first element in that SEQUENCE, which is key. The ASN.1 syntax above is equivalent to the following:
Module DEFINITIONS ::= BEGIN
UserData ::= SET --<TYPENAME "Monkey">-- OF
SEQUENCE {
key INTEGER --<FIELDNAME "Gibbon">--,
fvalue OCTET STRING --<FIELDNAME "Mandrill">-- OPTIONAL
} --<TYPENAME "Gorilla">--
END
When compiled, both versions of the ASN.1 syntax create the following code in the generated .h file:
class OSS_PUBLIC Monkey : public OssList /* SET OF */
{
public:
typedef Gorilla component;
. . .
};
class OSS_PUBLIC Gorilla /* SEQUENCE */
{
public:
. . .
typedef OSS_INT32 Gibbon;
typedef OssString Mandrill;
. . .
};
--<ASN1.Nickname Module.PasswordChallengeRequestResponse.
-- challengeRequestResponse.challengeResponse pcrrResponse>--
Module DEFINITIONS ::= BEGIN
PasswordChallengeRequestResponse ::= CHOICE {
passwordInTheClear INTEGER,
challengeRequestResponse SEQUENCE {
challengeRequest BOOLEAN OPTIONAL,
challengeResponse INTEGER OPTIONAL
}
}
ENDASN.1 compilation results in the following code:
class OSS_PUBLIC __seq1 /* SEQUENCE */
{
public:
. . .
typedef ossBoolean challengeRequest;
typedef OSS_INT32 pcrrResponse;
. . .
};
NOTE: For this example, you could substitute OSS.FIELDNAME for ASN1.Nickname and get the same result.
--<ASN1.Nickname Module.UserData.* UserDataSeq>--
Module DEFINITIONS ::= BEGIN
UserData ::= SET OF SEQUENCE {
key INTEGER,
value OCTET STRING OPTIONAL
}
END
In the ASN1.Nickname directive, * refers to the intermediate type created for the SEQUENCE.
The ASN.1 Compiler generates code that includes:
class OSS_PUBLIC UserData : public OssList /* SET OF */
{
public:
typedef UserDataSeq component;
. . .
component *at(OssIndex);
const component *at(OssIndex) const;
OssIndex prepend(const component & );
OssIndex prepend(UserData *);
OssIndex insert_after(OssIndex, const component & );
OssIndex insert_after(OssIndex, UserData *);
int remove_front();
int remove_after(OssIndex);
UserData *extract_after(OssIndex, OssIndex);
};
class OSS_PUBLIC UserDataSeq /* SEQUENCE */
{
public:
. . .
typedef OSS_INT32 key;
typedef OssString value;
. . .
key & get_key();
key get_key() const;
void set_key(key);
value *get_value();
const value *get_value() const;
void set_value(const value &);
int value_is_present() const;
void omit_value();
. . .
};
--<ASN1.Nickname Module.E.enum1 "new_enum1">--
Module DEFINITIONS ::= BEGIN
E ::= ENUMERATED {enum1(1), enum2(2)}
END
Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs). By default, all unreferenced types (defined types not referenced by any other type) are considered PDUs by the compiler, so they can be encoded and decoded as complete units.
--<ASN1.PDU type [, type] ...>--
type is an absolute reference that specifies which ASN.1 types should be treated as PDUs.
--<ASN1.PDU Module.Type>--
Module DEFINITIONS ::= BEGIN
TypeRef ::= Type
Type ::= SET { b BOOLEAN }
END
In the example above, Type will be treated as a PDU, even if it is referenced in another type definition.
After ASN.1 compilation, the following is generated in the header file:
/* Universal PDU class */
class OSS_PUBLIC sample_PDU : public UniversalPDU {
public:
sample_PDU();
void set_TypeRef(TypeRef &);
TypeRef *get_TypeRef() const;
void set_Type(Type &);
Type *get_Type() const;
. . .
};
/* Specific PDU classes */
class OSS_PUBLIC TypeRef_PDU : public ConcretePDU {
public:
TypeRef_PDU();
void set_data(TypeRef &);
TypeRef *get_data() const;
. . .
};
class OSS_PUBLIC Type_PDU : public ConcretePDU {
public:
Type_PDU();
void set_data(Type &);
Type *get_data() const;
. . .
};
Selects a binary or decimal representation for ASN.1 REAL type values. This directive can be applied to specific REAL types, or set as default for all REAL types. By default, the REAL type is represented by the C++ double class (i.e., binary).
--<ASN1.RealRepresentation realKind type [, type, ...]]>--
realKind refers to the desired representation and can be binary or decimal. Use binary to represent a REAL as a double in the generated .cpp and .h files. Use decimal to represent a REAL as a character string in "[-]nnnnn.nnnnn[E[-]nnnnn]" format (OssDecimal class). Each type is an absolute reference to a type or types affected by the directive. If no type is specified, the ASN1.RealRepresentation directive sets the default representation for REAL types at the local, module, or global level, according to its placement.
For a global effect, use the ASN1.RealRepresentation directive without type references and place it before the first module in the ASN.1 input.
--<ASN1.RealRepresentation decimal Module.Type.a1.b2>--
Module DEFINITIONS ::= BEGIN
Type ::= SEQUENCE {
a1 SET { b1 INTEGER, b2 REAL},
a2 REAL
}
END
The ASN.1 definition above is equivalent to the following:
Module DEFINITIONS ::= BEGIN
Type ::= SEQUENCE {
a1 SET { b1 INTEGER, b2 REAL --<DECIMAL>--},
a2 REAL
}
END
When compiled, both versions create the following code in the generated .h file:
class OSS_PUBLIC __set1 /* SET */
{
public:
. . .
typedef OSS_INT32 b1;
typedef OssDecimal b2;
. . .
};
class OSS_PUBLIC Type /* SEQUENCE */
{
public:
. . .
typedef __set1 a1;
typedef double a2;
. . .
};
Instructs the compiler to omit certain types or components from input ASN.1 modules when generating the output .h and .cpp files. Use this directive to exclude part of an ASN.1 specification without modifying the original ASN.1 source. By default, all of the input ASN.1 is included in the compiler-generated files.
--<ASN1.Remove absoluteReference [, absoluteReference ] ...>--
absoluteReference can refer to any of the following:
Even though components are omitted from the input ASN.1, the encodings that result are compatible with corresponding applications that do not use the ASN1.Remove directive. This is due to the following practices:
When an ASN.1 item is marked for removal, also remove any references to the item using the ASN1.Remove directive. If errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the ASN.1/C++ Compiler automatically generates the needed ASN1.Remove directives in a file with a .rmv extension and the same prefix as the .gen file. The generated .rmv file can be passed to the command line, before any compiler options, so the compiler automatically removes the problematic types. NOTE: In certain circumstances, ASN1.Remove directives cannot be generated into the .rmv file. The user should then call the ASN.1 Compiler several times, correcting the syntax, until the notation ASN.1-compiles cleanly.
The listing file generated with the -listingFile command-line option omits removed items entirely. For a full listing that includes any removed items, use the -modListingFile command-line option.
Standard directives applied to or found within ASN.1 items marked for removal have no effect.
When the ASN1.Remove directive is applied to the fields of a parameterized type, those fields are removed from each instance of the parameterized type. Applying the ASN1.Remove directive to parameterized types is not recommended.
When fields are removed from a type referenced in the COMPONENTS OF type notation, those fields are removed from each type specified with the COMPONENTS OF type notation.
Types that are referenced only by items marked for removal could become PDUs after those items are removed.
--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--
Mod DEFINITIONS ::= BEGIN
S ::= SET {
a SET OF SET OF SEQUENCE {
b Int
}OPTIONAL
}
Int ::= INTEGER
i Int ::= 10
END
After compiling the syntax above, only an empty S class is generated in the header file:
class OSS_PUBLIC S /* SET */
{
public:
void * operator new(size_t size);
void operator delete(void *ptr);
S();
S(const S &);
S & operator = (const S &);
int operator == (const S &) const;
int operator != (const S &) const;
. . .
};
Following is a more complex example:
--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--
Mod DEFINITIONS ::= BEGIN
Int ::= INTEGER
A ::= SEQUENCE {
a Int OPTIONAL,
b BIT STRING
}
a A ::= { a 1, b bit}
bit BIT STRING ::= '0'B
C ::= CHOICE {
a Int
}
Set ::= SET {
a SET {
b SET {
c SET {
d SET OF SET {
e INTEGER OPTIONAL
}
}
}
}
}
s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
END
The example above generates the following ASN1.Remove directives in the .rmv file:
Specifies the year of the ASN.1 standard in use for a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source. By default, the ASN.1 Compiler starts out in neutral mode, expecting any ASN.1 version. Once version-specific syntax is detected, the compiler exits neutral mode and checks for conformance to the detected version.
--<ASN1.Version version moduleName [{ oid }]>--
version refers to a year that an ASN.1 standard was published by ITU-T (e.g., 1990, 1994, 1997, 2002, 2008, 2015, or 2021). moduleName is a mandatory operand that specifies the module to which the directive is applied. oid is an optional OBJECT IDENTIFIER for unique module identification.
If the ASN1.Version directive conflicts with the -1990 | -2021 compiler option, the most recent version is used.
--<ASN1.Version 1990 Module>--
Module DEFINITIONS --<ASN1VER 1994>-- ::= BEGIN
a A ::= INTEGER {one(1), two(2)} : one
A ::= ANY
Type ::= SET {
typeComponent INTEGER,
b BOOLEAN
}
END
In the example above, the ASN1.Version directive takes precedence over the OSS-specific legacy ASN1VER directive.
Selects those items in the ASN.1 input that are key to the application. All names (types, values, information objects, etc.) defined in the working set are directly available for use by the application. By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives present. See Default Determination of the Working Set below for details.
--<ASN1.WorkingSet WSName absoluteReference [, absoluteReference] ...>--
WSName is the name of the working set. Although required for consistency with other ASN.1 Tools, it is otherwise ignored. absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. When a module name is referenced, the ASN1.WorkingSet directive has the same effect as that of the OSS.ROOT directive: all unreferenced types in this module are considered PDUs.
Items in the ASN.1 specification that are not included in the working set are available to the application only when they are referenced from the working set.
A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set on its own.
To extend an existing working-set, specify another instance of the ASN1.WorkingSet directive containing the existing working-set name and the ASN.1 item to be added. In the following ASN.1, both module1 and module14 will be included in commonSet:
--<ASN1.WorkingSet commonSet module1>-- . . . --<ASN1.WorkingSet commonSet module14>--
Including a type reference in a working set does not necessarily make it a PDU. In the following ASN.1, MyWorkingSet does not explicitly include A.Foo; it is included implicitly since A.Foo is referenced by A.Bar. The result is two types in the working set that reference each other; so neither is a PDU (unless the implementation makes them so).
--<ASN1.WorkingSet MyWorkingSet A.Bar>--
A DEFINTIONS ::= BEGIN
Foo ::= SEQUENCE OF Bar
Bar ::= SEQUENCE {a INTEGER, b Foo OPTIONAL}
Z ::= BOOLEAN
ENDIn this example, Type1, Type2, and Type4 are directly available to the application as PDUs; Type3 is not.
--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
Type1 ::= SET {
typeComponent INTEGER,
b BOOLEAN
}
Type2 ::= INTEGER
END
Module3 DEFINITIONS ::= BEGIN
Type3 ::= SET {
aComponent INTEGER,
b BOOLEAN
}
Type4 ::= IA5String
END
The ASN.1 Compiler derives the working set by considering four types of directives, in the following order:
Based on the presence or absence of these directives in the input, the ASN.1 Compiler assumes one of these four modes:
Different sets of directives in the ASN.1 input determine which ASN.1 Compiler mode is used, as shown in the following table. 1 means a directive is present, 0 means a directive is absent, and 1/0 indicates that a directive can be present or absent with no effect on mode selection.
| Directive Types Present in Input | ASN.1 Compiler Mode | |||
|---|---|---|---|---|
| ASN1.WorkingSet | Other ASN1.* Directives | OSS.ROOT | Other OSS.* Directives | |
| 0 | 1 | 0 | 0 | Default Working Set |
| 0 | 0 | 0 | 0 | Root Default |
| 0 | 1/0 | 0 | 1 | |
| 1 | 1/0 | 1 | 1/0 | Working Set |
| 0 | 1 | 1 | 1/0 | |
| 1 | 1/0 | 0 | 1/0 | |
| 0 | 0 | 1 | 1/0 | Root |
Specifies which version of the ASN.1 standard is in use in the ASN.1 input. By default, the ASN.1 Compiler starts out in neutral mode, expecting any ASN.1 version. Once version-specific syntax is detected, the compiler exits neutral mode and checks for conformance to the detected version.
--<OSS.ASN1VER [absoluteReference] version>--
When specified globally, absoluteReference refers to the name of an ASN.1 module or a module component that should be treated as if it is in ASN.1: version syntax. version refers to a year that an ASN.1 standard was published by ITU-T and can be: 1990, 1994, 1997, 2002, 2008, 2015, or 2021. If specified globally without an absolute reference, OSS.ASN1VER sets the ASN.1 version for the entire ASN.1 input. When specified locally, this directive does not accept an absolute reference and only affects the type it is placed next to.
The OSS.ASN1VER directive in this example instructs the compiler to allow the unnamed elements in the NoNames SEQUENCE elements. With ASN.1: 2021, all elements of a CHOICE, SEQUENCE, or SET require an identifier.
--<OSS.ASN1VER MyModule.NoNames 1990>--
MyModule DEFINITIONS ::= BEGIN
NoNames ::= SEQUENCE {
BOOLEAN,
BOOLEAN,
INTEGER
}
END
Represents a UTF8String type in C++ as the OssBMPString class.
--<OSS.BMPSTRING [absoluteReference]>--
absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String.
OSS.BMPSTRING functions only as a local directive when used without arguments.
When specified globally, this directive expects an absolute reference for a UTF8String type that requires OssBMPString representation. When specified locally, OSS.BMPSTRING does not accept any arguments and affects only the type it is placed next to.
With BMPString and UniversalString representations, character data is automatically converted to UTF-8 format before XER/CXER/E-XER encoding and is converted from UTF-8 format after XER/CXER/E-XERdecoding.
--<OSS.BMPSTRING Module.TwoByteGlobal>--
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--
Module DEFINITIONS ::= BEGIN
Default ::= UTF8String
TwoByteLocal ::= UTF8String --<BMPSTRING>--
TwoByteGlobal ::= UTF8String
FourByteLocal ::= UTF8String --<UNIVERSALSTRING>--
FourByteGlobal ::= UTF8String
END
The above syntax shows OSS.BMPSTRING used with and without arguments. TwoByteGlobal is set to OssBMPString representation by specifying OSS.BMPSTRING globally with an absolute reference. TwoByteLocal is set using the directive at the local level. OSS.BMPSTRING is not applied to Default, so it is set to the default OssString representation. FourByteLocal and FourByteGlobal are set to OssUniversalString representation by the OSS.UNIVERSALSTRING directive. Part of the generated header file for the above notation is shown below:
typedef OssString Default; typedef OssBMPString TwoByteLocal; typedef OssBMPString TwoByteGlobal; typedef OssUniversalString FourByteLocal; typedef OssUniversalString FourByteGlobal;
Instructs the ASN.1 Compiler to place a user-defined comment near the beginning of the generated .cpp and .h files. By default, user-defined comments are not generated.
--<OSS.COMMENT "commentText">--
commentText is the comment, enclosed in quotation marks, that will appear at the top of the generated files.
The OSS.COMMENT directive can only be specified globally and can occur only once in the ASN.1 input. If two or more OSS.COMMENT statements are found, the last one encountered is used and the others are ignored.
--<OSS.COMMENT "!ALERT! PDU should be encrypted before sending.">--
AccessData DEFINITIONS ::= BEGIN
TopSecret ::= SEQUENCE {
username IA5String,
password IA5String,
accessLevel INTEGER
}
END
When the ASN.1 syntax above is compiled, the comment is generated at the top of the .h and .cpp files, just below the copyright information:
/***************************************************/ /* !ALERT! PDU should be encrypted before sending.*/ /***************************************************/
Associates SEQUENCE or SET fields, CHOICE alternatives, or SEQUENCE OF or SET OF elements with your callback method when using partial decoding. This directive affects only generated decoding functions. The -enablePartialDecode and -partialDecodeOnly options cause the <module_name>_Callback class to be incorporated into the generated header and code files; other definitions are unaffected.
When specified globally, either in an ASN.1 file before the module definition or in a separate directives file, the OSS.DataCallback directive takes an absolute reference to a field:
--<OSS.DataCallback [absoluteReference] ["]MethodName["]>--
MethodName is the user-defined name for the callback method.
When specified locally, the OSS.DataCallback directive is placed next to the field definition, as shown in the following example:
age INTEGER(1..100) --<OSS.DataCallback "MethodName">--
When OSS.DataCallback is applied to a field of a named type, the decoded PDU could include several fields of this type. The decoder will call the same callback method for each one, and cannot differentiate a call for one field from a call for another since both are associated with the same method. Consider using the OSS.InfoCallback directive to discern the difference.
Sets the representation for an ASN.1 REAL type. By default, REAL is represented as a double in C++.
--<OSS.DECIMAL [absoluteReference]>--
absoluteReference refers to a component in the ASN.1 syntax to be represented by the OssDecimal class.
When the OSS.DECIMAL directive is used, the OssDecimal class is generated. The internal representation is a null-terminated character string of the form: [-]nnnnn.nnnnn[E[-]nnnnn]. The character string pointer can also be set to point to the special OSS_PLUS_INFINITY, OSS_MINUS_INFINITY and ossNaN variables.
When specified globally, this directive expects an absolute reference for a REAL type that requires OssDecimal representation. If specified globally without an absolute reference, OSS.DECIMAL sets the representation for all REAL types within its scope. When specified locally, this directive does not take any arguments and affects only the type it is placed next to.
NOTE: Constraining the base of a REAL type to 2 implies the binary representation, which is represented as a double. Constraining the base to 10 implies the decimal representation, which is represented as the ASN.1/C++ OssDecimal class.
WARNING: double is the default representation because OSS determined that this is what most users want. However, this is inconsistent with the ASN.1 standard, which implies that values encoded in base 10 must be represented in a format suitable for base 10 and values encoded in base 2 must be represented in a format suitable for base 2. This is to prevent loss of precision when converting to and from their floating point representations. To ensure no loss of precision occurs, constrain REAL types to base 2 or base 10.
The following example demonstrates using OSS.DECIMAL at the global and local levels.
--<OSS.DECIMAL>--
Module DEFINITIONS ::= BEGIN
Decimal ::= REAL (WITH COMPONENTS {..., base (10) } )
DecimalAlso ::= REAL (WITH COMPONENTS {..., base (2) } )
DecimalToo ::= REAL
DecimalOnceMore ::= REAL --<DECIMAL>--
END
When the syntax above is compiled, the following is generated in the .h file:
typedef OssDecimal Decimal; typedef OssDecimal DecimalAlso; typedef OssDecimal DecimalToo; typedef OssDecimal DecimalOnceMore;
The --<OSS.DECIMAL>-- global directive overrides the default representation of the base 2 constraint.
Instructs the compiler to use the definite or indefinite length form when encoding PDUs.
--<OSS.DEFINITE [absoluteReference]>--
--<OSS.INDEFINITE [absoluteReference]>--
absoluteReference refers to an ASN.1 component in the specification that is a PDU.
When specified globally, these directives require an absolute reference to the targeted PDU. If these directives are applied to non-PDU ASN.1 types there is no effect. When specified globally without an absolute reference, OSS.DEFINITE and OSS.INDEFINITE sets the type of length encoding for all PDUs in their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.
The TOED and LED BER encoders do not currently support the indefinite length form of encoding. On the other hand, all of the decoders (SOED, TOED, LED) do support the indefinite length form of encoding.
The following example illustrates local and global use of these directives. When compiled with the -soed option, the OSS.INDEFINITE directive sets a global default for indefinite length encoding. Consequently, ByteStream is encoded using the indefinite length form, since no other directives are applied to it. However, DataPacket will be encoded using the definite length form due to the local DEFINITE directive placed next to it. The directives do not affect the generated header file.
--<OSS.INDEFINITE>--
Module DEFINITIONS ::= BEGIN
ByteStream ::= OCTET STRING
DataPacket ::= SEQUENCE {
username IA5String,
userID INTEGER
} --<DEFINITE>--
END
The compiler uses the definite length form.
Instructs the compiler to generate a separate DTD (XML Data Type Definition) for a specified PDU. By default, no DTDs are produced by the ASN.1 Compiler unless the -dtd option is specified.
--<OSS.DTD [absoluteReference "NewName.dtd"]>--
absoluteReference refers to a PDU in the ASN.1 input for which to generate a separate XML DTD. NewName is an optional argument that specifies a filename for the generated DTD. Although the OSS.DTD directive can appear anywhere white space is allowed, the OSS prefix and a full absolute reference is required.
When the -dtd compiler option is specified, a DTD for each PDU in the input is generated into a separate file whose name is derived from that of the PDU.
NOTE: You can use DTDs to make XER output produced by encode() editable in a non-ASN.1-specific XML tool. Also, you can use the setXmlDTD() method of the OssControl class to have the encode() method generate a reference to your DTD in the produced XER encoding.
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
Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures. When OSS.ENCODABLE is applied to a CHOICE, SEQUENCE, or SET component, that component will be represented as an open type. Also, the type that would normally have been generated as a field in its class is generated as a typedef, which can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded. By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal forms.
--<OSS.ENCODABLE [absoluteReference]>--
When specified globally, this directive requires an absolute reference to the targeted CHOICE, SEQUENCE, or SET component. When specified locally, this directive does not take any arguments and affects only the type that it is placed next to.
Do not apply the OSS.ENCODABLE directive to a tagged type.
This directive does not work when PER is in use.
OSS.ENCODABLE is applied at the local level in the following syntax:
Module DEFINITIONS ::= BEGIN
A ::= SEQUENCE {
id [0] INTEGER,
data [1] OCTET STRING --<ENCODABLE>--
}
END
During compilation, the following is generated in the header file:
class OSS_PUBLIC A /* SEQUENCE */
{
public:
. . .
typedef OSS_INT32 id;
typedef OssOpen data;
A();
A(const A &);
A(id, const data &);
A & operator = (const A &);
int operator == (const A &) const;
int operator != (const A &) const;
id & get_id();
id get_id() const;
void set_id(id);
data & get_data();
const data & get_data() const;
void set_data(const data &);
. . .
};
typedef OssString A_data_encodable;
The class generated for the SEQUENCE uses OssOpen (open type) for the data component.
BOOLEAN types are encoded as numeric values of 0 and 1, instead of "true" and "false", when a GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instruction is present. This is useful for
--<OSS.ExerNumericBoolean [absoluteReference]>--
absoluteReference refers to the affected type.
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
Enables or disables decoder support for the rules of extensibility. At compile time, an internal flag is set that is associated with SEQUENCE, SET, and BIT STRING types.
--<OSS.EXTENSIBLE [absoluteReference]>--
--<OSS.INEXTENSIBLE [absoluteReference]>--
When specified globally, these directives can take an absolute reference, which refers to the affected BIT STRING, SEQUENCE, or SET type. If specified globally without an absolute reference, the OSS.EXTENSIBLE and OSS.INEXTENSIBLE directives determine how the decoder handles extensible elements. If specified locally, these directives do not take any arguments and affect only the type they are placed next to.
When decoding a PDU, consider the following rules of extensibility:
The OSS.EXTENSIBLE directive functions the same as the ASN.1 formal extension marker (...). You can use either the directive or the extension marker, but not both.
These directives do not affect C++ representation in the header file.
This example shows global and local use of the directives; the local OSS.INEXTENSIBLE overrides the global OSS.EXTENSIBLE for Sample1.Name2.
--<OSS.EXTENSIBLE>--
Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
Name1 ::= SEQUENCE {
a INTEGER,
b VisibleString
}
Name2 ::= SET {
c INTEGER,
d VisibleString
} --<INEXTENSIBLE>--
END
The OSS.INEXTENSIBLE directive is implied.
Affects how unknown values of extensible CHOICE types with a final XER USE-TYPE encoding instruction are decoded. Each unknown value contains the xsi:type attribute with an unrecognized value.
--<OSS.ExtensibleUseType>--
By default, the CHOICE data described above is decoded as data that matches the first alternative; all unknown elements or attributes are ignored. When OSS.ExtensibleUseType is present, the decoder treats such data as an unknown extension rather than a value of the first CHOICE alternative. If the input ASN.1 specification was compiled with the -relaySafe option, the entire XML sub-element that matches the unknown extension is preserved in the special "unknown alternative" field by the decoder and can be safely relayed to other parties. If -relaySafe was not used, the entire XML sub-element is skipped and the decoded CHOICE type indicates the use of an unknown alternative.
This directive is useful when dealing with unknown elements and attributes from the USE-TYPE content model at a low level. The decoder skips them by default, so to analyze such data, use the -relaySafe option and apply OSS.ExtensibleUseType to the CHOICE type to access the encoded XML data.
ASN.1 specification
Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
T ::= [USE-TYPE] CHOICE {
base SEQUENCE {i INTEGER},
e1 SEQUENCE {i INTEGER, b BOOLEAN},
...
} --<ExtensibleUseType>--
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
GLOBAL-DEFAULTS CONTROL-NAMESPACE
"http://www.w3.org/2001/XMLSchema-instance" PREFIX "xsi"
END
Example XML document
<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4"> <i>1</i> <j>2</j> </T>
Decoding the above XML produces different results depending on whether ExtensibleUseType and -relaySafe are used:
value T ::= base :
{
i 1
}value T ::= <unknown>
and the decoded CHOICE value contains the following data:
choice == 0
value T ::= <unknown>and the decoded CHOICE value contains the following data:
choice == ossUnknownAlt_chosen
u.ossUnknownAlt contains
<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
<i>1</i>
<j>2</j>
</T>Instructs the ASN.1 Compiler to generate a specific name for a field in a class or for a user-defined type. By default, elements in a class and user-defined types have names derived from their ASN.1 notation.
--<OSS.FIELDNAME [absoluteReference] [newName]>--
--<OSS.TYPENAME [absoluteReference] [newName]>--
newName is a valid C++ identifier.
Use OSS.FIELDNAME to specify the name of a SET, SEQUENCE, or CHOICE component to be generated in the header file, instead of one derived by default from the component's ASN.1 identifier.
Use OSS.TYPENAME to specify the name of a user-defined type to be generated in the header file, instead of one derived from the ASN.1 input by default.
When specified globally, these directives require an absolute reference that refers to the ASN.1 component to be renamed in the generated header file, along with newName. When specified locally, only newName is needed, enclosed in quotation marks.
NOTE: These directives have an absolute effect: the ASN.1 Compiler will not change the specified names, even if they are invalid. If the name you specify conflicts with one that the compiler derived from an ASN.1 identifier or type reference, the compiler alters that other name.
The following ASN.1 illustrates local and global use of these directives:
--<OSS.TYPENAME Module.RenamedStr "asciiStr">--
Module DEFINITIONS ::= BEGIN
DefaultName ::= [1] SET OF INTEGER
RenamedInt ::= [2] SET OF INTEGER
DefaultStruct ::= [3] SEQUENCE {
lunchPrepared BOOLEAN,
cost REAL
}
RenamedStruct ::= [4] SEQUENCE {
lunchPrepared BOOLEAN --<FIELDNAME "lunchReady">--,
cost REAL
}
DefaultNameStr ::= [5] IA5String
RenamedStr ::= [6] IA5String
END
When ASN.1-compiled, the following is generated in the header file:
class OSS_PUBLIC __shared1 : public OssList /* SET OF */
{
public:
typedef OSS_INT32 component;
. . .
};
typedef __shared1 DefaultName;
typedef __shared1 RenamedInt;
class OSS_PUBLIC DefaultStruct /* SEQUENCE */
{
public:
. . .
typedef ossBoolean lunchPrepared;
typedef double cost;
DefaultStruct();
DefaultStruct(const DefaultStruct &);
DefaultStruct(lunchPrepared, cost);
DefaultStruct & operator = (const DefaultStruct &);
int operator == (const DefaultStruct &) const;
int operator != (const DefaultStruct &) const;
lunchPrepared & get_lunchPrepared();
lunchPrepared get_lunchPrepared() const;
void set_lunchPrepared(lunchPrepared);
cost & get_cost();
cost get_cost() const;
void set_cost(cost);
. . .
};
class OSS_PUBLIC RenamedStruct /* SEQUENCE */
{
public:
. . .
typedef ossBoolean lunchReady;
typedef double cost;
RenamedStruct();
RenamedStruct(const RenamedStruct &);
RenamedStruct(lunchReady, cost);
RenamedStruct & operator = (const RenamedStruct &);
int operator == (const RenamedStruct &) const;
int operator != (const RenamedStruct &) const;
lunchReady & get_lunchReady();
lunchReady get_lunchReady() const;
void set_lunchReady(lunchReady);
cost & get_cost();
cost get_cost() const;
void set_cost(cost);
. . .
};
typedef OssString DefaultNameStr;
typedef OssString asciiStr;
Causes the specified ASN.1 open type to be represented by the OssOpen class. By default, the C++ representation of an ASN.1 open type depends on the constraints applied to it.
--<OSS.GenericOpenType absoluteReference>--
--<OSS.GenericOpenType Module.S.value>--
Module DEFINITIONS ::= BEGIN
C ::= CLASS {
&code INTEGER,
&Type
}
Object C ::= {
{ &code 1, &Type INTEGER } |
{ &code 2, &Type UTF8String }
}
S ::= SEQUENCE {
key C.&code ({Object}),
value C.&Type ({Object}{@key})
}
END
During ASN.1 compilation of the notation above, the following is generated in the header file:
class OSS_PUBLIC S /* SEQUENCE */
{
public:
void * operator new(size_t size);
void operator delete(void *ptr);
typedef OSS_INT32 key;
typedef OssOpen value;
. . .
};
Applies the OssHugeInt representation to integers whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine-dependent integers.
--<OSS.HUGE [absoluteReference]>--
When specified globally, absoluteReference refers to an INTEGER that requires the OssHugeInt representation. Also, when OSS.HUGE is applied globally with no parameters, it applies to all integers in the schema. When specified locally, OSS.HUGE takes no operands and affects only the type it is placed next to.
When an INTEGER type with OSS.HUGE applied is constrained to be non-negative, a type value is treated as an unsigned number rather than as a two's complement binary integer. For the BER/DER encoder, this ensures that unsigned HUGE INTEGER values are encoded correctly by prepending an extra 0 octet when the high order bit of the value is 1.
Value constraints on an INTEGER type with OSS.HUGE applied cannot exceed a 64-bit integer as the ASN.1 compiler will issue an error message.
HugeInt DEFINITIONS ::=
BEGIN
A ::= INTEGER --<HUGE>--
END
ASN.1-compiling the ASN.1 notation above generates the following code in the header file:
typedef OssHugeInt A;
Specifies one or more configuration files, containing global compiler directives, to be inserted where OSS.INCLUDES is specified. This is useful when defining different sets of compiler directives to be included or excluded, depending on the application.
--<OSS.INCLUDES "configFilename"[, "configFilename"...]>--
This directive can only be specified globally and requires at least one configuration filename; the configuration file specified can contain only global directives.
If a directive in a configuration file conflicts with a directive that is defined either in another configuration file or within the ASN.1 module, the last directive (scanning left to right, top to bottom) takes precedence. All directives defined within an ASN.1 source or INCLUDES file take precedence over those defined in the asn1dflt file.
Directives obtained from a configuration file read by OSS.INCLUDES override any conflicting directives in the asn1dflt file.
When the following example is compiled, directives from file1.cfg and file2.cfg are inserted at the location of the OSS.INCLUDES directive. The OSS.INCLUDES directive is not mentioned in the generated header file.
--<OSS.INCLUDES "file1.cfg", "file2.cfg" >--
Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
Name1 ::= INTEGER
Name2 ::= BOOLEAN
END
Use this helper directive when an OSS.DataCallback directive is applied to a type that occurs in multiple locations in a message.
--<OSS.InfoCallback [absoluteReference] ["]MethodName["]>--
MethodName is the user-defined name for the callback method.
For the following ASN.1
M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Subscriber ::= SEQUENCE {
name VisibleString,
company Company,
homeAddress Address
}
Company ::= SEQUENCE {
name VisibleString,
address Address
}
Address ::= SEQUENCE {
zipcode INTEGER( 0..99999 ),
addressline VisibleString( SIZE (1..64) )
}
END
a directive such as
--<OSS.DataCallback M.Address.zipcode "myZipcode">--
would cause myZipcode() to be called for both Subscriber.homeAddress.zipcode and Company.address.zipcode, but myZipcode() would be unable to differentiate the two fields. OSS.InfoCallback offers a way. By employing
--<OSS.InfoCallback M.Subscriber.homeAddress "homeAddressField">--
you instruct the compiler to generate a prototype for the homeAddressField() callback method inside the <module_name>_Callback class. This method, which you provide, is called by the decoder twice: once before starting the partial decoding of the homeAddress field and again after finishing its decoding.
Identifies those types or components for which constraint checking should be disabled. The directive turns off all constraint checking for the type, which includes checking the default permitted alphabet for character strings. For ENUMERATED types, OSS.NoConstrain disables subtype constraints but does not disable enumerator validation. By default, constraint checking is turned on.
--<OSS.NoConstrain [absoluteReference]>--
When specified globally, absoluteReference refers to an ASN.1 type with a defined constraint. OSS.NoConstrain cannot be specified locally.
OSS.NoConstrain has no effect if -constraint is explicitly specified, except in the following situations:
Provided -constraint is not specified for the following example, all constraints for S are disabled and S will behave as a simple INTEGER.
--<OSS.NoConstrain Module.S>--
Module DEFINITIONS ::= BEGIN
S ::= INTEGER (1..10 | 300)
END
In this example, PrintableString abc is passed at run-time without issuing a constraint violation error. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because it is composed of types that have OSS.NoConstrain applied.
--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
Mod DEFINITIONS ::= BEGIN
ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
abc ABConly ::= "The wrong string"
ShortString ::= PrintableString (SIZE(1 | 3 ))
shStr ShortString ::= "The long string"
ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
shABC ShortABCs ::= "ABCDD"
END
For the following example, automatic encoding and decoding will not be performed at run-time even if the -constraint option is specified on the command line:
--<OSS.NoConstrain ContConstr.O>--
ContConstr DEFINITIONS::= BEGIN
O ::= OCTET STRING (CONTAINING INTEGER)
END
Informs the ASN.1 Compiler that items with the ASN.1 DEFAULT tag shall be handled as if they have the OPTIONAL tag instead. By default, types with the DEFAULT tag use the specified default value when absent from the encoding.
--<OSS.NODEFAULTVALUE [absoluteReference]>--
When specified globally, absoluteReference can be present and refers to an ASN.1 type with a DEFAULT tag. When specified globally without an operand, the OSS.NODEFAULTVALUE directive affects all types with the DEFAULT tag. When specified locally, the OSS.NODEFAULTVALUE directive takes no operands and affects only the type that it is placed next to.
--<OSS.NODEFAULTVALUE Module.DataCard.a>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a [0] BOOLEAN DEFAULT TRUE,
b [1] BOOLEAN DEFAULT TRUE,
c [2] BOOLEAN
}
END
When ASN.1-compiling the above notation, the following is generated in the header file. Note that a is represented as an OPTIONAL component because OSS.NODEFAULTVALUE is applied to it. On the other hand, b is still handled as a component with a default value.
class OSS_PUBLIC DataCard /* SEQUENCE */
{
public:
. . .
typedef ossBoolean a;
typedef ossBoolean b;
typedef ossBoolean c;
static const b default_b;
static b get_default_b();
DataCard();
DataCard(const DataCard &);
DataCard(a, b, c);
DataCard(c);
DataCard & operator = (const DataCard &);
int operator == (const DataCard &) const;
int operator != (const DataCard &) const;
a *get_a();
const a *get_a() const;
void set_a(a);
int a_is_present() const;
void omit_a();
b *get_b();
const b *get_b() const;
void set_b(b);
int b_is_default() const;
void set_default_b();
c & get_c();
c get_c() const;
void set_c(c);
. . .
};
Instructs the compiler to not generate decoder or encoder routines for the operand of the directive when using the Time-Optimized Encoder/Decoder.
--<OSS.NOENCODE [absoluteReference]>--
--<OSS.NODECODE [absoluteReference]>--
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:
NOTES:
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.
By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.
When you use the Space-Optimized Encoder and Decoder, the OSS.NOENCODE and OSS.NODECODE directives have no effect.
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.
--<OSS.PDU [absoluteReference]>--
--<OSS.NOPDU [absoluteReference]>--
When specified globally, absoluteReference specifies the ASN.1 components that the directive will be applied to. When specified globally without an operand, the OSS.PDU and OSS.NOPDU directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.
The OSS.PDU and ASN1.PDU directives only affect types contained in root modules. To treat all input modules as root modules, either specify the -root compiler option or add the global OSS.ROOT directive in your ASN.1 specification.
--<OSS.PDU Module.NameString>--
Module DEFINITIONS ::= BEGIN
MiddleAgeClubCard ::= SEQUENCE {
name NameString,
phoneNumber PhoneString,
age AgeInt
}
NameString ::= IA5String (SIZE (40))
PhoneString ::= NumericString (SIZE (15)) --<PDU>--
AgeInt ::= INTEGER (45..54)
END
When the notation above is ASN.1-compiled, the following is generated in the header file:
typedef OssString NameString;
typedef OssString PhoneString;
typedef OSS_UINT32 AgeInt;
class OSS_PUBLIC MiddleAgeClubCard /* SEQUENCE */
{
. . .
};
/* Universal PDU class */
class OSS_PUBLIC sample_PDU : public UniversalPDU {
public:
sample_PDU();
void set_MiddleAgeClubCard(MiddleAgeClubCard &);
MiddleAgeClubCard *get_MiddleAgeClubCard() const;
void set_NameString(NameString &);
NameString *get_NameString() const;
void set_PhoneString(PhoneString &);
PhoneString *get_PhoneString() const;
. . .
};
/* Specific PDU classes */
class OSS_PUBLIC MiddleAgeClubCard_PDU : public ConcretePDU {
public:
MiddleAgeClubCard_PDU();
void set_data(MiddleAgeClubCard &);
MiddleAgeClubCard *get_data() const;
. . .
};
class OSS_PUBLIC NameString_PDU : public ConcretePDU {
public:
NameString_PDU();
void set_data(NameString &);
NameString *get_data() const;
. . .
};
class OSS_PUBLIC PhoneString_PDU : public ConcretePDU {
public:
PhoneString_PDU();
void set_data(PhoneString &);
PhoneString *get_data() const;
. . .
};
Instructs the compiler to generate ownership-transferring functions for a component of a type used as a component of a constructed type (i.e., SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF). For OSS.POINTER, this component is represented internally by a pointer to the value, which eliminates excessive copying of large memory blocks. By default, memory for a component is allocated inline, within the container, as is the case with OSS.NOPOINTER.
--<OSS.POINTER [absoluteReference]>--
--<OSS.NOPOINTER [absoluteReference]>--
When specified globally, absoluteReference specifies the ASN.1 component that the directive will be applied to. When specified globally without an operand, the OSS.POINTER and OSS.NOPOINTER directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.
These directives have no effect on the following types: BOOLEAN, ENUMERATED, INTEGER, NULL, REAL, and the GeneralizedTime, UTCTime, and ISO 8601 time types. Nothing is gained by having ownership-transferring functions for these types because their values copy as fast as, or faster than, pointers are copied.
Unlike in ASN.1/C, OSS.POINTER and OSS.NOPOINTER do not affect the representation of the type itself. These directives are effective only when the type is used as a component of a constructed type.
--<OSS.POINTER>--
--<OSS.NOPOINTER Module.InlineGlobal>--
Module DEFINITIONS ::= BEGIN
InlineLocal ::= [1] IA5String --<NOPOINTER>--
InlineGlobal ::= [2] IA5String
PointeredGlobal ::= [3] IA5String
Sequence ::= SEQUENCE {
a InlineLocal,
b InlineGlobal,
c PointeredGlobal
}
END
When the notation above is ASN.1-compiled, the following is generated in the header file. Notice how the local OSS.NOPOINTER directive overrides the global OSS.POINTER directive.
typedef OssString InlineLocal;
typedef OssString InlineGlobal;
typedef OssString PointeredGlobal;
class OSS_PUBLIC Sequence /* SEQUENCE */
{
public:
. . .
typedef OssString a;
typedef OssString b;
typedef OssString c;
. . .
a & get_a();
const a & get_a() const;
void set_a(const a &);
b & get_b();
const b & get_b() const;
void set_b(const b &);
c & get_c();
const c & get_c() const;
void set_c(const c &);
void set_c(c *);
c *release_c();
private:
a a_field;
b b_field;
c *c_field;
};
Identifies the ASN.1 module(s) that is used as the root module(s). In a root module, all unreferenced types are considered PDUs. Also, non-root modules exist only to supply external references to root modules. By default, the last ASN.1 input file specified on the command-line contains the root module.
--<OSS.ROOT [moduleName[{objectIdentifier}] ...]>--
OSS.ROOT can only be specified globally and takes one or more operands to identify ASN.1 modules. The operand can be a module reference (moduleName), or a module reference followed by a built-in objectIdentifier value. If no operands are provided, all input modules are considered root modules.
--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--
Instructs the compiler to generate a sample application containing code for the specified PDU types and value references, providing more control over the sample code being created than -sampleCode does. There can be more than one OSS.SampleCode directive in the ASN.1 input.
OSS.SampleCode accepts two different syntax formats, as follows:
--<OSS.SampleCode [pdus] | [values] | [absoluteReference]>--
Use this format to select PDU types and value references for inclusion in the sample code. When absoluteReference is present, it refers to a PDU type, an ASN.1 module, or a PDU value reference; otherwise, the directive is ignored. The pdus and values parameters are accepted only when the directive is specified globally and is applied to an ASN.1 module or to all ASN.1 input; no absoluteReference is specified.
--<OSS.SampleCode count:number | selection [absoluteReference]>--
Use this format to control how the compiler creates sample values for some ASN.1 types.
count:number refers to the entire ASN.1 syntax, an ASN.1 module, or a SEQUENCE OF/SET OF type. number designates how many items the compiler can use to create values for SEQUENCE OF/SET OF types in the sample code. If count:number is not specified for a SEQUENCE OF/SET OF type, the number of items defaults to 1.
selection refers to a CHOICE alternative used by the compiler when creating values for the matching CHOICE type in the sample code. If selection is not specified for a CHOICE type, the first CHOICE alternative is used by default. If several directives are assigned to different alternatives of the same CHOICE type, the compiler creates as many sample values as needed to cover all the selected alternatives.
Use the OSS.NoSampleCode directive to exclude PDU types and value references from the sample application. It has the following format:
--<OSS.NoSampleCode [absoluteReference]>--
When absoluteReference is present, it refers to a PDU type, an ASN.1 module, or a PDU value reference; otherwise, the directive is ignored. The pdus and values parameters are accepted only when the directive is specified globally and is applied to an ASN.1 module or to all ASN.1 input; no absoluteReference is specified.
When OSS.SampleCode is applied to the entire ASN.1 input, it has the same effect as the -sampleCode command-line option.
The -noSampleCode command-line option overrides all OSS.SampleCode directives.
The -sampleCode command-line option overrides all OSS.NoSampleCode directives.
For the following ASN.1 syntax, the compiler generates sample code for all value references, except those defined in Module2:
--<OSS.ROOT>-- --<OSS.SampleCode values>-- --<OSS.NoSampleCode Module2>-- Module1 DEFINITIONS ::= BEGIN A ::= OCTET STRING value1 A ::= '00'H END Module2 DEFINITIONS ::= BEGIN B ::= INTEGER value2 B ::= 1 END
The following ASN.1 syntax demonstrates custom generation of sample values:
--<OSS.SampleCode pdus Module>--
--<OSS.SampleCode selection Module.S.b>--
Module DEFINITIONS ::= BEGIN
S ::= CHOICE {
a IA5String,
b SEQUENCE --<SampleCode count:3>-- OF INTEGER
}
END
The compiler creates the sample application containing test code for the following value:
samplevalue1-S S ::= b : {
0,
0,
0
}
Instructs the compiler to mark affected types with a special flag in the control table. When this flag is found at runtime, the E-XER decoder attempts to preserve the wildcard body in the decoded value exactly as it was in the original XML document.
--<OSS.SelfCompleteWildcard [absoluteReference>]--
OSS.SelfCompleteWildcard can be applied to types with a final XER ANY-ELEMENT encoding instruction. It can be specified for a single type, for a module, or globally.
When decoding using the EncodedBuffer class, the wildcard contents are copied directly to the output value. When decoding using EncodedFile or EncodedSocket, the decoder can reconstruct the outermost tag of a wildcard, performing whitespace normalization within it and declaring all namespaces before all attributes. In either case, the following is true:
If the wildcard contents were normalized according to the W3C Canonical XML specification, the decoded wildcard value will match the original XML value, which enables post-decoding validation of the wildcard's digital signature.
You can use OSS.SelfCompleteWildcard to speed up E-XER decoding of wildcards if you know in advance that they self-complete and do not use namespace or entity declarations from the outer XML document.
--<OSS.SelfCompleteWildcard M.Root.w>--
M DEFINITIONS XER INSTRUCTIONS ::= BEGIN
Root ::= SEQUENCE {
w [ANY-ELEMENT] UTF8String (CONSTRAINED BY {}) }
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
NAMESPACE ALL AS "urn:Root" PREFIX "r"
END
For the following XML document
<Root xmlns="urn:Root"> <n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/> </Root>
where n1:wildcard is an element wildcard, the decoder produces what is literally the original:
<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>
Without OSS.SelfCompleteWildcard the decoder produces:
<n1:wildcard xmlns:n2="urn:n2" xmlns:n1="urn:n1" xmlns="urn:Root" n2:at2="2" n1:at1="1"/>
These directives determine the representation of INTEGER types. Representations for a typical system are shown in the following table:
| Directive | Representation | Notes |
|---|---|---|
| OSS.SHORT | 16-bit | |
| OSS.INT | 32-bit | 16-bit on older operating systems such as MS-DOS |
| OSS.LONG | 32-bit | |
| OSS.LONGLONG | 64-bit | Same as OSS.LONG (32-bit) on platforms that do not support 64 bit INTEGERs |
By default, when no subtype constraints are present, the OSS.INT directive is implied. When a subtype constraint is present, the compiler chooses the smallest representation able to carry all required values.
--<OSS.SHORT [absoluteReference]>--
--<OSS.INT [absoluteReference]>--
--<OSS.LONG [absoluteReference]>--
--<OSS.LONGLONG [absoluteReference]>--
When specified globally, only INTEGERs without subtype constraints are affected. absoluteReference refers to an ASN.1 INTEGER type. When specified globally without an absolute reference, OSS.SHORT, OSS.INT, OSS.LONG, and OSS.LONGLONG set the default for all INTEGER types within their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to. They also override any choices that the ASN.1 compiler would have made based on a subtype constraint.
When no subtype constraints are present, the OSS.INT directive is implied. When a subtype constraint is present, the compiler chooses the smallest representation able to carry all required values.
Neither the Time-Optimized Encoder/Decoder nor the Lean Encoder/Decoder supports OSS.SHORT, OSS.INT, or OSS.LONG; these directives can be used only with the -soed compiler option. When constraints are applied to INTEGER types and the ?soed compiler option is used, 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).
When the -lean or -toed (default) option is used, the ASN.1/C++ compiler generates 32-bit integers, along with 64-bit integers if OSS.LONGLONG is specified.
If a platform does not support 64-bit integers, the OSS.LONG and OSS.LONGLONG directives have the same effect.
--<OSS.SHORT>--
--<OSS.INT Module.GlobalINTInt>--
Module DEFINITIONS ::= BEGIN
GlobalDefaultInt ::= INTEGER
GlobalINTInt ::= INTEGER
LONGInt ::= INTEGER --<LONG>--
LONGLONGInt ::= INTEGER --<LONGLONG>--
END
During compilation of the above syntax, the following is generated in the header file:
typedef short int GlobalDefaultInt; typedef int GlobalINTInt; typedef long int LONGInt; typedef LONG_LONG LONGLONGInt;
Although OSS.SHORT set the global default representation for INTEGER types, only GlobalDefaultInt was affected. The representations of the GlobalINTInt, LONGInt, and LONGLONGInt INTEGER types were set by OSS.INT, OSS.LONG, and OSS.LONGLONG respectively.
Instructs the compiler to omit certain letters from long names so they are less than 31 characters in length in the header file. The directive accommodates maximum name length requirements that exist on some C++ compilers. The OSS ASN.1/C++ Compiler insures that all shortened names are unique by adding _# suffixes, when necessary. By default, name shortening is turned off.
--<OSS.SHORTENNAMES [shortenToLength]>--
This directive can only be specified globally. The optional shortenToLength operand is an integer that specifies the length (16 or greater) that long variable names will be shortened to. When no operands are specified, all long names in the ASN.1 input are shortened to 31 characters.
--<OSS.SHORTENNAMES>-- Mod DEFINITIONS ::= BEGIN WeWereTryingToThinkOfaNameButWeCouldNotFindaSuitableOne ::= INTEGER NormalName ::= BOOLEAN END
When the above syntax is ASN.1-compiled, the following is generated in the .h file:
typedef int WWTTTONBWCNFSOn; typedef ossBoolean NormalName;
Gives you more control over the XML stylesheets produced by the ASN.1 compiler. This directive instructs the ASN.1 compiler to generate a separate XML stylesheet with your specified filename for any PDU. By default, unless the -xsl option is specified, stylesheets are not produced. When -xsl is specified, a stylesheet for each input PDU is generated into a separate file with a name derived from that PDU.
--<OSS.Stylesheet [absoluteReference [OptionalNewName.xsl]]>--
absoluteReference refers to any PDU in the input ASN.1 that you want to generate a separate XML stylesheet for. When absoluteReference is not specified, a stylesheet is generated for every PDU in the input.
Stylesheets can be used to make the XER output of the encode() method more visually appealing when viewed in a web browser.
You can use the setXmlStylesheet() method of OssControl to have the encode() method generate a reference to your stylesheet in the produced XER encoding.
The OSS.Stylesheet directive can appear anywhere white space is allowed; however, the OSS prefix and an absolute reference is required.
For the following syntax, two separate stylesheet files are generated: StringType.xsl and AnotherNameForInt.xsl. Each contains default browser style information for their respective PDUs.
--<OSS.Stylesheet XModule.StringType>--
--<OSS.Stylesheet XModule.IntType "AnotherNameForInt.xsl">--
XModule DEFINITIONS ::= BEGIN
StringType ::= UTF8String
IntType ::= INTEGER
studentName ::= <StringType>John H. Doe</StringType>
studentAge ::= <IntType>23</IntType>
END
Disables printing of specific informatory and warning messages. This is useful when compiling abstract syntaxes that are known to contain specifications that do not comply with the ASN.1 standard. By default, informatory and warning messages are suppressed when -noRelaxedMode is turned on.
--<OSS.SUPPRESS messageID[, messageID ...]>--
messageID identifies the message to be suppressed. It can be the full message identifier, such as A0178W, or only its numeric portion: 178. OSS.SUPPRESS can only be used globally and can take one or more messageIDs.
In the following example, message A0178W warns that the first digit of a number in a module definition should be non-zero:
--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN
Age ::= INTEGER
legalAge Age ::= 021
END
Note that the OSS.SUPPRESS directive does not affect the C++ representation. Its only effect is to suppress the following warning message:
"filename.asn", line 4 (Sample): A0178W: The first digit should not be zero unless the number is a single digit.
legalAge Age ::= 021
^
Instructs the compiler to represent UTF8String types in C++ as OssUniversalString types. By default, UTF8Strings are represented as OssStrings.
--<OSS.UNIVERSALSTRING [absoluteReference]>--
When specified globally, absoluteReference refers to some UTF8String in the ASN.1 syntax. OSS.UNIVERSALSTRING has no effect if specified globally without an operand. When specified locally, this directive takes no operands and affects only the type it is placed next to.
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--
Module DEFINITIONS ::= BEGIN
Default ::= [1] UTF8String
TwoByteLocal ::= [2] UTF8String --<BMPSTRING>--
FourByteGlobal ::= [3] UTF8String
FourByteLocal ::= [4] UTF8String --<UNIVERSALSTRING>--
END
ASN.1 compiling the above notation generates the following in the header file:
typedef OssString Default; typedef OssBMPString TwoByteLocal; typedef OssUniversalString FourByteGlobal; typedef OssUniversalString FourByteLocal;
These directives specify whether an initialized C++ object in the .cpp file and an associated extern statement in the .h file should be generated for each ASN.1 value reference. By default, OSS.VALUE is implied.
--<OSS.VALUE absoluteReference>--
--<OSS.NOVALUE absoluteReference>--
When specified globally, absoluteReference refers to an ASN.1 user-defined type used in a value reference. When specified globally without arguments, these directives set the default for all value references within their scope. When specified locally, no arguments are accepted and the directives affect only the value references they are placed next to.
The following ASN.1 notation shows local and global use of OSS.VALUE and OSS.NOVALUE. The local OSS.VALUE directive overrides the global OSS.NOVALUE directive):
--<OSS.NOVALUE Module.IdInt>--
Module DEFINITIONS ::= BEGIN
ASCIIStr ::= IA5String
name ASCIIStr ::= "John"
age INTEGER --<SHORT>-- ::= 57
IdInt ::= INTEGER
idNumAbsent IdInt ::= 767543
idNumPresent IdInt --<VALUE>-- ::= 354876
END
When the above syntax is passed through the compiler, the following is generated in the header file:
/* External definitions for named values */
extern OSS_PUBLIC const OssString& name;
const short age = 57;
const int idNumPresent = 354876;
In addition, extern constant references are initialized in the .cpp file. Notice that there is neither an extern object nor any initialization for idNumAbsent.
This documentation applies to release 7.3 and later of the OSS® ASN.1 Tools for C++.
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.