TOP

Getting Started

Applies to: ASN.1/C++ 6.5

Software Distribution

The OSS ASN.1 Tools for C++ is available in three different distributions: compiler-only, target (runtime only), and development (full).

The compiler-only distribution includes only the OSS ASN.1 Compiler; since the runtime libraries are missing, the compiler-only software cannot produce an executable program. It can be used to

  • Compile your ASN.1 specification for use on the same type platform as that on which the compiler is running.
  • Cross-compile, which is compiling ASN.1 specifications on one computer platform to obtain .cpp and .h files for use on another platform, to any other platform for which you are licensed to use the run-time libraries.

The target distribution includes the OSS Runtime libraries only. The OSS ASN.1 compiler is missing, so the target software cannot compile your ASN.1 specification. It can only be used for runtime support on the target platform where your application using the encoder/decoder is run.

The development distribution is a combination of the compiler-only and target distributions. It includes both the OSS ASN.1 Compiler and the Runtime libraries. The development software can be used to compile your ASN.1 specification for use on the same type of platform as that on which the compiler is running, or to cross-compile to any other platform for which you are licensed to use the runtime libraries. Since the runtime libraries are included, the development software can also be used for runtime support on the target platform where your application using the encoder/decoder is run.

Skill Set

To fully utilize the OSS ASN.1 Tools, learn to do the following:

  1. Install the OSS ASN.1 Tools on your platform.
  2. Perform a basic sanity test to make sure that the installation was successful. This can easily be done by running the makefiles that are found in the samples directory.
  3. Compile your ASN.1 specifications using the OSS ASN.1 Compiler to produce header files and control-table/code files to include in your application.
  4. Fill the data structures that the ASN.1 Compiler generates in the header file to represent your ASN.1 specification.
  5. Issue calls to instantiated OSS API class methods from within your application source code to encode/decode your application messages and perform auxiliary operations.
  6. C++-compile your application code along with ASN.1 Compiler-generated .cpp and .h files, using your C++ compiler.
  7. Link your application code with the OSS ASN.1 Runtime libraries, either statically or dynamically, to produce executable code that uses the OSS ASN.1 libraries for encoding/decoding and related tasks.

Compiling an ASN.1 Module

The ASN.1 Compiler translates your ASN.1 specifications into C++ objects that you can use to encode application messages and decode messages. Just pass ASCII text files containing your specifications to the ASN.1 Compiler as command-line arguments. These files typically have a .asn extension.

You can ASN.1-compile using either the command-line ASN.1 Compiler or ASN.1 Studio. Command-line compiling uses this general form:

asn1cpp ASN.1_input_file(s) [commandLineOption(s)] 

where asn1cpp[.exe] is the name of the compiler executable file, ASN.1_input_file(s) specifies one or more .asn files that contain the ASN.1 input modules, and commandLineOption(s) can be one or more dash-prefixed compiler-configuration options.

For example, to compile the bcas.asn file located in the samples/basic/decode and samples/basic/encode directories, issue the following command:

asn1cpp bcas.asn -ber -per -exer

This generates the following files:

  • bcas.h is the header file containing the C++ class and method definitions required to represent the ASN.1 specification contained in bcas.asn. To use the produced classes, #include this .h file in your application code.
  • bcas.cpp is the file used by the OSS API functions to correctly encode/decode the values you store in the compiler-generated data structures found in bcas.h. This file contains the generated C++ code for the generated classes in bcas.h, as well as the code used by the encoder/decoder.

NOTES:

  • To generate C++ representations for all types in all input modules, either specify the -root command-line option when ASN.1-compiling or add the global OSS.ROOT compiler directive to the beginning of your specification. Normally, only representations for the last input ASN.1 module are generated into the produced header file.
  • The order of the input files on the command-line can be important. Place files that contain global compiler directives (e.g., asn1dflt files) before all ASN.1 input files. Also, place files that contain definitions referenced by other files first (left to right on the command line). For example, if the myModules.asn file references macro definitions in macro.asn, you would invoke the compiler as:
    asn1cpp macro.asn myModules.asn

