asn1ct(3erl)						     Erlang Module Definition						      asn1ct(3erl)

NAME

       asn1ct - ASN.1 compiler and compile-time support functions

DESCRIPTION

       The  ASN.1  compiler  takes an ASN.1 module as input and generates a corresponding Erlang module which can encode and decode the data-types
       specified. Alternatively the compiler takes a specification module (se below) specifying all input modules and generates  one  module  with
       encode/decode  functions. There are also some generic functions which can be used in during development of applications which handles ASN.1
       data (encoded as BER or PER).

EXPORTS

       compile(Asn1module) -> ok | {error,Reason}
       compile(Asn1module , Options) -> ok | {error,Reason}

	      Types  Asn1module = atom() | string()
		     Options = [Option| OldOption]
		     Option = ber_bin | per_bin | uper_bin | der | compact_bit_string | noobj | {n2n,EnumTypeName} |{outdir,Dir} |  {i,IncludeDir}
		     |	 optimize   |  driver  |  asn1config  |  undec_rest  |	{inline,OutputName}  |	inline	|  {macro_name_prefix,	Prefix}  |
		     {record_name_prefix, Prefix} | verbose
		     OldOption = ber | per
		     Reason = term()
		     Prefix = string()

	      Compiles the ASN.1 module Asn1module and generates an Erlang module Asn1module.erl with encode and decode functions  for	the  types
	      defined  in Asn1module . For each ASN.1 value defined in the module an Erlang function which returns the value in Erlang representa-
	      tion is generated.

	      If Asn1module is a filename without extension first ".asn1" is assumed, then ".asn" and finally ".py" (to be compatible with the old
	      ASN.1 compiler). Of course Asn1module can be a full pathname (relative or absolute) including filename with (or without) extension.

	      If  one wishes to compile a set of Asn1 modules into one Erlang file with encode/decode functions one has to list all involved files
	      in a configuration file. This configuration file must have a double extension ".set.asn", (".asn" can alternatively  be  ".asn1"	or
	      ".py").  The  input  files'  names  must be listed, within quotation marks (""), one at each row in the file. If the input files are
	      File1.asn , File2.asn and File3.asn the configuration file shall look like:

	      File1.asn
	      File2.asn
	      File3.asn

	      The output files will in this case get their names from the configuration file. If  the  configuration  file  has  the  name  SetOf-
	      Files.set.asn the name of the output files will be SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db .

	      Sometimes  in  a system of ASN.1 modules there are different default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The multi file
	      compilation resolves the default tagging as if the modules were compiled separately.

	      Another unwanted effect that may occur in multi file compilation is name collisions. The compiler solves this problem in	two  ways:
	      If  the  definitions  are identical then the output module keeps only one definition with the original name. But if definitions only
	      have same name and differs in the definition, then they will be renamed. The new names will be the definition name and the  original
	      module name concatenated.

	      If any name collision have occurred the compiler reports a "NOTICE: ..." message that tells if a definition was renamed, and the new
	      name that must be used to encode/decode data.

	      Options is a list with options specific for the asn1 compiler and options that are applied to the Erlang compiler.  The  latter  are
	      those  that not is recognized as asn1 specific. For preferred option use see Preferred Option Use section in users guide . Available
	      options are:

		ber | ber_bin | per | per_bin | uper_bin :
		  The encoding rule to be used. The supported encoding rules are BER (Basic Encoding Rules), PER aligned (Packed  Encoding  Rules)
		  and  PER  unaligned. If the encoding rule option is omitted ber is the default. The per_bin option means the aligned variant. To
		  use the unaligned variant the uper_bin option has to be used.

		  The generated Erlang module always gets the same name as the ASN.1 module and as a consequence of this only  one  encoding  rule
		  per ASN.1 module can be used at runtime.

		  The  ber_bin	and  per_bin  options are equivalent with the OldOptions ber and per with the difference that the generated encod-
		  ing/decoding functions take advantage of the bit syntax, which in most cases increases the performance considerably. The  result
		  from encoding is a binary or an iolist.

		der :
		  By  this  option  the Distinguished Encoding Rules (DER) is chosen. DER is regarded as a specialized variant of the BER encoding
		  rule, therefore the der option only makes sense together with the ber or ber_bin option. This option sometimes adds sorting  and
		  value checks when encoding, which implies a slower encoding. The decoding routines are the same as for ber .

		compact_bit_string :
		  Makes it possible to use a compact notation for values of the BIT STRING type in Erlang. The notation:

		BitString = {Unused,Binary},
		Unused = integer(),
		Binary = binary()

		  Unused  must be a number in the range 0 to 7. It tells how many bits in the least significant byte in Binary that is unused. For
		  details see BIT STRING type section in users guide .

		{n2n,EnumTypeName} :
		  Tells the compiler to generate functions for conversion between names (as atoms) and numbers and vice versa for the EnumTypeName
		  specified.  There  can  be  multiple	occurrences  of this option in order to specify several type names. The type names must be
		  declared as ENUMERATIONS in the ASN.1 spec. If the EnumTypeName does not exist in the ASN.1 spec the compilation will stop  with
		  an error code. The generated conversion functions are named name2num_EnumTypeName/1 and num2name_EnumTypeName/1 .

		noobj :
		  Do  not  compile (i.e do not produce object code) the generated .erl file. If this option is omitted the generated Erlang module
		  will be compiled.

		{i,IncludeDir} :
		  Adds IncludeDir to the search-path for .asn1db and asn1 source files. The compiler tries to open a .asn1db file  when  a  module
		  imports  definitions	from  another  ASN.1  module.  If  no  .asn1db	file  is  found  the  asn1  source file is parsed. Several
		  {i,IncludeDir} can be given.

		{outdir,Dir} :
		  Specifies the directory Dir where all generated files shall be placed. If omitted the files are placed in the current directory.

		optimize :
		  This option is only valid together with one of the per_bin or ber_bin option. It gives time optimized code generated and it uses
		  another  runtime  module and in the per_bin case a linked-in driver. The result in the per_bin case from an encode when compiled
		  with this option will be a binary.

		driver :
		  Option valid together with ber_bin and optimize options. It enables the use of a linked-in driver that gives considerable faster
		  decode. In ber_bin the driver is enabled only by explicit use of the option driver .

		asn1config :
		  When	one  of  the specialized decodes, exclusive or selective decode, is wanted one has to give instructions in a configuration
		  file. The option asn1config enables specialized decodes and takes the configuration file, which has the same name as	the  ASN.1
		  spec but with extension .asn1config , in concern.

		  The instructions for exclusive decode must follow the instruction and grammar in the User's Guide .

		  You can also find the instructions for selective decode in the User's Guide .

		undec_rest :
		  A buffer that holds a message, being decoded may also have some following bytes. Now it is possible to get those following bytes
		  returned together with the decoded value. If an asn1 spec is compiled with this option a tuple {ok,Value,Rest} is returned. Rest
		  may be a list or a binary. Earlier versions of the compiler ignored those following bytes.

		{inline,OutputName} :
		  Compiling  with this option gives one output module containing all asn1 run-time functionality. The asn1 specs are provided in a
		  target module Module.set.asn as described above . The name of the resulting module containing generated encode/decode  functions
		  and  in-lined  run-time  functions  will  be	OutputName.erl	. The merging/in-lining of code is done by the igor module of syn-
		  tax_tools . By default the functions generated from the first asn1 spec in the .set.asn are exported, unless a {export,[atom()]}
		  or {export_all,true} option are provided. The list of atoms are names of chosen asn1 specs from the .set.asn file.

		inline :
		  It  is  also possible to use the sole argument inline . It is as {inline,OutputName} , but the output file gets the default name
		  of the source .set.asn file.

		{macro_name_prefix, Prefix} :
		  All macro names generated by the compiler are prefixed with Prefix . This is useful when multiple protocols that contains macros
		  with identical names are included in a single module.

		{record_name_prefix, Prefix} :
		  All  record  names  generated  by  the  compiler are prefixed with Prefix . This is useful when multiple protocols that contains
		  records with identical names are included in a single module.

		verbose :
		  Causes more verbose information from the compiler describing what it is doing.

	      Any additional option that is applied will be passed to the final step when the generated .erl file is compiled.

	      The compiler generates the following files:

		* Asn1module.hrl (if any SET or SEQUENCE is defined)

		* Asn1module.erl the Erlang module with encode, decode and value functions.

		* Asn1module.asn1db intermediate format used by the compiler when modules IMPORTS definitions from each other.

       encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}

	      Types  Module = Type = atom()
		     Value = term()
		     Bytes = [Int] when integer(Int), Int >= 0, Int =< 255
		     Reason = term()

	      Encodes Value of Type defined in the ASN.1 module Module . Returns a list of bytes if successful. To get as fast execution as possi-
	      ble  the	encode function only performs rudimentary tests that the input Value is a correct instance of Type . The length of strings
	      is for example not always checked. Returns {ok,Bytes} if successful or {error,Reason} if an error occurred.

       decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}

	      Types  Module = Type = atom()
		     Value = Reason = term()
		     Bytes = [Int] when integer(Int), Int >= 0, Int =< 255

	      Decodes Type from Module from the list of bytes Bytes . Returns {ok,Value} if successful.

       validate(Module,Type,Value) -> ok | {error,Reason}

	      Types  Module = Type = atom()
		     Value = term()

	      Validates that Value conforms to Type from Module . Not implemented in this version of the ASN.1 application.

       value(Module ,Type) -> {ok,Value} | {error,Reason}

	      Types  Module = Type = atom()
		     Value = term()
		     Reason = term()

	      Returns an Erlang term which is an example of a valid Erlang representation of a value of the ASN.1 type Type . The value is a  ran-
	      dom value and subsequent calls to this function will for most types return different values.

       test(Module) -> ok | {error,Reason}
       test(Module,Type) -> ok | {error,Reason}
       test(Module,Type,Value) -> ok | {error,Reason}

	      Performs	a test of encode and decode of all types in Module . The generated functions are called by this function. This function is
	      useful during test to secure that the generated encode and decode functions and the general runtime support work as expected.
	      test/1 iterates over all types in Module .
	      test/2 tests type Type with a random value.
	      test/3 tests type <c>Type with Value .
	      Schematically the following happens for each type in the module.

	      {ok,Value} = asn1ct:value(Module,Type),
	      {ok,Bytes} = asn1ct:encode(Module,Type,Value),
	      {ok,Value} = asn1ct:decode(Module,Type,Bytes).

Ericsson AB							    asn1 1.6.16 						      asn1ct(3erl)