ParameterHandler (FB)

Epec Programming and Libraries Manual

Click here to see this page in full context

Supported platforms: CODESYS 3.5, CODESYS 3.5 SAFETY

ParameterHandler (FB)

Description

This function block takes care of parameter area. It offers methods for writing, reading, deleting parameter blocks and enabling/disabling parameter area changes. It also calculates necessary checksums and guarantee the integrity of parameter area. The whole parameter area can be deleted by calling init method with invalid keyword.

Function block set output o_ParametersChanged to true when parameter area is modified. Flag is set when WriteParameter or DeleteParameter method is called. This information can be used as a trigger for saving the parameter area to non-volatile memory. During saving the parameter area can be freezed by calling method DisableChanges.

Parameter area structure is defined in figure below. It consists of header, parameter blocks and end tag. End tag is 4 bytes long.

If save counter is used, the save counter value is written to area header and to end tag. Otherwise end tag’s value is 0x0000FFFF.

Limitations

Code template contains the parameter area handling.

Usually there is no need to use ParameterHandler function block in user code.

SSeriesHardware 1.1.2.0 automatically uses Parameter Handler's save counter for OD parameter image if OD parameter backup is in use.

Inputs

No inputs

Outputs

Output variable name	Data type	Unit	Range	Description
o_ParametersChanged	BOOL	-	-	Parameter area changed flag
o_ParamAreaLocked	BOOL	-	-	Parameter area is locked. Write and delete operations are denied.

Init method

Init method initializes pointer to parameter area and area size to ParameterHandler function block. The consistency of parameter area is verified by checking the following conditions:

Checking keyword. The input keyword i_Keyword needs to match with the keyword in parameter area.
Checking the parameter area header CRC. The parameter header CRC is calculated and compared to the value in area.
Checking that end tag has correct value and it locates in correct location. The correct location is after the last parameter block.

If save counter is in use, the area header’s save counter value shall match with end tag’s value.

If one of these checking fail the whole parameter area is formatted and the error PARAM_AREA_CORRUPTED is returned.

If input parameters are not in valid range the corresponding error is returned and parameter reading and writing are disabled.

Inputs

Input variable name	Data type	Unit	Range	Description
i_pParamArea	POINTER TO BYTE	-	≠0	Pointer to parameter area
i_ParamAreaSize	DWORD	bytes	> i_BlockMaxDataSize+ Parameter header size+ Parameter block header size	Parameter area size in bytes .
i_Keyword	DWORD	-	-	Parameter area keyword. This input needs to match with the keyword in area.
i_BlockMaxDataSize	WORD	bytes	See i_ParamAreaSize range	The maximum data size of one parameter block. Default value 2KB.

Return value

Data type	Range	Description
ENUM	ParamHandlerStatus	Init status

Error diagnostic

Conditions	Return value
Keyword mismatch	PARAM_AREA_CORRUPTED
Parameter area header CRC mismatch	PARAM_AREA_CORRUPTED
End tag mismatch	PARAM_AREA_CORRUPTED
i_pParamArea=NULL	NULL_POINTER
i_ParamAreaSize is too small	PARAM_AREA _SIZE_INVALID
i_ParamAreaSize < Parameter area read from image header (ParametersSize)	PARAM_AREA_CORRUPTED
Input parameters are valid. Keyword ok. Image header CRC ok	NO_ERROR

ReadParameter method

Method finds the correct parameter block according given inputs i_Group and i_Index. The block data is written to data buffer if the following conditions are fulfilled:

Input parameters are valid
Correct parameter block is found
The calculated CRC of requested block matches the CRC value in image
i_Size ≥ data size
Block data size is smaller or equal than the maximum allowed data size (i_ParameterMaxDataSize)
Block data is stored to allowed location. Image header variable ParametersSize defines the allowed parameter area.

If one of these checking fail the whole parameter area is formatted and the error PARAM_AREA_CORRUPTED is returned.

If input parameters are not in valid range the corresponding error is returned and parameter reading and writing are disabled.

Inputs

Input variable name	Data type	Unit	Range	Description
i_Group	WORD	-	-	Parameter group
i_Index	WORD	-	-	Parameter index. Could be OD index or some other index
i_pBuffer	Pointer to BYTE	-	≠0	Pointer to buffer to which the read data is copied.
i_Size	WORD	-	>0	Index (data buffer) size.

Outputs

