Built-in Routines

mikroPascal PRO for PIC compiler provides a set of useful built-in utility functions. Built-in functions do not have any special requirements. You can use them in any part of your project.

The Delay_us and Delay_ms routines are implemented as “inline”; i.e. code is generated in the place of a call, so the call doesn’t count against the nested call limit.

The Vdelay_ms, Vdelay_Advanced_ms, Delay_Cyc and Get_Fosc_kHz are actual Pascal routines. Their sources can be found in Delays.mpas file located in the Uses folder of the compiler.

Lo

Prototype

function Lo(number: longint): byte;

Returns

Lowest 8 bits (byte)of number, bits 7..0.

Description

Function returns the lowest byte of number. Function does not interpret bit patterns of number – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers).

Example
d := 0x12345678; 	
tmp := Lo(d);  // Equals 0x78

Lo(d) := 0xAA; // d equals 0x123456AA

Hi

Prototype

function Hi(number: longint): byte;

Returns

Returns next to the lowest byte of number, bits 8..15.

Description

Function returns next to the lowest byte of number. Function does not interpret bit patterns of number – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers).

Example
d := 0x12345678; 	
tmp := Hi(d);  // Equals 0x56

Hi(d) := 0xAA; // d equals 0x1234AA78

Higher

Prototype

function Higher(number: longint): byte;

Returns

Returns next to the highest byte of number, bits 16..23.

Description

Function returns next to the highest byte of number. Function does not interpret bit patterns of number – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers).

Example
d := 0x12345678; 	
tmp := Higher(d);  // Equals 0x34

Higher(d) := 0xAA; // d equals 0x12AA5678

Highest

Prototype

function Highest(number: longint): byte;

Returns

Returns the highest byte of number, bits 24..31.

Description

Function returns the highest byte of number. Function does not interpret bit patterns of number – it merely returns 8 bits as found in register.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers).

Example
d := 0x12345678; 	
tmp := Highest(d);  // Equals 0x12

Highest(d) := 0xAA; // d equals 0xAA345678

LoWord

Prototype

function LoWord(val : longint) : word;

Description

The function returns low word of val. The function does not interpret bit patterns of val – it merely returns 16 bits as found in register.

Parameters :

  • val: input value

Parameters number
Returns

Low word of val, bits 15..0.

Requires

Nothing.

Example
d := 0x12345678; 	
tmp := LoWord(d);  // Equals 0x5678

LoWord(d) := 0xAAAA; // d equals 0x1234AAAA
Notes

None.

HiWord

Prototype

function HiWord(val : longint) : word;

Description

The function returns high word of val. The function does not interpret bit patterns of val – it merely returns 16 bits as found in register.

Parameters :

  • val: input value

Parameters number
Returns

High word of val, bits 31..16.

Requires

Nothing.

Example
d := 0x12345678; 	
tmp := HiWord(d);  // Equals 0x1234

HiWord(d) := 0xAAAA; // d equals 0xAAAA5678
Notes

None.

Inc

Prototype

procedure Inc(var par : longint);

Returns

Nothing.

Description

Increases parameter par by 1.

Requires

Nothing.

Example
p := 4;
Inc(p);  // p is now 5

Dec

Prototype

procedure Dec(var par : longint);

Returns

Nothing.

Description

Decreases parameter par by 1.

Requires

Nothing.

Example
p := 4;
Dec(p);  // p is now 3

Chr

Prototype

function Chr(code : byte) : char;

Returns

Returns a character associated with the specified character code.

Description

Function returns a character associated with the specified character code. Numbers from 0 to 31 are the standard non-printable ASCII codes.

This is an “inline” routine; the code is generated in the place of the call.

Requires

Nothing.

Example
c := Chr(10);  // returns the linefeed character

Ord

Prototype

function Ord(character : char) : byte;

Returns

ASCII code of the character.

Description

Function returns ASCII code of the character.

This is an “inline” routine; the code is generated in the place of the call.

Requires

Nothing.

Example
c := Ord('A');  // returns 65

SetBit

Prototype

procedure SetBit(var register : byte; rbit : byte);

Returns

Nothing.

Description

