Getting Started with the GDMO/ASN.

1 Compiler

A guide on how to get started with the Q3ADE GDMO/ASN.1 compiler.

UH Communications

Copyright 2000 UH Communications A/S. UH Communications A/S Telegrafvej 5 DK-2750 Ballerup, Denmark ph. +45 4468 0864, fax +45 4468 0805 web: http://www.uhcommunications.com

Information in this document is subject to change without notice. Companies, names and data used in examples herein are fiction unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of UH Communications A/S. Comments or questions may be submitted via electronic mail to product@uhcommunications.com. Visual C++, Windows NT, Windows 2000 and Windows 95 are registered trademarks of Microsoft Corporation. UNIX is a trademark of Unix System Laboratories, Inc. Solaris is a registered trademark of Sun Microsystems Inc.

CONTENTS
INTRODUCTION_______________________________ 3 INVOKING THE COMPILER ______________________ 4
Pre paring the input ____________________________________ 4 Validate your specification ______________________________ 5 The command line paramete rs ___________________________ 6

GENERATING CODE ____________________________ 8

The Code Ge neration Information Mode l __________________ 10 Dynamic Macro Variables a nd Implicit Invocation of Macros __ 11 Fragments __________________________________________ 13

App A: Samples ______________________________ 14

Content of My Model.gdmo: ___________________________ 14 Content of MySy ntaxes.asn ___________________________ 15 Content MyModelFragment.gdmo ______________________ 16 Gene ration Macro: ListItems.mac ________________________ 18 Gene ration Macro 2: ListItems2.mac _____________________ 18 Gene ration Te mplate : ListItems.txt ______________________ 18

Page 2

UH Communications A/S

Doc. no. A0604.xxxx

INTRODUCTION
The Q3ADE GDMO/ASN.1 Compiler is a utility included with the Q3ADE 3G Development package. Henceforth we will just call it the GDMO compiler. The GDMO compiler consists of a f rontend compiling batches of GDMO and ASN.1 specifications and a backend that generates various kinds output depending on the set of code generation templates fed to it. As a Q3ADE 3G Developer, you will use the utility as tool in producing new managed object classes to extend the behavioural capacity of the Q3ADE 3G management engine. But you may use the GDMO compiler as a separate development tool for your own purposes, e.g. by adding your own backend to the compiler. You will find detailed documentation of the compiler at http://www.uhcommunications.com/help/q3gdmo/q3gdmoINTR ODUCTION.ht m . This guide offers you a way to get started with the tool by using the project management tools included with the Q3ADE 3G development package to manage the files and the invocation of the GDMO compiler. It is assumed that you have installed Q3ADE 3G on your computer and obtained either a demo license or a developer license from UHC. It is also assumed that you are familiar with the GDMO and ASN.1 languages. Also, you need to be familiar with the make tools of your development platform.

Doc. No. A0604.xxxx

UH Communications

Page 3

INVOKING THE COMPILER

Preparing the input
The input to the GDMO compiler is an ASCII file containing one or more ASN.1 specifications or GDMO specifications. For the compiler to accept the input, it must be complete and adhere to the ASN1 and GDMO specifications in ITU X.208 and ITU X.722. Also the individual GDMO specifications must be framed as described below. Since most GDMO/ASN.1 specifications refer to other GDMO/ASN.1 specifications, ultimately to ITU X.721, all these specifications must be included as well. Naturally, it would become seriously unmanageable if you had to provide all this in one physical file. Therefore, the GDMO compiler offers two tec hniques to allow you to split your GDMO and ASN.1 specifications into separate files and even store them in different locations. The GDMO compiler includes a precompiler offering a subset of the precompiler pragmas as you probably are used to from C and C++ language compilers. If your GDMO/ASN.1 specification relies on another GDMO/ASN.1 specification stored in a separate file, then you may refer to this file using the precompiler pragma #include <filename>, usually placed in the beginning of your specification file. The precompiler w ill then include this specification in what we will call the compile batch. Have a look at the sample in App A. A relevant issue in this context is often that you cannot alter the GDMO specification, since it comes f rom a 3 rd party source or is used by other tools not prone to the precompiler pragmas. This you may solve by making a stub f ile containing the necessary includes to external f iles and then an include of the untouchable GDMO file. Another way to provide a complete compile batch is by reference resolution. Each ASN.1 and GDMO specification are named uniquely. These names are used as part of the language e.g. in the IMPORTS part of an ASN.1 module or as name prefixes of references in GDMO specifications. If a reference is not resolved by the explicit presence of the specification in the compile batch, then the compiler will go through a number of

