Programming guideline

In the following you find the minimum requirements that you must observe and implement when programming your library. 

ūüóĻ Naming the library

Using several libraries within one project can cause problems if they do not have a unique name.

Phoenix‚ÄČContact recommends to include the library version number in the name.

  • Choose a unique name for the library. Make sure that it is unique in the entire¬†PLCnext‚ÄĮStore.
  • Insert¬†the library ID before the name, the version number at the end.
    Syntax: <Library_Name>_<Version>

Example: 

Modbus_RTU_3
<Library_Name> = Modbus_RTU
<Version> = 3

ūüóĻ Naming function blocks and functions

Using several libraries within one project can cause problems if they do not have a unique ID. 

  • Choose a unique library ID and version number for function blocks and functions.
  • Insert¬†the library ID before the name, the version number at the end.
    Syntax: <Lib_ID>_<FB_Name>_<Version>

Example: 

MB_RTU_Master_5
<Lib_ID> = MB
<FB_Name> = RTU_Master
<Version> = 5

ūüóĻ ¬†Checking input parameter validity

To avoid unexpected program behavior, the value ranges of the input paramters must be checked. 

  • Check¬†the value ranges of the input paramters of a function or a function block¬†(all parameters that can be changed from the outside) when the¬†function value range is smaller than the value range of the data type used and no check has been performed at a higher level.

Possible actions:

  • Function block error message
  • Setting default values
  • Limiting the value range
  • Starting a system task
  • Other

Example: 

(* arrBuffer is ARRAY[1..512] *)
IF ((iIndex < 1) OR (iIndex > 512)) THEN
xError := TRUE;
ELSE
arrBuffer[iIndex] := 1;
END_IF;

ūüóĻ Checking the field limits

To avoid unexpected program behavior,  you must check the field limits.

  • If array elements are accessed by an index variable that can be changed from the outside, you must ensure¬†that the index lies within the valid field limits.
  • If the field limits can be changed from the outside, you must ensure¬†that the field limits contain valid values.

Example: 

(* arrBuffer is ARRAY[1..512] *)
IF((iIndex < 1) OR (iIndex > 512)) THEN
xError := TRUE;
ELSE
arrBuffer[iIndex] := 1;
END_IF;
Alternativ:
iIndex = Limit(0,iIndex, 512);

ūüóĻ Input and outputs

Naming of inputs and outputs

The user finds his way around more quickly if the names of the inputs and outputs are the same as the function behind them.

  • Choose the name¬†of the inputs and outputs based on the meaning of the element.

Comments for inputs, outputs and inouts

If the inputs, outputs and inouts are commented, the user can understand the function faster by reading the comments. 

  • Comment all inputs, outputs and inouts in the variables worksheet.

Required inputs and outputs

Direction Description Datatype Example
Input FB activation BOOL xActivate
Output FB active status BOOL xActive
Output FB error status BOOL xError
Output Diagnostic code ‚Äí wDiagCode
ūüóĻ Library ID for global variables and¬†user-defined data types

To avoid conflicts when using several libraries that use global variables and/or user-defined data types, the names of the global variables and user-defined data types in libraries must start with the library ID. 

Syntax for global variables:  <LIB_ID>_<Variable name>

Syntax for user-defined data types: <LIB_ID>_<data type name>

  • Make sure that global variables and user-defined data types in libraries have the library ID at the beginning of the name.

Example for a global variable: MB_iCounter

Example for a user-defined data type: MB_ARR_W_1_100 : ARRAY[1..100] OF WORD;

ūüóĻ Software compilations without warnings

Warnings are always indications of potential errors that can only occur in specific runtime configurations. Therefore, all warnings must be eliminated prior to software release.

  • Make sure that the libraries do not generate warnings in the application.
ūüóĻ Spaces between keywords, operators and operands

In extended identifiers, the use of some operand symbols is permitted. To avoid problems with the use of extended identifiers and to improve readability, spaces should be used to separate keywords, operators and operands. 

  • Always use a space to separate¬†keywords, operators and operands.¬†
  • Do not use operand symbols in variable names.¬†

Example: iTemp3 := iTemp1 + iTemp2;

Negative Example: iTemp3 := iTemp1+iTemp2;

 

→ Next step: Testing a Library 

 

Or go back to Overview.

 

 

 

 


‚Äʬ† Web browser recommendation:¬†Chrome, Firefox 78 or newer, Edge 88 or newer, or Safari¬†‚Äʬ†
‚Äʬ†Published/reviewed:¬†2022-12-16¬†‚ÄĘ Revision‚ÄĮ11¬†‚Äʬ†