Kollmorgen Support Network

Macro Language | 23 Oct 2008 | |

Macro Language

Valid for S300, S700

Table of Contents

  1. Macro language
    1. Program flow control
      1. IF
      2. #IF
      3. WHILE
      4. GOTO
    2. Variables
      1. BYTE
      2. WORD
      3. LONG
      4. DLONG
      5. Predefined User Variables
    3. Access to ASCII Parameters
    4. Expressions and Operations
      1. Arithmetic/shift operators
      2. Relational operators
      3. Logical operators
      4. Binary operators
      5. MULDIV Function
      6. Subroutines
  2. Time / Performance restrictions
  3. Commands and Functions
Back to top

Macro language

The user can write an application program which will be running inside the S300/S700. The language is a subset of IEC 601131-3 structured text. Because this is very similar to BASIC or C an application engineer does not need much training to write a simple program. The system uses an internal compiler which allows fast program execution. The program source is stored in one segment of the amplifier's flash memory (actual 60kByte) and will be compiled automatically during the boot phase. If the amplifier is not enabled the program can be modified and recompiled.
The development tool  MacroStar supports the engineer to write a program.

Program flow control

Program flow control gives a system most of its "intelligence", the ability to evaluate conditions and take different actions depending on the outcome. The macro language supports IF .. THEN ELSE END_IF, WHILE .. DO     END_WHILE, REPEAT .... UNTIL, GOTO and FOR .......

IF

The basic program flow control uses the syntax:

IF <expression> THEN

    .....

ELSE

    ...

END_IF ;

The ELSE path is optional and can be skipped. The word IF is followed by an expression, which can include comparisons between variables and/or a constant or a simple statement. For IF ... THEN, ELSE and END_IF should always used a separate source code line and it is recommended to use tabs or spaces to structure the source code.

The following relational operators are allowed:
> greater then
< less then
>= greater than or equal to
<= smaller than or equal to
= equal to
<> not equal to
IF Example:

IF var1=12 THEN
checks whether var1 is equal 12 (True) or not (false).

IF var1 THEN
checks whether var1 is not zero (True) or zero (false).

If the expression is true the program path between THEN and ELSE (if used) or END_IF is executed. If the expression is false the optional path between ELSE and END_IF will be processed.

#IF

The #IF (sharp IF) statement is a special extension to IEC 601131-2 structured text. It works like a C preprocessor #if instruction. The expression will be processed and the execution path will be selected during compilation time. Due to that constrain only configuration variables (do not change during operation) or constants should be used in #IF expressions. The #IF is a very powerful tool to optimize execution speed because all unnecessary decisions are done during compilation time.
 
The #IFDEF acts like a 'C' #ifdef. The compiler checks whether the following variable is already defined (true) or not (false).

WHILE

The

WHILE .... DO
            ........
END_WHILE ;

statement allows structured looping. The condition is handled in the same way its handled in the IF .. THEN statement. Looping (jumping back) is only allowed in the task PLCMAIN.

GOTO

The statement GOTO <Label> allows the servo amplifier to execute the program out of the sequential order. The word GOTO followed by a label will force the program execution to jump to the line with that label. It is possible to create loops that will never end. Therefore in all real time tasks a jump back is not allowed. Looping and jumping back is only allowed in the task PLCMAIN. If possible it is recommended not to use the GOTO statement to create more structured programs.

Variables

Variables are names that represents data values used in the macro statements. The value represented by a variable can be assigned by setting it equal to a constant, or it can be the result of calculations in the program. All variables have to be defined before they can be used.

Variable names can be defined with a max length of 10 characters. Variables names may not be the same as macro keywords, operator names and function names. The characters used to form variable names are the alphabet and the numbers 0-9. The first character of the name must be a letter. Variable names must always  be written in capital letters!

The macro language offers the user different variable types which can be stored in different RAM areas. All variables are signed and global (like BASIC). Floating point and array are not implemented. Nearly all calculations are sign extended to 32 bit and are processed with 32 bit operations.

BYTE

The smallest variable is a BYTE it can store values from – 128 to 127 (1 Byte)
Example:
BYTE VAR1,VAR ;

WORD