Using the ASN.1/C++ Compiler Output

The ASN.1 Compiler output consists of two files:

  • <module name>.h contains the class definitions that you will manipulate directly. It is essential that you become familiar with the details of this file.
  • <module name>.cpp is used by the OSS API to properly encode and decode your application messages using the standard ASN.1 encoding rules. For the most part, you do not need to know about the contents of the *.cpp files.

The OSS ASN.1 Compiler generates class definitions in the target C++ language based on the input ASN.1 notation. See C++ Representation of ASN.1 Notation for details about the rules used by the ASN.1 Compiler to produce C++ classes. These classes can be later referenced by the application program.

For example, when the following ASN.1 syntax is passed to the ASN.1/C++ Compiler:

-- Baseball Card Abstract Syntax (BCAS) 

BBCard ::= SEQUENCE {
        name IA5String (SIZE (1..60)),
        team IA5String (SIZE (1..60)),
        age INTEGER (1..100),
        position IA5String (SIZE (1..60)),
        handedness ENUMERATED
                {left-handed(0), right-handed(1), ambidextrous(2)},
        batting-average REAL
}

a bcas.h header file is generated that contains the following:

#include "oss.h"
#include "asn1.h"

/* Representation types */

enum _enum1 {
    left_handed = 0,
    right_handed = 1,
    ambidextrous = 2
};

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

    typedef OssString name;
    typedef OssString team;
    typedef OSS_UINT32 age;
    typedef OssString position;
    typedef enum _enum1 handedness;
    typedef double batting_average;

    BBCard();
    BBCard(const BBCard &);
    BBCard(const name &, const team &, age, const position &, handedness, batting_average);

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

    name & get_name();
    const name & get_name() const;
    void set_name(const name &);

    team & get_team();
    const team & get_team() const;
    void set_team(const team &);

    age & get_age();
    age get_age() const;
    void set_age(age);

    position & get_position();
    const position & get_position() const;
    void set_position(const position &);

    handedness & get_handedness();
    handedness get_handedness() const;
    void set_handedness(handedness);

    batting_average & get_batting_average();
    batting_average get_batting_average() const;
    void set_batting_average(batting_average);
private:
    name name_field;
    team team_field;
    age age_field;
    position position_field;
    handedness handedness_field;
    batting_average batting_average_field;
};

/* Universal PDU class */

class OSS_PUBLIC bcas_PDU : public UniversalPDU {
public:
    bcas_PDU();
    void set_BBCard(BBCard &);
    BBCard *get_BBCard() const;
#ifdef OSS_PREALLOCATED_BUFFER_DECODE_SUPPORTED
    void set_const_BBCard(const BBCard &);
    const BBCard *get_const_BBCard() const;
#endif
};

/* Specific PDU classes */

class OSS_PUBLIC BBCard_PDU : public ConcretePDU {
public:
    BBCard_PDU();
    void set_data(BBCard &);
    BBCard *get_data() const;
#ifdef OSS_PREALLOCATED_BUFFER_DECODE_SUPPORTED
    void set_const_data(const BBCard & d);
    const BBCard *get_const_data() const;
#endif
protected:
    OssTypeIndex get_index() const;
};

/* Control object class */

class OSS_PUBLIC bcas_Control : public OssControl {
public:
    bcas_Control();
    bcas_Control(const bcas_Control &);
};

In the first two statements, oss.h and asn1.h are header files needed for a clean compilation of the output code. These files are located in the include subdirectory of the OSS ASN.1 Tools for C++ installation.

Following these statements are class definitions and type declarations you can use to create instantiated objects for encoding, decoding, viewing, or manipulating.

To use the ASN.1 Compiler output in your application, explicitly #include the generated header file in your application code:

#include "bcas.h"