Page 4

UH Communications A/S

Doc. no. A0604.xxxx

attempts to determine the name and location of the required specification files. This also leads to the other preparatory addition to your GDMO specification. For some reason the GDMO language does not have a standardized way of providing the name of the specification. The gdmo compiler therefore includes a feature was proposed by the Telemanagement Forum, but never actually integrated in the GDMO language standard, called GMO framing. This feature allows us to separate and identify sets of GDMO specifications as coming f rom different sources. The framing consist of two specialized GDMO comments, one at the beginning of the GDMO specification and one at the end, like: --<GDMO.Document "MyModel">- Here goes your GDMO specification --<GDMO.EndDocument >-Finally, it is quite common in GDMO specifications to implicitly refer to ASN.1 syntaxes in a related ASN.1 module, typically included in the same document as the GDMO specification. Regrettably we have not been able to device a way for the GDMO compiler to unambiguously guess these relations. In such cases, you have to add another specialized comment to the GDMO specification of the form: --<UHC.ASN1Module MyModuleSnt x>-Again, have a look at the sample in App. A. Given these preparatory steps, you should be ready to validate your GDMO/ASN.1 specification.

Validate your specification

To test that your GDMO/ASN.1 specification is complete, invoke the utility chkgdmo, like in: chkgdmo My Mode l.gdmo Q3ADE GDMO Compiler and Code generator R5.8b2[70] Copyrights (C) 1996-2005 UH Comm unications A/S. reserved The model specification is valid Now that was to be expected. Assume an x has been added in line 33 of the MyModel sample, the error message would look like: C:\Temp\MyModel.gdmo(33): error 1051 Item "MyModel":myObjectId: All rights

Syntax MySyntaxes.Stringx is not defined The model specification is invalid or incomplete

Doc. No. A0604.xxxx

UH Communications

Page 5

As you see here, the compiler checks the consistency of the GDMO spec all the way down to the ASN.1 spec. It will cross check your OID assignments that there are no duplicate registration OIDs in the compile batch. You might want to use this feature to cross check your complete GDMO library. Simply create a super file including all your GDMO specs and run it through the chkgdmo feature. We have tested it with libraries containing hundreds of GDMOs. The ASN.1 part of the compiler will also perform complete semantic validation of the ASN.1 specification, including tag assignments and overlapping names in choice constructs etc.

The command line parameters