Output variable name	Data type	Unit	Range	Description
o_DataSize	WORD	-	-	Size of returned data.
o_Status	ENUM	-	ParamHandlerStatus	Status of execution

Error diagnostic

Conditions	o_DataSize	Return value
Requested parameter block cannot be found	0	BLOCK_NOT_FOUND
Parameter block CRC mismatch	0	BLOCK CORRUPTED
i_pBuffer=NULL	0	NULL_POINTER
i_Size < block data size	0	BLOCK_SIZE_INVALID
Block data is not stored correct location	0	BLOCK_SIZE_INVALID
Init input parameters not valid. Null parameter area pointer or the size of parameter area invalid.	0	INIT_PARAMETERS_ INVALID
Input parameters are valid. Block found. Block CRC ok. Block size ok	i_Size	NO_ERRORS

WriteParameter method

Method writes parameter data to parameter area. If parameter block can be found from parameter area then only data need to be updated. If parameter block cannot be found then a new parameter block is added.

Inputs

Input variable name	Data type	Unit	Range	Description
i_Group	WORD	-	-	Parameter group
i_Index	WORD	-	-	Parameter index. Could be OD index or some other index
i_pBuffer	Pointer to BYTE	-	≠0	Pointer to data buffer which is written to image.
i_Size	WORD	-	>0	Index (data buffer) size.

Outputs

Output variable name	Data type	Unit	Range	Description
o_DataSize	WORD	-	-	Size of written data.
o_Status	ENUM	-	ParamHandlerStatus	Status of execution

Error diagnostic

Conditions	o_DataSize	Return value
Not enough free space	0	PARAM_AREA_FULL
i_pBuffer=NULL	0	NULL_POINTER
o_ParamAreaLocked flag is on	0	OPERATION_DISABLED
Init input parameters not valid. Null parameter area pointer or the size of parameter area invalid.	0	INIT_PARAMETERS_ INVALID
Input parameter valid. Enough free space	i_Size	NO_ERRORS

DeleteParameter method

Method deletes parameter block from parameter area.

Inputs

Input variable name	Data type	Unit	Range	Description
i_Group	WORD	-	-	Parameter group
i_Index	WORD	-	-	Parameter index. Could be OD index or some other index

Outputs

Output variable name	Data type	Unit	Range	Description
o_Status	ENUM	-	ParamHandlerStatus	Status of execution

Error diagnostic

Conditions	Return value
Requested parameter block cannot be found	BLOCK_NOT_FOUND
o_ParamAreaLocked flag is on	OPERATION_DISABLED
Init input parameters not valid. Null parameter area pointer or the size of parameter area invalid.	INIT_PARAMETERS_ INVALID
Operation successfull	NO_ERRORS

DisableChanges method

This method disables/enables the write and delete operations of parameter area. This method can be used to freeze the parameter area for example when parameters are saved to non-volatile memory.

When input i_DisableChanges is FALSE the function block output flags o_ParametersChanged and o_ParamAreaLocked are reset.

Inputs

Input variable name

Data type

Unit

Range

Description

i_DisableChanges

BOOL

TRUE – parameter area modification disabled

FALSE – parameter area modification enabled

Outputs

ResetData method

This method resets all parameter data from image and updates area header.

o_ParametersChanged flag is set TRUE to trigger saving.

ResetData is used by e.g. CANopenODSave and SSeriesHardware libraries.

Inputs

Outputs

Return value

Data type	Range	Description
ENUM	ParamHandlerStatus	Returns NO_ERROR when OK.

Error diagnostic

Conditions	Return value
o_ParamAreaLocked flag is on	OPERATION_DISABLED
Init input parameters not valid.	INIT_PARAMETERS_ INVALID
Operation successfull	NO_ERRORS

UseSaveCounter method

This method enables optional save counter functionality for parameter handler.

Method shall be executed before Parameter handler’s Init method.

Inputs

Outputs

UpdateSaveCounter method

Method updates save counter value to area header and image’s end tag.

Feature needs to be enabled by UseSaveCounter.

Inputs

Outputs

Return value

Data type	Range	Description
ENUM	ParamHandlerStatus	Returns NO_ERROR when OK.

Error diagnostic

Conditions	Return value
Method is executed when save counter is not in use	SAVE_COUNTER_NOT_IN_USE
Error when copying data	MEMORY_COPY_FAIL
Operation successfull	NO_ERRORS