Library Recipe Management - RecipeManCommands

The methods of the function block RecipeManCommands from the library "Recipe Management" enable the recipes to be managed programmatically.

Library Recipe Management - RecipeManCommands 1:

The application automatically creates recipe files with the name <Recipe>.<Recipe definition>.txtrecipe on the controller. They serve as a clipboard for reading and writing recipe variables. The option Save recipe changes to recipe files automatically on the tab Recipe Manager > General influences access to these files.

Library Recipe Management - RecipeManCommands 2:

If the option Save recipe changes to recipe files automatically is activated, the recipes of the definition in TwinCAT and the implicit recipe files on the controller are automatically kept identical. The changing of recipes then also leads to file accesses.

Method CreateRecipe

This method creates a new recipe in the specified recipe definition. It subsequently reads the current PLC values into the new recipe and saves it as a recipe file with a standard name. The standard name is <Recipe>.<Recipe definition>.<Recipe extension>.

Library Recipe Management - RecipeManCommands 3:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

CreateRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_ALREADY_EXIST

ERR_RECIPE_NOMEMORY

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method CreateRecipeNoSave

This method creates a new recipe in the specified recipe definition. It subsequently reads the actual values into the new recipe.

Library Recipe Management - RecipeManCommands 4:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

CreateRecipeNoSave

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_ALREADY_EXIST

ERR_RECIPE_NOMEMORY

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method DeleteRecipe

This method deletes a recipe from the recipe definition.

Library Recipe Management - RecipeManCommands 5:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

DeleteRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method DeleteRecipeFile

This method deletes the specified recipe file of a recipe. The recipe file must be stored under the standard name <Recipe>.<Recipe definition>.<Recipe extension>.

Library Recipe Management - RecipeManCommands 6:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

DeleteRecipeFile

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_FILE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method LoadAndWriteRecipe

The method loads a recipe from the specified recipe file. The recipe file must be stored under the standard name <Recipe>.<Recipe definition>.<Recipe extension>. It subsequently writes the recipe into the PLC variables.

Library Recipe Management - RecipeManCommands 7:

Entries in the recipe file that contain no value assignment are not loaded and written. Refer to the description of the menu command Load and write Recipe.

Library Recipe Management - RecipeManCommands 8:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

LoadAndWriteRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_FILE_NOT_FOUND

ERR_RECIPE_MISMATCH

ERR_RECIPE_NOT_ALL_VARIABLES_WERE_LOADED

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method LoadFromAndWriteRecipe

This method loads the specified recipe file into a recipe. It subsequently writes the recipe into the PLC variables.

Library Recipe Management - RecipeManCommands 9:

Entries in the recipe file that contain no value assignment are not loaded and written. Refer to the description of the menu command Load and write Recipe.

Library Recipe Management - RecipeManCommands 10:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

FileName

STRING (255)

Name of the file

Return value

Name

Data type

Description

LoadFromAndWriteRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_FILE_NOT_FOUND

ERR_RECIPE_MISMATCH

ERR_RECIPE_NOT_ALL_VARIABLES_WERE_LOADED

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

See also:

Method LoadRecipe

The method loads a recipe from a recipe file. The recipe file must be stored under the standard name <Recipe>.<Recipe definition>.<Recipe extension>.

Library Recipe Management - RecipeManCommands 11:

Entries in the recipe file that contain no value assignment are not loaded and written. Refer to the description of the menu command Load and write Recipe.

Library Recipe Management - RecipeManCommands 12:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

LoadRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_FILE_NOT_FOUND

ERR_RECIPE_MISMATCH

ERR_RECIPE_NOT_ALL_VARIABLES_WERE_LOADED

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

See also:

Method ReadAndSaveAs

This method reads the current PLC values from the variables of the recipe definition and saves this data set in a recipe file without changing the existing standard recipe file <recipe.recipedefinition.extension>.

Library Recipe Management - RecipeManCommands 13:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition The variables specified in the recipe definition are read out.

FileName

STRING(255)

Name of the file. The currently read-out data set is saved as a recipe in the file.

Return value

Name

Data type

Description

ReadAndSaveAs

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_SAVE_ERR

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method ReadAndSaveRecipe

This method reads the current PLC values into the recipe. It subsequently saves the recipe to a recipe file with a standard name. The standard name is <Recipe>.<Recipe definition>.<Recipe extension>. The contents of any existing file are overwritten.

Library Recipe Management - RecipeManCommands 14:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

ReadAndSaveRecipe

DWORD

Return value, possible values:

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_SAVE_ERR

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method ReadAndSaveRecipeAs

This method reads the current PLC values into the recipe. It subsequently saves the recipe to a specified recipe file. The contents of any existing file are overwritten.

Library Recipe Management - RecipeManCommands 15:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

FileName

