ASN1C

ASN.1 Compiler Version 6.2 Installation Guide

Objective Systems, October 2009

The software described in this document is furnished under a license a reement and ma! be used onl! in accordance with the terms of this a reement. Cop!ri ht Notice Cop!ri ht " 1##$%2&&# 'b(ecti)e S!stems* Inc. All +i hts +eser)ed This document ma! be distributed in an! form* electronic or otherwise* pro)ided that it is distributed in its entiret! and that the cop!ri ht and this notice are included. Authors Contact Information: Comments* su estions* and in,uiries re ardin this document ma! be submitted )ia electronic mail to info-ob(%s!s.com.

Installing the ASN1C Compiler Software

Version 6.. of the ASN1C compiler software is pac/a ed in two or three separate distribution units* dependin on how ASN1C is licensed0 A System Development Kit 1S234 unit that contains the compiler and de)elopment libraries* and 'ne or more run%time deplo!ment units containin optimi5ed binar! libraries for deplo!ment of a finished application. A floatin license ser)er application 1a)ailable for 6indows and )arious 7NI8es4.

The followin sections contain installation instructions for 6indows and 7NI8 )ersions of the ASN1C distribution files. This procedure is the same for all of the different confi urations. The last section describes techni,ues to help port code enerated b! earlier )ersions of the compiler to )ersion 6.&..

Microsoft Windows Distribution

The 9icrosoft 6indows )ersion of ASN1C is distributed either on a C2 and:or electronicall! o)er the Internet. The distribution files are self%e.tractin * e.ecutable setup files. The format of the filename of the S23 unit is as follows0 ac<L>v62xw32sdk.exe where <L> would be replaced with a sin le%letter lan ua e code. ;ossible )alues are p for C:C<<* j for =a)a* or s for C>. +un%time deplo!ment pac/a es ha)e the followin format0 rt<L>v62xw32<TYP>.exe where <L> would be replaced with a sin le%letter lan ua e code and <TYP> would be replaced with a code for the pac/a e t!pe. ;ossible )alues for the lan ua e code are p for C:C<<* j for =a)a* or s for C>. The t!pe code would contain information on whether the librar! is licensed per%host 1limited4 or unlimited* whether source code is included or not* and what encodin rules are supported. ?or e.ample0 the followin would be an ASN1C )6.2& run%time deplo!ment /it for =a)a0 rtjv620w32ubb.exe In this case* the ubb on the end stands for unlimited* binar!* @A+:2A+. The floatin license pac/a e is )ersioned separatel! from ASN1C and is distributed in an e.ecutable self% e.tractin installation file 1li/e other 6indows /its4. The pac/a e is named with the followin format0 lsvxxxw32.exe In this case* stands for the )ersion number. At the time of writin * the latest )ersion of the floatin license ser)er was 1.1.&.

Floating License Server Installation

This section describes the installation of a floatin license ser)erB users are encoura ed to consult the +AA29A.html file included with the pac/a e for additional details.

The floatin license ser)er is an application that runs as a 6indows ser)ice. The installation pro ram will install the ser)er as a ser)ice if the appropriate bo. is chec/ed durin installation. If !ou wish to enable or disable the ser)ice after installation* this ma! be done from the 6indows Control ;anel 1Administrati)e Tools* Ser)ices4. Alternati)el!* 'b(ecti)e S!stems pro)ides two batch files 1one for startin the ser)ice and one for stoppin the ser)ice4 in the installation pac/a e. The ser)ice re,uires a file called licServer!con" to be used in order to properl! bind the ser)ice to the host. This file is /ept in the bin subdirector! of the installation and contains a line of the format0 url: http://[host IP] The #ost $P is the I; address of the host on which the ser)er is runnin . The license ser)er is itself a licensed product0 it re,uires an osyslic!t t file to be installed in the bin subdirector! in order to run properl!. This file is pro)ided b! 'b(ecti)e S!stems when the license ser)er is purchased. A separate file* osys"lo%tlic!t t* is re,uired in order to run ASN1CB the contents of this file are described below.