In the examples in this document we use the chkgdmo utility to invoke the GDMO compiler. The reason is primarly that the chkgdmo utility provides the basic gdmo command line parameters required, like the I parameter. You may get a list of the command line parameters with the command: gdmo -? The output looks like this:
Q3ADE GDMO Compiler and Code generator R5.8b2[70] Copyrights (C) 1996-2005 UH Communications A/S. All rights reserved usage: gdmo [options] [inputfile] where options are: -A <Asn1 module/Fragment defn > Name of target ASN.1 (Fragment) definition file for generation -D <Macro Name>=<Macro Value> -C <Module Class Name> Code generation name assigned to the module selected by -G or -A -c Disable(!) macro script caching. Default enabled Definition of precom piler macro (controlling #ifdef's) -E Error messages will always contain full file path -G <GDMO module/Fragment defn> Name of target GDMO (Fragment) definition file for generation. -I <include path> (may also be given as env variable gdmopath) -b ignore behaviour descriptions (saves memory) -g <Generation macro file> Name of initiating generation macro file -H No Banner -l <File name> Generator log filename -m <File name> ASN.1 and GDMO module labels to file name mappings -x <Module or "All"> Generate index of GDMO elements -p [xhs]* <Module Name or "All">

Page 6

UH Communications A/S

Doc. no. A0604.xxxx

Print a module in Q3ADE-GDMO format. Print Options: x: Print (HTML link) index h: Print in HTML format s: Print only strict X.722-GMDO -P <Module Name or "All"> Print a module in strict X.722-GDMO format -t <Tailor file> Read Compiler options file ".cc" -v [ i[<pattern>] ] Verbose mode. Options: i: Enable use of 'Item' macro, omitting items not matching pattern string -w Suppress warnings -W Compilation fails on warnings

The detailed description of the gdmo command line parameters are found at: http://www.uhcommunications.com/help/q3gdmo/q3gdmoTHE_ COMMAND_LINE_ARGUMENTS.ht m Specifically the I parameter is required. This parameter informs the gdmo compiler about which directories to search to find a specific file. The format of this parameter is the same as the PATH environment variable of your host operating system. In the chkgdmo utility, the default path looks like this (on Unix systems):
;../gdmo;%Q3ADEDIR%/../nms/gdmo;%Q3ADEDIR%/../SNMPGW/gdmo;%Q 3ADEDIR%/../SNMPGW/gdmo/rfcs;%Q3ADEDIR%/../CorbaGW/gdmo;%Q3A DEDIR%/../sms/gdmo;%Q3ADEDIR%/../CLIGW/gdmo;%Q3ADEDIR%/../Gu ido/gdmo;%Q3ADEDIR%/gdmo;%Q3ADEDIR%/templates/q3mm;%Q3ADEDIR %/templates

Note the use of the QADEDIR environment variable, which we assume you have already defined according to the installation guide in Q3ADE3GUnixInstall. On Windows, the installation tool should take of this.

Doc. No. A0604.xxxx

UH Communications

Page 7

GENERATING CODE
You have now verif ied your GDMO specification using the chkgdmo utility. For the GDMO compiler to generate code, you need to provide it with a code generation macro. You will find a detailed description of the code generation mechanism at http://www.uhcommunications.com/help/q3gdmo/q3gdmoTHE_ GENERATOR.ht m In App. A you find a code generation sample ListItems.mac. This sample generates a list of registration OIDs. Invoke it like this: chkgdmo -g ListItems.mac -G MyModel My Mode l.gdmo and you should get an output like this: ---- GDMO Items in "MyModel" -----Name, OID aValue, 0.32.100.1001.2.7.3 myNamebinding, 0.32.100.1001.2.6.1 myObject, 0.32.100.1001.2.3.1 myObjectId, 0.32.100.1001.2.7.1 myObjectPackage, unregistered wiseSaying, 0.32.100.1001.2.7.2

The code generation backend of the compiler accepts two types of code generation files: a) Macro files, which are procedural scripts using the macro language of the compiler. b) Template files, which are files mi micking the layout of the code to be generated. The elements that are dynamic are replaced by macro codes surrounded by $$signs The ListItems.mac sample was an example of a Macro file. In App. A you also find the sample template file ListItems.txt. This template produces exactly the same output as ListItems.mac. Since the compiler only accep t a macro file as an argument, you have to make a simple macro file to invoke

Page 8

UH Communications A/S

Doc. no. A0604.xxxx

the template file. The sample ListItems2.mac is an example of such a macro file. The GENERATE macro statement invokes the ListItems.txt template and produces an output file named MyModel- Items.txt. Try to invoke it with this command: chkgdmo -g ListItems2.mac -G MyMode l MyModel.gdmo The output file MyModel-items.txt is found in the same directory as where you invoked the chkgdmo. The content of it is the same as the ouput of the previous example. Whether you want to use macros only for your code generation or use templates is mostly a matter of taste. In our experience the templates are better suited when there are relatively fe w dynamic elements. Also they are an excellent tool if you have a existing output file you want to use as a prototype. It is a natural an appealing approach to replace the dynamic bits with equivalent macro definitions. On the other hand, at a certain point, the templates get too difficult to decipher and maintain if they are filled with complex macro structures. Then we typically cut out the complex bits and turn them into pure macro files, which we invoke from the template file. You will find a detailed description of the code generation mechanism at http://www.uhcommunications.com/help/q3gdmo/q3gdmoTHE_ GENERATOR.ht m with more elaborate examples. You may also benefit from studying the template libraries that comes with Q3ADE3G, primarily stored in the q3ade/templates directory. In the next chapter we provide an intro to the information structures in the gdmo compiler to be used by the code generation macros.

Doc. No. A0604.xxxx

UH Communications

Page 9

The Code Generation Information Model

To extract information from the GDMO compiler, you need to understand the way information extracted from the GDMO/ASN.1 specifications is made available by the compiler. The information model looks somewhat like this (not all details

are shown). The detailed description of the content of each information object is found at: http://www.uhcommunications.com/help/q3gdmo/q3gdmoRefer ence_of_compiler_Informatio.ht m

Page 10

UH Communications A/S

Doc. no. A0604.xxxx