The type WORD is 2 byte wide and can store values from – 32768 to 32767
Example:
WORD VAR2;

LONG

The type LONG uses 4 byte and can store values from – 2147483648 to 2147483647
Example:
LONG VAR3;

DLONG

The type DLONG uses 8 byte and can store values from – 263 to 263
Example:
DLONG VAR4;
The type DLONG is not a standard variable type. For this reason the standard expressions and operations cannot be used. However, there are some internal macro functions that can be used for handling of the 64 bits variables.
For example:
CLRDLONG(Var64);    -> Var64 := 0;
SETDLONG(Var64_1,Var64_2);   -> Var64_1 := Var64_2;
ADDDLONG(Var64_1,Var64_2,Var32);   -> Var64_1 := Var64_2 + Var32;
SUBDLONG(Var64_1,Var64_2,Var32);   -> Var64_1 := Var64_2 - Var32;;

Predefined User Variables

There are 16 predefined general purpose variables of type LONG that can be used in the program. They can be changed e.g. via the RS232 interface like all other ASCII parameters, are saved with the standard SAVE command and stored in the parameter file.

Variable Name
CAN Object Number
Profibus PNU
DPRVAR1
36A6h or 2090h Subindex 1 (see CANOpen manual)
2022d
DPRVAR2
36A7h or 2090h Subindex 2
2023d
...
 
...
DPRVAR8
36ADh or 2090h Subindex 8
2029d
DPRVAR9
36AEh or 2030h Subindex 1 (s. CANOpen manual)
2030d
DPRVAR10
36AFh or 2030h Subindex 2
2031d
...
...
...
DPRVAR16
36B9h or 2030h Subindex 8
2037d

Beginning with firmware version 3.62 there 16 additional user variables:

Variable Name
CAN Object Number
Profibus PNU
DPV17
37BCh
1900 Index 17
DPV18
37BDh
1901 Index 17
...
 ...
 ...
DPV32
37CBh
1915 Index 17

Access to ASCII Parameters

The following functions allow access to all ASCII parameters and functions and must be used in the MAIN or in the INIT task only because they are time consuming.

//write content of user variable TEMPVAR1 to ASCII parameter MTMUX

XWRITE('MTMUX',TEMPVAR1);

//read value of PGEARO and store in user variable MYPGEARO

XREAD('PGEARO',MYPGEARO);

//create a motion task using the ORDER command

COMMAND('ORDER 192 49000 2800 8192 50 50 0 0 0 0');

Expressions and Operations

Expressions are formed using constants, variables and/or operations. An expression can be a simple variable assignment like
var1 := 13 ;
or a combination of constants, variables and operations like
var2 := 2 * var3-var4 ;
The priority of the operation is defining the processing order. The priority can be overwritten by creating sub-expressions with parentheses ( ). The parts of an expression enclosed in parentheses will be reduced to a single value before working on parts outside the parentheses. 
var2 := 2 * (var3-var4) ;
The hierarchy / priorities are defined according to IEC 601131:
Highest            ()
                       -(unary), not, bnot
                       *, /, mod
                       +, -
                       >>, <<
                       >, >=, <, <=
                       =, <>
                       &
                       |
                       xor
                       and
                       or
Lowest            :=

Arithmetic/shift operators

The arithmetic operator defines an arithmetic operation which is performed on the two operands on either side of the operator. The minus can also be used as a unary minus( var1 := -var2;)
+          signed arithmetic addition: 32 bit + 32 bit = 32 bit
-          signed arithmetic subtraction: 32 bit + 32 bit = 32 bit
*          signed arithmetic multiplication 16 bit * 16 bit = 32 bit
/           signed arithmetic division: 32 bit / 16 bit = 16 bit
mod     signed arithmetic modulo 32 bit / 16 bit = 16 bit
>>       signed arithmetic shift right (yet only with constant shifts: var1 >> 3)
<<       signed arithmetic shift left (yet only with constant shifts: var1 << 2 )

Relational operators

The relational operators are primarily used to compare the values of two operands, but they also produce an arithmetic result:
True := -1
False := 0
The relational operators are always using 32 bit:
>          greater then
<          less then
>=       greater than or equal to
<=       smaller than or equal to
=          equal to
<>        not equal to