Function sets the bit rbit of register. Parameter rbit needs to be a variable or literal with value 0..7. See Predefined globals and constants for more information on register identifiers.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
SetBit(PORTB, 2);  // Set RB2

ClearBit

Prototype

procedure ClearBit(var register : byte; rbit : byte);

Returns

Nothing.

Description

Function clears the bit rbit of register. Parameter rbit needs to be a variable or literal with value 0..7. See Predefined globals and constants for more information on register identifiers.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
ClearBit(PORTC, 7);  // Clear RC7

TestBit

Prototype

function TestBit(register, rbit : byte) : byte;

Returns

If the bit is set, returns 1, otherwise returns 0.

Description

Function tests if the bit rbit of register is set. If set, function returns 1, otherwise returns 0. Parameter rbit needs to be a variable or literal with value 0..7. See Predefined globals and constants for more information on register identifiers.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
flag := TestBit(PORTE, 2);  // 1 if RE2 is set, otherwise 0

Delay_us

Prototype

procedure Delay_us(time_in_us: const dword);

Returns

Nothing.

Description

Creates a software delay in duration of time_in_us microseconds (a constant). Range of applicable constants depends on the oscillator frequency.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
Delay_us(1000);  // One millisecond pause 

Delay_ms

Prototype

procedure Delay_ms(time_in_ms: const dword);

Returns

Nothing.

Description

Creates a software delay in duration of time_in_ms milliseconds (a constant). Range of applicable constants depends on the oscillator frequency.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
Delay_ms(1000);  // One second pause 

Vdelay_ms

Prototype

procedure Vdelay_ms(time_in_ms : word)

Returns

Nothing.

Description

Creates a software delay in duration of time_in_ms milliseconds (a variable). Generated delay is not as precise as the delay created by Delay_ms.

Note that Vdelay_ms is library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Requires

Nothing.

Example
pause := 1000;
Vdelay_ms(pause);  // ~ one second pause

VDelay_Advanced_ms

Prototype

procedure VDelay_Advanced_ms(time_ms, Current_Fosc_kHz: word);

Returns

Nothing.

Description

Creates a software delay in duration of time_in_ms milliseconds (a variable), for a given oscillator frequency. Generated delay is not as precise as the delay created by Delay_ms.

Note that Vdelay_ms is library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Requires

Nothing.

Example
pause := 1000;
fosc := 10000;

VDelay_Advanced_ms(pause, fosc);  // Generates approximately one second pause, for a oscillator frequency of 10 MHz

Delay_Cyc

Prototype

procedure Delay_Cyc(Cycles_div_by_10 : byte)

Returns

Nothing.

Description

Creates a delay based on MCU clock. Delay lasts for 10 times the input parameter in MCU cycles.

Note that Delay_Cyc is library function rather than a built-in routine; it is presented in this topic for the sake of convenience. There are limitations for Cycles_div_by_10 value. Value Cycles_div_by_10 must be between 2 and 257.

Requires

Nothing.

Example
Delay_Cyc(10);  // Hundred MCU cycles pause

Clock_kHz

Prototype

function Clock_kHz(): word;

Returns

Device clock in kHz, rounded to the nearest integer.

Description

Function returns device clock in KHz, rounded to the nearest integer.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
clk := Clock_kHz();

Clock_MHz

Prototype

function Clock_MHz(): byte;

Returns

Device clock in MHz, rounded to the nearest integer.

Description

Function returns device clock in MHz, rounded to the nearest integer.

This is an “inline” routine; code is generated in the place of the call, so the call doesn’t count against the nested call limit.

Requires

Nothing.

Example
clk := Clock_MHz();

Get_Fosc_kHz

Prototype

function Get_Fosc_kHz() : longint;

Returns

Device clock in kHz.

Description

Function returns device clock in kHz, rounded to the nearest integer.

Get_Fosc_kHz is a library function rather than a built-in routine; it is presented in this topic for the sake of convenience.

Requires

Nothing.

Example
clk := Get_Fosc_kHz();

Swap

Prototype

function Swap(arg : byte) : byte;

Returns

Returns byte consisting of swapped nibbles.

Description

Swaps higher nibble (bits 7..4) and lower nibble (bits 3..0) of byte-size parameter arg.

Requires

Nothing.

Example
PORTB := 0xF0;
PORTA := Swap(PORTB);  // PORTA = PORTB = 0x0F