The command line parameter G forces the code generation template to start at in context of the GDMOModule with the given name. Hence the sample call: chkgdmo -g ListItems.mac -G MyModel My Mode l.gdmo The magic command is then the FOREACH macro, which enables you to access elements inside the current context. An example: If you want to list the package defined in a GDMO specification: FOREACH(Package) PRINT(Name) ENDF OR The commands between the FOREACH and the ENDFOR w ill be repeated for each package in the GDMO specification denoted by the G parameter provided at the compiler call. The current context will shift to the actual GDMOPackage information object while between the FOREACH and ENDFOR. Hence you may embed another FOREACH inside the first to list the attributes inside that package: FOREACH(Package) FOREACH(Attribute) PRINT(Name) ENDF OR ENDF OR And so on. Read about the available macros at: http://www.uhcommunications.com/help/q3gdmo/commonT HE _GENERATOR.ht m

Dynamic Macro Variables Invocation of Macros

and

Implicit

Another important feature to learn is the ability to create new variables in the data structure during code generation. You may def ine a variable in a given context by means of the macro DEFINEMETA(<variable>,<value >) You may also defined it the global scope using the macro DEFINE(<variable>,<value>) The variable may then be referenced by succeeding macro commands.

Doc. No. A0604.xxxx

UH Communications

Page 11

To dereference a variable name in an expression, the compiler first looks in the current context. If it is not there, it looks for it in the global scope. If it is not resolved, then the compiler will attempt an implicit invocation of a macro with the same name as the unresolved variable. The output of this macro (always a text string) will then become the dereferenc ed value of that variable. An example: You have a macro with the content: FOREACH(Package) PRINT(UpperName) ENDF OR The UpperName is not a known variable in any Package or in the global scope. Therefore the compiler looks for a macro file w ith the name UpperName.mac and will invoke this macro in the current context, that is in whatever Package it is at. We create a macro file w ith the name UpperName.mac and this content: DEFINEMETA(UpperName, toupper(Name)) PRINT(UpperName) The first statement will create a new UpperName variable in the current context. The second macro will return the content of this variable as the result of the macro. The output of this macro will then be used as the dereferenced value of UpperName . In this example, the UpperName w ill be invoked once for each package defined in the GDMO specification at hand. Furthermore, since the variable is defined by the macro, it will be not invoked again when addressed in the same context. If you want the macro to be invoked every time, then simply skip the DEFINEMETA statement. In this example we used the build-in function toupper. Read about the available build-in functions at: http://www.uhcommunications.com/help/q3gdmo/q3gdmoRefer ence_of_Builtin_macro_funct.htm

Page 12

UH Communications A/S

Doc. no. A0604.xxxx

Fragments
An issue that will soon appear is the need to tailor code generation for individual GDMO/ASN.1 mode ls. You may want only some elements to appear in the output and leave others out. You may want to assign individual names to elements, which cannot be derived mechanically, e.g. if you are to integrate with an existing TMN development environment. You may even want to manipulate the definitions w hich comes from a 3 rd party source without ref raining to editing the specifications themselves. For this purpose, Fragments. we have introduced the concept of

A Fragment definition is a file, which looks much like a gdmo definition. But it refers to an existing GDMO specification and through it, you may add information to the specification, e.g. meta variables and you may exclude elements of the information model from the code generation phase. A detailed description of the feature is found at: http://www.uhcommunications.com/help/q3gdmo/q3gdmoThe_ Fragment_specifications.ht m

In App. A you find the file MyModelF ragment.gdmo . Further details TBA.

Doc. No. A0604.xxxx

UH Communications

Page 13

App A: Samples

Content of MyModel.gdmo:
#ifndef __MyModel__ #define __MyModel__ #include <X721.gdmo> #include "MySyntaxes.asn" --<GDMO.Document "MyModel">---<UHC.ASN1Module MyModuleSntx>-myObject MANAGED OBJECT CLASS DERIVED FROM "X.721":top; CHARACTERIZED BY myObjectPackage PACKAGE ATTRIBUTES myObjectId GET SET-BYCREATE, wiseSaying GET-REPLACE, aValue GET REPLACE-WITHDEFAULT ; ; ; REGISTERED AS { oidMyModelObjectClass 1 }; myObjectId ATTRIBUTE WITH ATTRIBUTE SYNTAX MySyntaxes.String; MATCHES FOR EQUALITY ; REGISTERED AS {oidMyModelAttribute 1}; wiseSaying ATTRIBUTE WITH ATTRIBUTE SYNTAX MySyntaxes.String; MATCHES FOR EQUALITY ;

Page 14

UH Communications A/S

Doc. no. A0604.xxxx