Logical operators

The logical operator can be used to combine relational operator to a more complex expression. Before calculating each value which is not zero will be converted to true, zero is representing false. The result is true or false. These are the logical operators:
AND   logical and ( 1 AND 0 results in false(=0) )
OR      logical or ( 7 OR 0 results in true (=-1) )
XOR    logical exclusive or ( 8 XOR 1  results in false (=0) )
NOT    logical negation ( NOT 8 results in false (=0) )

Binary operators

The binary operators can be used to mask bits in a variable, they also produce a 32 bit arithmetic result:
&         binary and ( 20 & 15 results in 4 )
|           binary or ( 20 | 15 results in 31 )
^          binary xor ( 20 | 15 results in 27 )
bnot     binary not ( bnot -1 results in 0 )

MULDIV Function

For multplication and division of variables of type Long the function MULDIV can be used as follows:
 
MULDIV (VALUE1,VALUE2,VALUE3,RESULT);
 
This will multiply VALUE1 with VALUE2, divide the result by VALUE3 and put the result into RESULT.
If a multiplication only is required, VALUE3 must have a value of 1, if a division only is required, VALUE2 must have a value of 1.
It is not possible to use a number directly.

Subroutines

The call of subroutines works in different ways:
·                    Call of a fast MACRO subroutine with a sequence like:
LIMITW(OUT ,IN ,MAX ) ;
This subroutine will check the value of the variable IN and will reduce it to +/- MAX if the value is greater than MAX. The result is stored in the variable OUT. All variables are passed as pointers (like FORTRAN) and the subroutine is always inline coded. This makes code execution very fast, but for example recursion (calling itself) is not allowed.
·                    Call of a regular subroutine with a sequence like:
FUNCTION (CALCOPMODE) ;
This calls the subroutine CALCOPMODE. It is not possible to pass parameters.
 
·                    The sequence
COMMAND ('OPMODE 0')
will call the ASCII ServoStar Command interpreter to execute a switch to opmode 0. This is the easiest, but also the slowest way to execute subroutines. It should be only used in the application task PLCMAIN
·                      The sequence
   LONG YEAR ;
   YEAR := 2011;
   PRINTF ('Hello world in the year %d\n',YEAR) ;
words like a subset of the 'C' printf function. It will show on the terminal:
Hello world in the year 2011
There are in addition to the control string up to three parameters possible. The parameter type must be of the type LONG. Constants and other types are not supported yet. PRINTF should be only used in the application task PLCMAIN
Back to top

Time / Performance restrictions

The performance of the PLC programs depends on the size and the cycle time of the implemented routines. If execution of a task requires more time than is allotted, then a F32 error will result on the drive front face. The available time for executing a user macro program can vary with different versions of FW. It can also vary with the setting of S300 standard configuration variables. 
The PLC programs are compiled during the initialisation phase of the drive.
The information about the compilation progress, program errors and program size is
displayed by the serial interface (parameter MSG=2).
The number of lines displayed for every single plc program can be used for calculation of the system load caused by the plc programs.
PLC program
Load factor
PLC62
256*number of line
PLC250
64*number of line
PLC1
16*number of line
PLC4
4*number of line
PLC16
1*number of line
PLCMAIN
-
PLCINIT
-
 
The total load factor allowed for the S300/S700 is: 100000
Example:
PLC62 (size=20)
PLC1 (size=1000)
PLC16 (size=200)
 
The total load factor is: 20*256 + 1000*16 + 200 = 21320 ( is less than 100000)
 
The PLCMAIN function cannot affect the function of the drive but it's size defines the cycle time of the plc main loop. If the PLCMAIN exists, it's execution time can be controled by the command TASK. This command calculate the number of executions of the PLC main loop pro second.
When the PLCMAIN program is not running, the output of the TASK command is: PLC 0
If PLCMAIN program is not included inside the plc segment, the TASK command gives no information about this program.
 
The size of the PLCINIT function doesn’t affect the function of the drive. This function is started once immediately before other plc programs are activated (after the PLCSTART command). For this reason the execution time of the PLCINIT function delays the start of the other PLC programs. 
Back to top

Commands and Functions

Back to top

About this Article

Kollmorgen Support