Reset

Prototype

procedure Reset();

Returns

Nothing.

Description

This procedure is equal to assembler instruction reset. This procedure works only for P18.

Requires

Nothing.

Example
Reset(); // Resets the MCU

ClrWdt

Prototype

procedure ClrWdt();

Returns

Nothing.

Description

This procedure is equal to assembler instruction clrwdt.

Requires

Nothing.

Example
ClrWdt(); // Clears WDT

DisableContextSaving

Prototype

procedure DisableContextSaving();

Returns

Nothing.

Description

Use the DisableContextSaving to instruct the compiler not to automatically perform context-switching.
This means that no register will be saved/restored by the compiler on entrance/exit from interrupt service routine, except STATUS, WREG and BSR registers in high priority interrupt ('Fast Register Stack').

This exception can be overridden by placing an asm RETFIE, 0 instruction at the end of the high priority interrupt routine (with redirecting all routine exits to this instruction).
Thus, DisableContextSaving directive enables the user to manually write code for saving registers upon entrance and to restore them before exit from interrupt.

Requires

This routine must be called from main.

Example
DisableContextSaving(); // instruct the compiler not to automatically perform context-switching

SetFuncCall

Prototype

procedure SetFuncCall(FuncName: string);

Returns

Nothing.

Description

If the linker encounters an indirect function call (by a pointer to function), it assumes that any routine whose address was taken anywhere in the program can be called at that point if it's prototype matches the pointer declaration.

Use the SetFuncCall directive within routine body to instruct the linker which routines can be called indirectly from that routine :
SetFunCCall (called_func[, ,...])

Routines specified in the SetFunCCall argument list will be linked if the routine containing SetFunCCall directive is called in the code no matter whether any of them was explicitly called or not.

Thus, placing SetFuncCall directive in main will make compiler link specified routines always.

Requires

Nothing.

Example:
procedure first(p, q: byte);
begin
...
  SetFuncCall(second); // let linker know that we will call the routine 'second'
...
end

SetOrg

Prototype

procedure SetOrg(RoutineName: string; address: longint);

Returns

Nothing.

Description

Use the SetOrg() routine to specify the starting address of a routine in ROM.

Requires

This routine must be called from main.

Example
SetOrg(UART1_Write, 0x1234);

GetDateTime

Prototype

function GetDateTime() : string;

Returns

String with date and time when this routine is compiled.

Description

Use the GetDateTime() to get date and time of compilation as string in your code.

Requires

Nothing.

Example
str := GetDateTime();

DoGetDateTime

Prototype

function DoGetDateTime() : string;

Returns

String with date and time when this routine is compiled.

Description

Use the DoGetDateTime() to get date and time of compilation as string in your code.

Requires

Nothing.

Example
str := DoGetDateTime();

GetVersion

Prototype

function GetVersion() : string;

Returns

String with current compiler version.

Description

Use the GetVersion() to get the current version of compiler.

Requires

Nothing.

Example
str := GetVersion(); // for example, str will take the value of '8.2.1.6'

DoGetVersion

Prototype

function DoGetVersion() : string;

Returns

String with current compiler version.

Description

Use the DoGetVersion() to get the current version of compiler.

Requires

Nothing.

Example
str := DoGetVersion(); // for example, str will take the value of '8.2.1.6'

New

Prototype

procedure New(var Ptr : pointer);

Description

Allocates a block of memory from the memory Heap, taking care of the alignment. It is recommended to use this routine instead of GetMem.

Parameters
  • Ptr: variable of any pointer type, pointing to an object which is to be allocated.
Returns

Returns a pointer to the memory block allocated by the function; Otherwise 0 (no free blocks of memory are large enough).

Requires

Nothing.

Notes

None.

Dispose

Prototype

procedure Dispose(var Ptr : pointer);

Description

Disposes a block of memory from the memory Heap, referenced by Ptr and returns its memory to the Heap.

Parameters
  • Ptr: variable of any pointer type previously assigned by the New procedure.
Returns

Requires

Nothing.

Notes

After calling this routine, the value of Ptr is nil (0) (not assigned pointer).

Copyright (c) 2002-2012 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries? 
Find them on LibStock - A place for the code