REGISTERED AS {oidMyModelAttribute 2}; aValue ATTRIBUTE WITH ATTRIBUTE SYNTAX MySyntaxes.Integer; MATCHES FOR EQUALITY ; REGISTERED AS {oidMyModelAttribute 3}; myNamebinding NAME BINDING SUBORDINATE OBJECT CLASS myObject AND SUBCLASSES; NAMED BY SUPERIOR OBJECT CLASS "Recommendation X.721 : 1992":system AND SUBCLASSES; WITH ATTRIBUTE myObjectId; CREATE WITH-REFERENCE-OBJECT; DELETE ; REGISTERED AS { oidMyModelNameBinding 1}; --<GDMO.EndDocument>-#endif __MyModel__

Content of MySyntaxes.asn
#ifndef __MySyntaxes_ASN_ #define __MySyntaxes_ASN_ #include "X721Attr.asn" MySyntaxes {joint-iso-ccitt(0) management(32) private(100) oidMyModel(1001) oidMySyntaxesASN(1) } DEFINITIONS IMPLICIT TAGS ::= BEGIN -- EXPORTS everything IMPORTS AttributeList FROM X721Attr { joint-iso-ccitt ms(9) smi(3) part2(2) asn1Module(2) 1 }; oidMyModelInformationModel OBJECT IDENTIFIER ::= {joint-iso-ccitt(0) management(32) private(100) oidMyModel(1001) 2 } oidMyModelObjectClass OBJECT IDENTIFIER ::= {oidMyModelInformationModel managedObjectClass(3)}

Doc. No. A0604.xxxx

UH Communications

Page 15

oidMyModelPackage OBJECT IDENTIFIER ::= {oidMyModelInformationModel package(4)} oidMyModelNameBinding OBJECT IDENTIFIER ::= {oidMyModelInformationModel nameBinding(6)} oidMyModelAttribute OBJECT IDENTIFIER ::= {oidMyModelInformationModel attribute(7)} Integer ::= INTEGER String ::= IA5String MySequence ::= SEQUENCE { anAttributeList [1] AttributeList, anInteger [2] Integer, aString [3] String } MyNewSyntax ::= SET OF SEQUENCE { a INTEGER, REAL, c SET OF OBJECT IDENTIFIER } END #endif

Content MyModelFragment.gdmo
#ifndef __MyModelFragment__ #define __MyModelFragment__ #include "X721Fragment.gdmo" #include "MySyntaxesAQ3Fragment.asn" #include "MyModel.gdmo" MyModelFragment FRAGMENT CPPCLASSNAME MyModel; -- Defining a C++ class names prefix for MyModel LOCATIONS HDIR "$(HDIR)", SDIR "$(TOPDIR)/MyModel", LIBDIR "$(LIBDIR)", ETCDIR "$(ETCDIR)", BINDIR "$(BINDIR)" ; REQUIRES X721Fragment; -- add names of other fragments that this fragment depens on IMPLEMENTS FROM "MyModel", ALL -- Simply includes all MyModel components -- Here you may tailor the formal GDMO specification ,myObject MANAGED OBJECT CLASS META Persistent 0; -- Make the object instances persistent by default META ExpandAttributes 2; -- Generate Get/Set methods ;,

Page 16

UH Communications A/S

Doc. no. A0604.xxxx

-- Defining a Managed Object Refinement class ,rfMyObject MANAGED OBJECT CLASS DERIVED FROM myObject; ALLOMORPH TO myObject CREATE; TEMPLATE "DCXXMOC" NOREPLACE; META WakeUp 10; ; ; META UseSMIAttr 1; -- Direct the compiler to use SmiAttr classes as attr base clases wherever relevant META AsnModule "MySyntaxes"; -- the related ASN.1 module the same fragment library META NPOImage 1; -- Default Forward compatible POIMage format ; #endif

Doc. No. A0604.xxxx

UH Communications

Page 17

Generation Macro: ListItems.mac

PRINT("\n---- GDMO Items in "+Name+" ------\n") PRINT("Name, OID\n") FOREACH(Item) IF(#OIDdot) PRINT(Name+", "+OIDdot+"\n") ELSE PRINT(Name+", unregistered\n") ENDIF ENDFOR

Generation Macro 2: ListItems2.mac

GENERATE("ListItems.txt", "MyModel-Items.txt")

Generation Template: ListItems.txt

---- GDMO Items in $$Name$$ -----Name, OID $$FOREACH(Item) $$ $$ $$ IF(#OIDdot) ELSE ENDIF $$Name$$, $$OIDdot$$ $$Name$$, unregistered $$ENDFOR

Page 18

UH Communications A/S

Doc. no. A0604.xxxx