where bcas.h is the file location of the generated header file.

Using the OSS ASN.1/C++ API Routines

Once you have successfully compiled your ASN.1 specification, you can begin to initialize your environment and instantiate the objects to be used by your application. Then, you can fill the created objects and data-structures with your application data for encoding, decoding, viewing, or manipulating via the provided routines. To learn how this is done, see this comprehensive example.

Switching Between the Encoders/Decoders

OSS provides three types of encoders/decoders:

  • Space-Optimized
  • Time-Optimized
  • Lean (available separately)

The application program interface for the three types of encoders/decoders is identical. You can use any of the available encoders/decoders without having to modify your application.

To use a particular encoder, explicitly link your application with one of the runtime library files in the lib subdirectory of the Tools. By default, the ASN.1 Compiler produces output suitable for use with the Time-Optimized Encoder/Decoder, which is the fastest encoder/decoder.

Specify the –lean compiler option to generate output suitable for use with the Space-Optimized or Lean Encoder/Decoder. You can switch between them just by linking with the corresponding encoder/decoder library (SOED or LED). You do not need to recompile your application. However, if you want to use SOED-specific features that are not present in LED, recompile your input specification with the -soed option specified.

Compiler-generated TOED code is usually much bigger than the SOED/LED control table. To help exclude unneeded code from the resulting application, the ASN.1 Compiler puts some generated TOED code sections under #ifdef preprocessor directives, so they are compiled only when the user specifies the corresponding preprocessor symbol in the C++ compiler command line. For example, to print decoded PDU values using the ASN1Handle::print function and TOED is in use, specify –DOSSPRINT when compiling the generated TOED code; otherwise any call to ASN1Handle::print will fail. When no preprocessor symbols are defined, only encoding and decoding routines without debugging capabilities are compiled.

In practice, you will find that the Time-Optimized Encoder/Decoder is the best choice for applications that require fast processing times and the Lean Encoder/Decoder best for running under constrained environments, such as embedded systems with limited space. The Space-Optimized Encoder/Decoder is more appropriate for applications that require advanced API support from their runtime libraries.

NOTE: The Lean Encoder/Decoder (LED) is only available on common platforms like Windows, Linux, and Solaris, and may not be available for your embedded system port. If you are interested in LED for your platform, contact OSS Nokalva Sales.

See Also

C++-compiling your Application

Once you have ASN.1-compiled your specification and added the appropriate calls to the needed OSS API functions, you can compile the generated .cpp and .h files along with your application code.

Using the Microsoft Visual C/C++ compiler, execute the following commands to compile your application code along with the generated .cpp and .h files:

cl -c -MT –EHsc -I. –I "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\include"
                                                                      –DOSSPRINT bcas.cpp encode.cpp

where bcas.cpp is the ASN.1 Compiler-generated file and encode.cpp is the application code that contains OSS API function calls. The command creates two object files, bcas.obj and encode.obj, that will be linked into the final application executable.

Replace -MT above with -MD if you want to link dynamically rather than statically.

Once you have ASN.1-compiled your specification and added the appropriate calls to the needed OSS API functions, you can compile the generated .cpp and .h files along with your application code.

Execute the following commands to compile and link your application code along with the generated .cpp and .h files:

CC -I. -I/usr/local/asn1cpp/include -DOSSPRINT -c  bcas.cpp

CC -I. -I/usr/local/asn1cpp/include -c  tbcas.cpp

where bcas.cpp is the ASN.1 Compiler-generated file and encode.cpp is the application code that contains OSS API function calls. The command creates two object files, bcas.o and encode.o, that will be linked into the final application executable.

Linking your Application with the OSS Libraries

Once you have compiled the generated .cpp and .h files and your application code into object code, link the code with the OSS API Runtime libraries either statically or dynamically.

Linking statically using the Microsoft Visual C/C++ linker:

link  \
    -out:tbcas.exe bcas.obj encode.obj \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\osscppmt.lib"  \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\cpptoedmt.lib"  \
    user32.lib

