JAL manual - language - pragma's

The pragma name can be used to document the file name of a source file. The compiler checks that the stated name is indeed the current file name (the .jal extension must be omitted).

   -- a comment can state anything:
   -- this is file xyz

   -- but when this compiles you can be sure 
   -- that this is indeed file e0001!
   pragma name e0001 

The target specification pragma's give the compiler information about the target. The target chip (16c84, 16f84, SX18, SX28) and oscillator setting (hs, xt, rc, lp or internal ) must be specified. Optionally the watchdog (on or off, default off), protection (on or off, default off) and powerup delay (on or off, default on) can be specified. The clock frequency is not needed by the compiler, but some libraries ( busy delay, interval delay, hd44780, asynch ) need the clock frequency which is provided by the (pre-declared) global variable target_clock.

It is possibly to put all required pragma's in a project's source file, but it will often be easier to include one of the standard target files (16c84_4, SX28_50 etc.).

   -- 16c84_14.jal
   pragma target chip        16c84
   pragma target clock       4_000_000
   pragma target osc         xt
   pragma target watchdog    off
   pragma target powerup     on
   pragma target protection  off

The pragma jump_table informs the compiler that the current subprogram contains code which manipulates the program counter via the PCL register. The compiler will ensure that the PCLATH bits are set appropriatelty.

   procedure _seven_table is
      pragma jump_table
         assembler
            addwf 2, f
            retlw seven_0
            ...
            retlw seven_f
      end assembler
   end procedure   

The error pragma produces a compilation error when it reaches the code generation phase of the compiler. It can be used to check for certain errors at compilation time, for instance an un-anticipated clock frequency.

Note that constant expressions evaluation and dead branch elimination takes place even when all optimization is switched off, hence contructs like the one below will work even without optimization.

   if target_clock < 4_000_000 then
      pragma error -- clock frequency must be at least 4 MHz
   end if

The test pragma's can be used for two purposes:

• testing the compiler's error detection mechanism
• testing the code generated by the compiler

The pragma test catch states that the next line should cause a compilation error at the indicated position. When this is the case the compiler will return a success condition, otherwise the compiler will return a failure condition.

   
   var byte n
   pragma test catch 9
   var bit n

The pragma test assert states that during simulated execution at this point of the program the indicated variable should have the indicated value. The compiler contains an integrated CPU core simulator which is activated by the -t option.

The pragma test done states that the running simulation should be ended. The compiler will return a success status.

   
   var byte a, b, c
   a = 5
   b = 6
   c = a * b
   pragma test assert c == 30
   c = a % b
   pragma test assert c == 5
   pragma test done