ASN1C System Development Kit (SDK) Installation (No e! Loc"e )

The procedure to install the ASN1C compiler and run%time libraries is as follows0 1. 2. C. 2ouble%clic/ the S23 installation pro ram /it e.ecutable filename. This is the filename in the format described abo)e. ?ollow the setup pro ram instructions. Dou should ha)e recei)ed a node%loc/ed license file 1osyslic!t t4 to enable the compiler to run on a i)en node. Cop! this file into one of the followin locations0 a. 'ne of the directories specified in !our ;ATE en)ironment )ariable* or b. In a different director! and create a new en)ironment )ariable name 'SFIC2I+ that points to this director!* or c. Into the same director! as the ASN1C compiler e.ecutable file 1asn1c.e.e4 If installation was successful* !ou should ha)e both a raphical user interface 1G7I4 compilation wi5ard a)ailable as well as a command line )ersion of the compiler. The G7I wi5ard can be tested b! startin the application and enterin the data re,uested in each of the dialo prompts. The command%line )ersion of the compiler can be tested as follows0 1. 2. 'pen an 9S%2'S or other command shell window. Chan e director! 1cd4 to the compiler root director!. The default director! in the setup script is c:\acv<version> where <version> is the )ersion number of the compiler. ?or e.ample* c:\acv620 is the default root director! for )ersion 6.2& of the compiler. Anter .\bin\asn1c from the command line prompt. Dou should see a usa e displa! of compiler command line options 1these options are discussed later4. This indicates the compiler is properl! installed and wor/in .

C.

If !ou et a messa e indicatin the license file could not be found* please re)iew the procedure in step C abo)e to ma/e sure it is installed in the proper location.

Dou should include the Gtar etHIbin 1e. . c0Iac)62&Ibin4 director! in !our ;ATE en)ironment )ariable in order to run the compiler from an!where.

ASN1C System Development Kit (SDK) Installation (Floating)

Installation of ASN1C in con(unction with a floatin license ser)er is identical to the procedure described in the precedin section e.cept that a floatin license must be used instead of a node%loc/ed license. The floatin license is /ept in a file called osys"lo%tlic!t t. It is this file* not osyslic!t t* that should be copied to the same director! as the asn1c e.ecutable. The floatin license contains a sin le line of the format url: http://[host IP] The #ost $P must correspond to the I; address of the host on which the floatin license ser)er is runnin .

ASN1C #$n!time Deployment Kit Installation

The deplo!ment run%time pac/a es can be installed at an! time after the S23 is installed. The! are not necessar! for basic pro ram de)elopment. The! should be used when an application is read! to be deplo!ed. To install* do the followin 0 1. 2. 2ouble%clic/ the installation pro ram /it e.ecutable filename. This is the filename in the format described abo)e. ?ollow the setup pro ram instructions. Note that the root director! for the installation should be the same as was specified for installation of the S23 pac/a e described earlier.

The result will be additional librar! subdirectories of the form lib&opt added to the director! hierarch!. These contain the optimi5ed libraries. To lin/ with these libraries* either the ma/efile1s4 or pro(ect files used to lin/ the application must be chan ed* or the subdirectories must be renamed. ?or e.ample* the e.istin lib subdirector! could be renamed lib&nonopt and libopt could then be renamed to lib.

Doc$mentation Installation
7p%to%date documentation is alwa!s a)ailable online at0 http0::www.ob(%s!s.com:docs:documents.shtml If a C2 was purchased with the software* all applicable ;2? document files for a particular confi uration of the software will be a)ailable on the C2.

Compiling an Lin"ing ASN1C %enerate Co e