STRING

Name of the file

Return value

Name

Data type

Description

ReadAndSaveRecipeAs

DWORD

Return value, possible values:

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_SAVE_ERR

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method SaveRecipe

This method saves the recipe to a recipe file with a standard name. The standard name is <Recipe>.<Recipe definition>.<Recipe extension>. The contents of any existing file are overwritten.

Library Recipe Management - RecipeManCommands 16:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

SaveRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_RECIPE_SAVE_ERR

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method ReadRecipe

This method reads the current PLC values into the recipe.

Library Recipe Management - RecipeManCommands 17:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

ReadRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Data server error from 16#2000 to 16#20FF

Data source driver error from 16#2100 to 16#21FF

Method WriteRecipe

This method writes the recipe into the PLC variables.

Library Recipe Management - RecipeManCommands 18:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

STRING

Name of the recipe

Return value

Name

Data type

Description

WriteRecipe

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method ReloadRecipes

This method reads the list of recipes from a file system. Recipes with the standard name <Recipe>.<Recipe definition>.<Recipe extension> located in the path defined in the recipe manager are thereby considered.

Library Recipe Management - RecipeManCommands 19:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

Return value

Name

Data type

Description

ReloadRecipes

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method GetRecipeCount

This method returns the number of recipes in a recipe definition.

Library Recipe Management - RecipeManCommands 20:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

Return value

Name

Data type

Description

GetRecipeCount

INT

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method GetRecipeNames

This method returns the recipe names in a recipe definition.

Library Recipe Management - RecipeManCommands 21:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

pStrings

POINTER TO ARRAY [] OF STRING

Pointer to the array containing the recipe names.

iSize

INT

Number of elements in the STRING array

iStartIndex

INT

Start index

Example: 1

Return value

Name

Data type

Description

GetRecipeNames

DWORD

Return value, possible values:

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Example:

There are 50 recipes, for example. If you wish to generate a table that displays 10 recipe names simultaneously, you must define a STRING array:

strArr: ARRAY[0..9] OF STRING;

Corresponding to the iStartIndex you then obtain the recipe names for the specified range.

iStartIndex := 0; die Namen 0..9 werden zurückgegeben
iStartIndex := 20; die Namen 20..29 werden zurückgegeben

The following applies in this example:

iSize := 10;

Method GetRecipeValues

This method returns the values of a recipe.

Library Recipe Management - RecipeManCommands 22:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

 

Name of the recipe

pStrings

POINTER TO ARRAY [] OF STRINGS

Pointer to a string in which the recipe values are stored.

iSize

INT

Size of the string array.

iStartIndex

INT

The start index.

iStringLength

INT

The length of the string in the array.

Return value

Name

Data type

Description

GetRecipeValues

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Example:

There are 50 recipes, for example. If you wish to generate a table that displays 10 recipe values simultaneously, you must define a STRING array:

strArr: ARRAY[0..9] OF STRING;

Corresponding to the iStartIndex you then obtain the recipe values for a specified range.

iStartIndex := 0; die Werte 0..9 werden zurückgegeben
iStartIndex := 20; die Namen 20..29 werden zurückgegeben

The following applies in this example:

iStringLength := 80;
iSize := 10;

Method GetRecipeVariableNames

This method returns the names of the recipe variables of a recipe.

Library Recipe Management - RecipeManCommands 23:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

 

Name of the recipe

pStrings

POINTER TO ARRAY [] OF STRINGS

Pointer to STRING data types in which the names of the recipe variables are stored.

iSize

INT

Size of the STRING array.

iStartIndex

INT

The start index.

Return value

Name

Data type

Description

GetRecipeVariableNames

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Example:

There are 50 recipes, for example. If you wish to generate a table that displays 10 variable names of a recipe simultaneously, you must define a STRING array:

strArr: ARRAY[0..9] OF STRING;

Corresponding to the iStartIndex you then obtain the variable names of the recipe for the specified range.

iStartIndex := 0; die Namen 0..9 werden zurückgegeben
iStartIndex := 20; die Namen 20..29 werden zurückgegeben

The following applies in this example:

iSize := 10;

Method SetRecipeValues

This method sets the recipe values of a recipe.

Library Recipe Management - RecipeManCommands 24:

Inputs (VAR_INPUT)

Name

Data type

Description

RecipeDefinitionName

STRING

Name of the recipe definition

RecipeName

 

Name of the recipe

pStrings

POINTER TO ARRAY [] OF STRINGS

Pointer to STRING data types in which the recipe values are stored.

iSize

INT

Size of the STRING array.

iStartIndex

INT

The start index.

Return value

Name

Data type

Description

SetRecipeValues

DWORD

ERR_RECIPE_DEFINITION_NOT_FOUND

ERR_RECIPE_NOT_FOUND

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Example:

