  Plm2C  - A translator from the PL/M language to  the  C language
  Copyright (c) 1989-1998 by Ilan Mahalal.  All rights reserved 


 
            
 
                      P L M 2 C     specifications
    

     Plm2C is a translator from  the  PL/M  language  to  the  C  language.
  Since the two languages are different , an effort was  made  to  produce 
  a translation that will be clear and readable to the original  software
  programmer.  Another objective is to keep  the  translation , as  far  as 
  possible , in the  C  language programming style.

     Here is a partial list of non trivial and important translations that 
  are handled during the translation -

    1)    A structure can be defined by several  "literally"  macros. In a
          "literally" macro definition, another name of a macro can appear.

    2)    All "based" declarations are handled by using the based pointer.

    3)    All "AT" declarations that define "unions" in  C  are handled.

    4)    External labels are correctly translated.

    5)    All nested include files are translated.


    Following is a complete list of problematic translations  that are not  
  being automatically handled.  Plm2C produces an error or warning message
  when any of these problems is encountered. Each one of these problematic
  translations can be handled as will be detailed later.
    ( However the following problems  are quite rare  and  usually will not
  be encountered. )


    1)    Plm2C  does not translate  a  procedure  that is declared inside
        another procedure. An automatic translation, may result in an ugly
        and unclear source code. This problem can be handled by	moving the
        nested procedures outside the  main procedure , and calling  Plm2C
        to operate on the modified file. 
          This is  a technical  modification  that  should  not change the
        original code , since the modified code will perform the same.
   

    2)    When defining a structure type by several concatenated "literally"
        macros , these macros should follow each other in the correct order.
        For example -
 
          declare START  literally 'structure ( fld1  byte,' ;
          declare END    literally 'fld2  word)' ;

          The START and END macros define one structure type , and the  END
        macro should appear right after START.
          Declaration of structure fields cannot be broken when moving from 
        one macro to another.  In the above  example   "fld1"   declaration 
        should start and end in the same macro ( START ).
          If the macros are not in the correct  order  then they  should be 
        placed correctly before running Plm2C again.  This is  a  technical 
        modification that do not change the original code.

    3)    When a structure type is being declared  by  several  "literally"
        macros ,as was described in 2, the same macros cannot be  used  for 
        defining another structure type. For example the macros  START  and
        END , in the above example , define one structure type.
        The following declaration -

          declare struct1  START END ;

        produces a new structure named "struct1" of the type defined by the
        macros START and END.
          Another declaration like -

           declare struct2  START  FIN ;

        should not appear in the source code , since  the  START  macro was
        already used before to define another structure type.
        ( START and FIN define a new structure type ).
           This problem can be solved by defining a new macro , the same as
        START  but with  another name , and adding it to the source code by
        using the rules in paragraph  2  above.
          This is a technical modification that do not change the  original
        code.

     4)  Plm2c does not support nested structures.
	Flattening the structures should be done in two places:
	   1. The structure definition itself where you put all fields in the 
	      same level.
	   2. Change all references to the  (previously) nested fields within
 	      the structure.  You  can  automate  it  with a script or with a
 	      search and replace using an editor. 

     5)   Labels with the same name should not appear in the same file. If 
        different labels share the same  name  then  their  name should be 
        changed. References to these  labels  should  use  the  new  names 
        according to the scoping rules in PL/M.

     6)   Interrupt procedures are translated as ordinary procedures , but
        Plm2C gives  a  warning  message  when  encountering  an interrupt 
        procedure.
        
     7)   Usage of the "AT" attribute with a numerical value , or with  an 
        expression that is not an address of an identifier , is ignored.
        Plm2C produces a warning message in this line.

     8)   Translation of the expression  -

            @(const1,const2, . . . ,constN)

        is  possible  if  all  const1,const2, . . . ,constN  are  strings.
        Otherwise this structure should be redefined by an array of chars.

     9)   Assignment of two ASCII characters to an identifier of type word
        is not translated , and a syntax error is produced. For example -

          f1 = 'AB' ;

        This problem can  be  solved by  using  the  ASCII code of the two 
        characters instead.
        
     10)   The quotation mark  "'"  cannot appear inside a  literally macro
        definition. For example -

         declare mac literally  '''A''' ;
       
        This problem can  be  solved  by  using  the  ASCII  code  of  the 
        desired character ( in this example 'A' ).

     11)   You should pay attention where you use the  compiler  directives 
	 $if $else and $end. These are compiler directives definitions that 
	 are processed before the compilation by the (PL/M) preprocessor. 
	 Plm2c behaves like a compiler and maintains a symbol table in order
	 to enable context sensitive  and  intelligent  translation.  It can 
	 translate also the  $if $else and $end compiler directives in most 
	 cases. But when the $if $else $end directives are being used to 
	 redeclare the same variable, it cannot choose which declaration to
	 use.  For example:

		$if Version1
			declare A Byte;
		$else
			declare A Word;
		$end
	
	 In the (PL/M) compilation process it is rather clear:   only one is 
	 chosen in the preprocessing phase. In the translation both should be
 	 translated so a variable can have several  different  types  at  the
	 same time.  This  is  not  possible  in a translation which tries to 
	 understand the semantics of the program and choose the  best  suited 
	 equivalent translations in C.  It  can  be  possible in a completely 
	 mechanical translation but it will result in a very ugly and unusable 
	 translation which you would not like to have. 
	 If you  have  two  different  variables  declarations  or  execution 
	 statements, the translation will work correctly. But In the case of 
	 the  above  example,  Plm2c  will  issue  an  error  that  "A"  has 
	 multiple declarations.
 	 You can work around it by choosing one declaration  and  translating 
	 the file. Then add the compiler directives in the C source code. 
	 Another solution is to break the  PL/M  source code file, which uses 
	 these directives, to several files depending on the structure of the
	 $if $else and $end directives.
	 Always work on a copy of the original PL/M source code, you may need
	 sometimes to do cosmetic changes to help Plm2c do  the right job for 
	 you.
        