Do you have a sample application illustrates the use of the OSS ASN.1 Compiler to compile a simple ASN.1 module, and the use of the OSS runtime APIs to invoke the Extended-XER (XML) encoder/decoder?

The following sample application illustrates the use of the OSS ASN.1 Compiler to compile a simple ASN.1 module, and the use of the OSS runtime APIs to invoke the Extended-XER (here after called E-XER) encoder/decoder.

The C application program in this example is tebcas.c and the associated ASN.1 source file is ebcas.asn. This ASN.1 file contains a value notation myCard. The application program encodes this value (myCard) using E-XER, and then decodes the E-XER encoded data into structures.

The following outline shows how you can produce and run a sample executable program that encodes and decodes a message using E-XER (Extended XML Encoding Rules) .

Step 1: Invoking the ASN.1 Compiler

The following describes how to compile the abstract syntax defined in the ebcas.asn file.

1.1 Input ASN.1 Syntax (ebcas.asn)

BCAS DEFINITIONS XER INSTRUCTIONS ::= BEGIN
BBCard ::= SEQUENCE {
name [ATTRIBUTE] VisibleString (SIZE (1..60)),
team [ATTRIBUTE] VisibleString (SIZE (1..60)),
age INTEGER (1..100),  
position VisibleString (SIZE (1..60)), 
handedness ENUMERATED  {left-handed(0), right-handed(1), ambidextrous(2)} 
}   

myCard BBCard ::= {  
name "Casey",  
team "Mudville Nine",  
age 32,  
position "left field",  
handedness right-handed  
}   

ENCODING-CONTROL XER  
GLOBAL-DEFAULTS MODIFIED-ENCODINGS 
        NAME ALL IN BBCard AS CAPITALIZED  

        TEXT BBCard.handedness:left-handed AS "left handed"  

        TEXT BBCard.handedness:right-handed AS "right handed"  

        NAMESPACE BBCard AS "http://www.example.com" 
        PREFIX "oss"                  
END

1.2 Command to compile ebcas.asn

The following command compiles ebcas.asn, and generates ebcas.h and ebcas.c files. The ebcas.h file contains the structures corresponding to the components of ASN.1 file. The ebcas.c file contains information needed by the encoder and the decoder at runtime. The file, ebcas.c, must be compiled and linked with the sample application.

asn1 -exer ebcas.asn

or

asn1 -exer ebcas

The -exer compiler option notifies compiler that E-XER (Extended XML Encoding Rules) will be used at runtime. For detailed descriptions of all the compiler options, see the Compiler Options Reference section.

1.3 Output files generated by the ASN.1 Compiler

ebcas.h:

#ifndef OSS_ebcas  
#define OSS_ebcas    
                
#include "asn1hdr.h"  
#include "asn1code.h"    
                
#define BBCard_PDU 1    
                
  typedef struct BBCard {  
  char name[61];  
  char team[61];  
  unsigned short age;  
  char position[61];  
  enum {  
  left_handed = 0,  
  right_handed = 1,  
  ambidextrous = 2  } handedness;  
                } BBCard;    
                
                extern BBCard myCard;      
                extern void * const ebcas; /* encoder-decoder control table */  
                
                #endif /* OSS_ebcas */

ebcas.c:

The ebcas.c file contains the information needed by the runtime APIs to encode and decode PDUs. Since this file contains internal information, it is not shown here. This file must be compiled and linked with the sample application.

---

Step 2: Compiling and Linking the sample application

The following C program, tebcas.c, encodes the PDU described by the ebcas.asn abstract syntax using E-XER (Extended XML Encoding Rules), and then decodes it. Note that ebcas.h (generated by the compiler) has been #included in the application program. This header file contains the generated declarations for the application. (The function calls to the OSS Encoder/Decoder functions are in bold font.) After the application program is compiled, the OSS Encoder/Decoder runtime library must be linked into the resulting executable file.

2.1 Input application program tebcas.c

/ * Application Program: tebcas.c  
* Encodes a sample baseball card  
* using BCAS (Baseball Card Abstract Syntax)  */    
                  
#include "ebcas.h" /* compiler-generated header file */
                  