There are 50 recipes, for example. If you wish to generate a table that sets 10 recipe values simultaneously, you must define a STRING array:

strArr: ARRAY[0..9] OF STRING;

Corresponding to the iStartIndex you can then set the recipe values for a specified range.

iStartIndex := 0; Die Werte 0..9 werden gesetzt
iStartIndex := 20; Die Werte 20..29 werden gesetzt

The following applies in this example:

iStringLength := 80;
iSize := 10;

Method GetLastError

This method returns the last error of the preceding operation.

Library Recipe Management - RecipeManCommands 25:

Return value

Name

Data type

Description

GetLastError

DWORD

Return value, possible values:

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method ResetLastError

This method resets the last error.

Library Recipe Management - RecipeManCommands 26:

Return value

Name

Data type

Description

ResetLastError

DWORD

ERR_NO_RECIPE_MANAGER_SET

ERR_OK

Method SetStoragePath

This method is for setting the storage path for the recipe file. It overwrites the path specification in the dialog Storage of the recipe manager.

Library Recipe Management - RecipeManCommands 27:

Inputs (VAR_INPUT)

Name

Data type

Description

stPath

STRING

File path, example:

  • D:/recipefiles/

Return value

Name

Data type

Description

stPath

BOOL

TRUE (path was set)

FALSE

Possible errors:

ERR_OK

ERR_NO_RECIPE_MANAGER_SET

Return values

The return values of the functions described above are contained in the GVL ReturnValues.

These are InOut constants of the data type UDINT.

Name

Initialization value

Comment

ERR_OK

16#0

The operation was carried out successfully.

ERR_FAILED

16#1

The operation failed.

ERR_PARAMETER

16#2

Incorrect parameter

ERR_NOTINITIALIZED

16#3

The data server object is not initialized. The data server is required if the recipe management is used in combination with TwinCAT HMI.

ERR_NOTIMPLEMENTED

16#C

The data server does not implement the interface IDataServer4 that is required if the recipe management is used in combination with TwinCAT HMI.

ERR_NO_OBJECT

16#10

Not all variables of a recipe definition can be written via the data server. Only the valid variables are written.

ERR_NOMEMORY

16#11

The data server does not have sufficient memory.

ERR_RECIPE_FILE_NOT_FOUND

16#4000

The recipe file was not found.

ERR_RECIPE_MISMATCH

16#4001

The contents of the recipe file do not match the current recipe. This error is only output if the storage type is textual (see editor Recipe Manager, tab Storage, Storage Type) and if a variable name in the file does not correspond to the variable name in the recipe definition. The recipe file is not loaded if this error occurs.

Possible causes:

A variable was removed from the recipe definition in the project.

ERR_RECIPE_SAVE_ERR

16#4002

The storage procedure failed.

Possible causes

  • The file could not be created or opened because the hard disk is full.
  • The configured file path does not exist (see editor Recipe Manager, tab Storage, File Path).
  • The configured file extension is not permitted by the runtime system (see editor Recipe Manager, tab Storage, File Extension).

ERR_RECIPE_NOT_FOUND

16#4003

The recipe does not exist.

ERR_RECIPE_DEFINITION_NOT_FOUND

16#4004

The recipe definition does not exist.

ERR_RECIPE_ALREADY_EXIST

16#4005

The recipe already exists in the recipe definition. Create a new recipe under a different name.

ERR_NO_RECIPE_MANAGER_SET

16#4006

The global recipe manager has not been created.

Possible cause:

  • The option Recipe management in the PLC is not set in the editor of the recipe manager, tab General of the current PLC project.

ERR_RECIPE_NOT_ALL_VARIABLES_WERE_LOADED

16#4007

The recipe definition contains more variables than the recipe file. In this case the variable values of the recipe file will be written in any case. This is only for information, not actually an error.

ERR_RECIPE_NOMEMORY

16#4008

The recipe definition has no free memory to create a new recipe.

Possible causes

  • The option Save recipe changes to recipe files automatically is not set in the editor of the recipe manager, tab General of the current PLC project.
  • In this case only 50 recipes are possible per recipe definition. The error cannot occur if the option Save recipe changes to recipe files automatically is set. If the hard disk is full the error ERR_RECIPE_SAVE_ERR will be output.

ERR_RECIPE_MANAGER_LOCKED_DURING_ONLINE_CHANGE

16#4009

The recipe manager was blocked during the online change.

Possible causes:

Some of the RecipeMan commands that should have been executed during an online change were not executed.

ERR_SOURCE_EXHAUSTED

16#40A0

Used for UTF8 Helper

ERR_TARGET_EXHAUSTED

16#40A1

Used for UTF8 Helper

ERR_SOURCE_ILLEGAL

16#40A2

Used for UTF8 Helper