Procedure for Calling C Decode Functions

---

This section describes the step-by-step procedure for calling a C XER decode function. This method must be used if C code generation was done. This method cannot be used as an alternative to using the control class interface if C++ code generation was done. Use the C++ procedure instead.

There are four steps to calling a compiler-generated decode function:

1. Prepare a context variable for decoding;
2. Open a stream;
3. Call the appropriate compiler-generated decode function to decode the message;
4. Free the context after use of the decoded data is complete to free allocated memory structures

Before a C XER decode function can be called; the user must initialize a context variable. This is a variable of type OSCTXT. This variable holds all of the working data used during the decoding of a message. The context variable is declared as a normal automatic variable within the top-level calling function. It must be initialized before use. This can be accomplished by using the rtInitContext function. Also, the context must be initialized for streaming operations by calling the rtxStreamInit function:

 
        OSCTXT ctxt; // context variable 
 

 
        if (rtInitContext (&ctxt) != 0) {
 
           /* initialization failed, could be a license problem */
 
           printf ("context initialization failed (check license)\n");
 
           return -1;
 
        }
 

 
        rtxStreamInit (&ctxt));	  // Initialize stream
 

The next step is to create a stream object within the context. This object is an abstraction of the output device to which the data is to be encoded and is initialized by calling one of the following functions:

• rtxStreamFileOpen
• rtxStreamFileAttach
• rtxStreamSocketAttach
• rtxStreamMemoryCreate
• rtxStreamMemoryAttach

The flags parameter of these functions should be set to the OSRTSTRMF_INPUT constant value to indicate an input stream is being created (see the C/C++ Common Run-Time Library Reference Manual for a full description of these functions).

A decode function can then be called to decode the message. If the return status indicates success (0), then the message will have been decoded into the given ASN.1 type variable. The decode function may automatically allocate dynamic memory to hold variable length items during the course of decoding. This memory will be tracked in the context structure, so the programmer does not need to worry about freeing it. It will be released when the context is freed.

The final step of the procedure is to close the stream and free the context block. The function to free the context is rtFreeContext.

A program fragment that could be used to decode an employee record is as follows:

    #include employee.h         /* include file generated by ASN1C */
 

 
    main ()
 
    {
 
        int     stat;
 
        OSCTXT  ctxt;
 
        PersonnelRecord employee;
 
        ASN1ConstCharPtr filename = "message.xml";
 

 
        /* Step 1: Init context structure */
 

 
        if (rtInitContext (&ctxt) != 0) return -1;
 

 
        rtxStreamInit (&ctxt);
 

 
        /* Step 2: Open a stream */
 

 
        stat = rtxStreamFileOpen (&ctxt, filename, OSRTSTRMF_INPUT);
 
        if (stat != 0) {
 
           rtErrPrint (&ctxt.errInfo);
 
           return -1;
 
        }
 

 
        /* Step 3: decode the record */
 

 
        stat = asn1XD_PersonnelRecord (&ctxt, &employee);
 
        if (stat == 0) {
 
           if (trace) {
 
              printf ("Decode of PersonnelRecord was successful\n");
 
              printf ("Decoded record:\n");
 
              asn1Print_PersonnelRecord ("Employee", &employee);
 
           }
 
        }
 
        else {
 
           printf ("decode of PersonnelRecord failed\n");
 
           rtxErrPrint (&ctxt);
 
           rtxStreamClose (&ctxt);
 
           return -1;
 
        }
 

 
        /* Step 4: Close the stream and free the context. */   
 

 
        rtxStreamClose (&ctxt);
 
        rtFreeContext (&ctxt);
 

 
        return 0;
 
   }