6hen buildin code enerated b! the ASN1C compiler* !ou will need to ha)e one or more run%time source directories in !our include path to compile the enerated code with a C or C<< compiler. The run%time source directories are rtsrc 1common4* rtbersrc 1@A+:2A+4* rtpersrc 1;A+4* and rt ersrc 18A+4. To lin/* !ou will need the lib or lib&opt subdirector! in !our librar! path. This is where all of the librar! files are located.

&esting the C or C'' #$n!time Components

The default C or C<< run%time libraries for 6indows were built with 9icrosoft Visual C<< V6.&. 'ther libraries are a)ailable that ha)e been built with the @orland C<< compiler 1)J.J4 and with the 9icrosoft Visual C<< )$.1* )K.&* and )#.& 1.NAT4 compilers. If !ou ha)e the )ersion of the product that includes run%time source code* !ou can rebuild the run%time libraries usin an! ANSI%standard C or C<< compiler.

Dou can )erif! operation of an! of the different run%time libraries b! e.ecutin the sample pro rams. These can be found in the s%mple&ber* s%mple&'er* and 1optionall!4 the s%mple&per or s%mple& er subdirectories. ?or e.ample* we will assume that !ou installed ASN1C for C:C<<. To test the @A+ C<< encode:decode capabilities* do the followin 0 1. Chan e director! 1cd4 to the .\cpp\sample ber\emplo!ee subdirector!. A.ecute the nma"e command to build the writer and reader sample pro rams. nma"e is utilit! pro ram that comes with Visual C<<. It ma! also be necessar! to e.ecute a 9icrosoft batch file named #C#A$%&2.'A( to set the path information so that the nma"e utilit! can be found. 1Important note0 this assumes !ou are usin 9icrosoft Visual C<< on !our ;C. Some ;C specific include and librar! directories in the ma/efile ma! need to be chan ed to et the samples to wor/ on !our s!stem. See the +AA29A.t.t file for further details4. A.ecute the )riter.e*e pro ram to encode the sample record. The results of the encodin will be dumped to the screen and sa)ed in a file called mess%(e!'%t. A.ecute the rea+er.e*e pro ram to read and decode the contents of the mess%(e!'%t file. This pro ram will read the encoded record into memor!* decode it* and then print the contents of the enerated structure )ariable to standard output.

2. C.

Testin ;A+ is similar0 1. 2. Chan e director! 1cd4 to the .\sample per\emplo!ee subdirector!. A.ecute the nma"e command to build the writer and reader sample pro rams. A.ecute the )riter.e*e pro ram to encode the sample record. The ,a switch can be used to encode a record usin ali ned ;A+. The ,u switch encodes a record usin unali ned ;A+. The results of the encodin will be dumped to the screen and sa)ed in a file called mess%(e!'%t. A.ecute the rea+er.e*e pro ram to read and decode the contents of the mess%(e!'%t file. The ,a or ,u switch must be the same as that specified when the writer pro ram was e.ecuted. This pro ram will read the encoded record into memor!* decode it* and then print the contents of the enerated structure )ariable to standard output.

C.

This test can be repeated for 8A+ as well b! oin to the sample *er\emplo!ee subdirector! and repeatin the abo)e se,uence of steps.

(er!host License Deployment Iss$es

If !ou purchased run%time libraries that allow for unlimited redistribution* then all run%time license chec/in would ha)e been remo)ed from these libraries and all that must be done to deplo! is to ma/e certain that the code is lin/ed with these libraries. If per%host run%time licensin was selected* then there are two choices as to how applications are deplo!ed0 1. 2. The run%time license information can be directl! compiled into the application and then the application deplo!ed without an! e.ternal files* or An e.ternal binar! license file can be deplo!ed with the application to allow it to run on the licensed hosts.

The first choice is done b! default e)er! time ASN.1 source files are enerated and the resultin code compiled and lin/ed into an application. Information from the osyslic!t t file is transferred to a C header

file called rt)ey!# and this information is included in the enerated code. This allows the application to run on all licensed hosts. The second option is applicable mainl! in situations when a finished application is to be run on different hosts than were ori inall! licensed. This can happen if host names are chan ed* or additional hosts are added at a later date. It mi ht not be practical in these situations to rebuild the application in this case. The alternati)e is therefore a)ailable to create a binar! license file and deplo! it with the application to allow it to run on the newl! licensed hosts. The procedure to do this is as follows0 1. 7se ASN1C to enerate an rt)ey!'%t file b! issuin the followin command0 asn1c -genlic The rt)ey!'%t file will be created in the director! where !ou issued the command. 2. C. Cop! the rt)ey!'%t file onto the computers on which !ou want to run !our application. Set the *+L$+,$L- en)ironment on these computers to point at the full path to the rt)ey!'%t file.

In the case of =a)a* the procedure is different. In this case* the deplo!ed %sn.rt!j%r file must contain up%to% date license information. This is done b! e.ecutin the set)ey!b%t script for 6indows or set)ey!s# script for Finu.:7NI8 in the =a)a subdirector! after the license file for ASN1C is installed. This must be done whene)er the osyslic!t t license file is updated.

Floating License Server Installation (UNIX)

This section briefl! describes the installation of a floatin license ser)er on a 7NI8 s!stem. 9ore detail ma! be found in the +AA29A.t.t file that accompanies the installation. The floatin license ser)er is an application that should be run as a lon %runnin process. In 7NI8* this ma! be done b! runnin the license ser)er in the bac/ round0 ./licServer -url http://[host IP] & The #ost $P specified is the hostLs I; address on which the license ser)er runs. The floatin license ser)er is itself a licensed application0 it re,uires an osyslic!t t file in order to run. This file is pro)ided b! 'b(ecti)e S!stems when the floatin license ser)er is purchased. 6ithout the license* the ser)er will fail to start. The license ser)er is not confi ured b! default to be installed as a run%le)el ser)ice. As different 7NI8es ma! treat run%le)el ser)ices differentl!* users are encoura ed to consult their 'peratin S!stem%specific documentation to determine how to do this if desired.

UNIX Distribution (Node-loc ed)

Installation of the Finu. : 7NI8 )ersion of ASN1C is similar to the 6indows )ersion e.cept that the distribution files are pac/a ed as 5ipped tar files. The format is the same as 6indows e.cept that the e.tension is !t%r!(/ instead of !e e! To install* do the followin 0 1. 2. Cop! the distribution file GdistfileH to the top%le)el director! where the compiler is to be installed. 7n5ip usin the GN7 un5ip tool0

gunzip <distfile> C. 7ntar the file usin the followin command0 tar xvf <distfile> This will create a director! tree structure with Masn1c%)G)ersionHN as the root. O. Dou should ha)e recei)ed a node%loc/ed license file 1osyslic!t t4 to enable the compiler on a i)en node. Cop! this file into one of the followin locations0 a. 'ne of the directories specified in !our ;ATE en)ironment )ariable* or b. In a different director! and create a new en)ironment )ariable name 'SFIC2I+ that points to this director!* or c. Into the same director! as the ASN1C compiler e.ecutable file 1asn1c.e.e4 To test if the compiler installation was successful* do the followin 0 1. Chan e director! 1cd4 to the compiler root director!. The default director! in the setup script is .-asn1c.v<version> where <version> is the )ersion number of the compiler. ?or e.ample* .-asn1c.v612 is the default root director! for )ersion 6.1& of the compiler. Anter .-bin-asn1c from the command line prompt. Dou should see a usa e displa! of compiler command line options 1these options are discussed later4. This indicates the compiler is properl! installed and wor/in .

2.

After installin the compiler* !ou can modif! !our operatin en)ironment to access the compiler e.ecutable files from an!where. To do this* !ou will need to add the path to the compiler to !our ;ATE en)ironment )ariable or add a lin/ to it from a standard binar! director! 1such as :opt:bin4. This is optional and not re,uired for an! of the run%time sample pro rams to wor/. The! are all set up to use relati)e director! paths to access the compiler and libraries. 2eplo!ment run%time pac/a es should be installed b! repeatin steps 1 throu h C abo)e. The pac/a es should be unpac/ed in the same base root director! as the ori inal S23 files. This will cause lib&opt subdirectories to be added to the )arious C and C<< directories in the installation.

UNIX Distribution (Floating)

Installation of ASN1C in con(unction with a floatin license ser)er is identical to the procedure described in the precedin section e.cept that a floatin license must be used instead of a node%loc/ed license. The floatin license is /ept in a file called osys"lo%tlic!t t. It is this file* not osyslic!t t* that should be copied to the same director! as the asn1c e.ecutable. The floatin license contains a sin le line of the format url: http://[host IP] The #ost $P must correspond to the host I; address on which the floatin license ser)er is runnin . It should match the host I; of the 7+F used to start the floatin license ser)er.

!esting t"e # or #$$ %un-ti&e #o&'onents

The basic C or C<< run%time libraries for 7NI8 are t!picall! built with the GN7 cc: << compiler and:or the standard nati)e compiler pro)ided b! the manufacturer of a particular t!pe of 7NI8 1for e.ample* aCC for E;%784. Two s!mbolic lin/s are used within the c or cpp subdirector! to select the )ersion of the run% time libraries to be used. The! are as follows0

lib platform.m/

@! default* these are set to point at the GN7 cc: << )ersion of the run%time libraries for a particular platform. This is easil! chan ed b! deletin the lin/s and settin them to point at another run%time librar!. ?or e.ample* on Solaris* to use the nati)e compiler libraries one would set lib %H libCC and platform.m/ %H platform.CC0 ln s libCC lib ln s plat or!.CC plat or!.!" Dou can )erif! operation of an! of the different run%time /its b! e.ecutin the sample pro rams. These can be found in the different sample directories 1s%mple&ber* s%mple&'er* s%mple&per and:or s%mple& er dependin on what run%time /its were installed4. To test the encode:decode capabilities for an! of the encodin rules* e.ecute the sample pro rams as described in the section on 6indows installation.

)ac"war s Compati*ility
ASN1C underwent si nificant chan es between )ersion J.K. and 6.&.* includin some that affect code eneration. These chan es are also present in )ersion 6.1. Additionall!* 6.1 includes more modifications that will affect =a)a and C> handlin of enumeration t!pes* especiall!. These chan es represent an A;I chan e for all lan ua es. ?or C and C<<* two files ha)e been pac/a ed with the /it to help in portin code enerated with prior )ersions0 rtport.pl and asn1co!pat.h. The former will process a specified file and rename the t!pes contained in it. The latter contains macro definitions that con)ert old names to the new namin scheme. Chan es for =a)a and C> will be mostl! transparent to the user* e.cept that enumerated )alues are now retrie)ed throu h the use of accessor methods. These chan es are discussed in detail in the =a)a and C> 7serLs Guides.