To use the LED, run the ASN.1/C++ Compiler with the –lean option and link your application with the osscppmt.lib and cppledmt.lib /MT libraries.

To use the SOED, run the ASN.1/C++ Compiler with the –soed option and link your application with the osscppmt.lib and cppsoedmt.lib /MT libraries.

NOTE: If you are using the OSS ASN.1 Tools for C++ trial version, also specify the ossiphlp.lib OSS library and the advapi32.lib Microsoft Visual C/C++ library.

Linking dynamically using the Microsoft Visual C/C++ linker:

link 
    -out:encode.exe encode.obj bcas.obj \
    "C:\Program Files\OSS Nokalva\asn1cpp\<platform name>\<version>\lib\cpptoed.lib"

To use the LED DLLs, link your application with the cppled.lib import library.

To use the SOED DLLs, link your application with the cppsoed.lib import library.

NOTE: To correctly link dynamically with cppsoed.lib, cppled.lib, or cpptoed.lib, be sure to C++-compile your application code with the -MD option (and not -MT).

See Also

Once you have compiled the generated .cpp and .h files and your application code into object code, link the code with the OSS API Runtime libraries either statically or dynamically.

To link the object code statically with the OSS API Runtime library files:

CC  -o encode encode.o bcas.o /usr/local/asn1cpp/lib/libosscpp.a  \
      /usr/local/asn1cpp/lib/libcpptoed.a -lm –lsocket -lnsl

To link the object code dynamically with the OSS API Runtime library files:

CC  -o encode encode.o bcas.o /usr/local/asn1cpp/lib/libosscpp.so  \
      /usr/local/asn1cpp/lib/libcpptoed.so -lm –lsocket -lnsl

See Also

Running your application

You can run your ASN.1 application in the same way that you run other applications on your system. For example, if the generated executable for your application is called encode.exe, you would issue the following command:

encode

When you include calls to API Runtime functions in your source code, your application will automatically use the OSS Nokalva runtime libraries for encoding, decoding, and performing auxiliary tasks. However, if you linked your application dynamically with the OSS libraries, be sure to add the bin/ directory, which contains the OSS DLLs, to your executable search path or copy the OSS DLLs to a directory within the executable search path.

If you are using any /MD static libraries, you must C++-compile your generated and handwritten code with the USE_MD_LIB macro #defined. For example, on the C++-compiler command line that would be:

-DUSE_MD_LIB

Also, keep in mind that Microsoft recommends the following:

"Having more than one copy of the run-time libraries in a process can cause problems, because static data in one copy is not shared with the other copy. To ensure that your process contains only one copy, avoid mixing static and dynamic versions of the run-time libraries. The linker will prevent you from linking with both static and dynamic versions within one .exe file, but you can still end up with two (or more) copies of the run-time libraries. For example, a dynamic-link library linked with the static (non-DLL) versions of the run-time libraries can cause problems when used with an .exe file that was linked with the dynamic (DLL) version of the run-time libraries. You should also avoid mixing the debug and non-debug versions of the libraries in one process."

To be consistent with the above recommendation, use the VC++ /MT compiler option with the OSS /MT static runtime libraries, or the VC++ /MD compiler option with the OSS static /MD runtime libraries, or the VC++ /MD compiler option and one of the OSS import libraries.

You can run your ASN.1 application in the same way that you run other applications on your system. For example, if the generated executable for your application is called encode, you would issue the following command:

./encode

When you include calls to API Runtime functions in your source code, your application will automatically use the OSS Nokalva runtime libraries for encoding, decoding, and performing auxiliary tasks. However, if you linked your application dynamically with the OSS libraries, be sure to add the lib/ directory, which contains the OSS dynamic libraries, to the LD_LIBRARY_PATH environment variable.

For information about the OSS Nokalva makefiles, see the README.TXT files located in the samples directory.


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

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