/* Encodes a card. If the card is successfully encoded, decodes it. */
                  int main()  {  
     OssBuf encodedData; /* length and address of encoded data */ 
     BBCard *myCardPtr = NULL; /* address of decoded data */
     int pdu_num = BBCard_PDU;  
     struct ossGlobal w, *world = &w;
     int retcode; /* return code */
                    
     /* Call ossinit() first to initialize OSS's global structure  */  
     if ((retcode = ossinit(world, ebcas))) {
       ossPrint(world, "Ossinit() returned %d\n", retcode);  
       return retcode; 
     }
                    
     ossSetEncodingFlags(world, DEBUGPDU); 
     ossSetDecodingFlags(world, DEBUGPDU); 
                    
     /* Print the input to the encoder */  
     ossPrint(world, "\nThe input to the encoder ...\n\n");  
     ossPrintPDU(world, BBCard_PDU, &myCard); 
                    
     /* Encode a card. Return non-zero for failure. */  
     encodedData.value = NULL;  
     encodedData.length = 0;    
     ossPrint(world, "\nEncoding BBCard ...\n");
                    
     if (ossEncode(world, BBCard_PDU, &myCard, &encodedData)) { 
     /* an error occurred, print errmsg */
     ossPrint(world, "%s\n", ossGetErrMsg(world));  
     return 1; 
     }
                    
     ossPrint(world, "Card encoded.\n");    
     ossPrint(world, "\nE-XER encoding of BBCard:\n");    
                    
    /* For XER specifically, print the encoding */  
    ossPrint(world, "\n%.*s\n", encodedData.length, encodedData.value);    
                    
     /* Decode a card whose encoding is in encodedData. Return non-zero  for failure. */    
     ossPrint(world, "\nDecoding BBCard ...\n"); 
     if (ossDecode(world, &pdu_num, &encodedData, (void **)&myCardPtr)) {  
     /* an error occurred, print errmsg */  
     ossPrint(world, "%s\n", ossGetErrMsg(world));  
     retcode = 1;  
                    } else {    
     ossPrint(world, "Card decoded.\n"); /* successfully decoded */    
     
     /* Print the decoder's output */  
     ossPrint(world, "\nOutput from the decoder ...\n\n");  
     ossPrintPDU(world, pdu_num, myCardPtr);  
     ossFreePDU(world, pdu_num, myCardPtr);  retcode = 0;  
     }    
     
     /* free the encoder's output buffer*/  
     ossFreeBuf(world, encodedData.value);    
     
     /*  Call ossterm() to free all resources  */  
     ossterm(world);    
     return retcode;  
                  } 
 

---

2.2 Command to compile and link sample program

The OSS ASN.1/C compiler generated file ebcas.c and application program tebcas.c should be compiled and linked to generate the sample executable program.

The easiest way to compile and run the sample program is by using the makefiles (asn1cpl.mak and tebcas.mak) under the samples directory of the OSS ASN.1 Tools for C. The asn1cp.mak file compiles the ASN.1 syntax and generates .h and .c files. The other makefile, tebcas.mak, compiles application code with the generated .c file, and links the object file with the OSS runtime libraries to generate a sample executable. These files are located under the samples/xml/extended-xer directory.

For example, if you have installed OSS ASN.1 Tools for C under the /ossasn1/win32/7.0.0 directory, these makefiles can be found under the /ossasn1/win32/7.0.0/samples/xml/extended-xer directory.

An executable for the sample program can be created by using the following these commands:

On Windows:

nmake -f asn1cpl.maknmake -f tebcas.mak

On Unix:

make -f asn1cpl.makmake -f tebcas.mak

---

Step 3: Running the sample program

3.1 Command to run the executable

An executable tebcas (tebcas.exe for Windows) will be generated after step 2.2. This executable can be run on the command line by the following command:

tebcas

3.2 Output of the sample program

Running tebcas will generate the following output:

The input to the encoder ...    
   value BBCard ::=  {  
      name "Casey",  
      team "Mudville Nine",  
      age 32,  
      position "left field",  
      handedness right-handed  
              }    
              
              Encoding BBCard ...  
              Card encoded.    
              
              E-XER encoding of BBCard:    
   <?xml version="1.0" encoding="UTF-8"?>  
<oss:BBCard xmlns:oss="http://www.example.com"    xmlns:asn1="urn:oid:2.1.5.2.0.1" Name="Casey" 
Team="Mudville Nine">  
   <Age>32</Age>  
   <Position>left field</Position>  
   <Handedness>right handed</Handedness>  
   </oss:BBCard>    
      
Decoding BBCard ...  
        Card decoded.    
             
Output from the decoder ...    
         value BBCard ::=  {  
      name "Casey",  
      team "Mudville Nine",  
      age 32,  
      position "left field",  
      handedness right-handed  
              }

---

The samples included with some of the Knowledge Center answers are meant for your general understanding of the OSS products. Different versions of the products might produce slightly different outputs. Consult the products documentation and samples for the most up-to-date products information and code examples.