This method is used to add a recipe to the recipe management of the vision system. It concerns itself only with the metadata of the recipe, the actual content is transferred by a RecipeTransferType object.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

AddRecipe ([in]RecipeIdExternalDataTypeexternalId[in]ProductIdDataTypeproductId[out]RecipeIdInternalDataTypeinternalId[out]NodeIdrecipe[out]NodeIdproduct[out]BooleantransferRequired[out]Int32error);

Table 31 – AddRecipe Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment. This argument must not be empty.
productId	Identification of a product the recipe is to be used for. This argument may be empty.
internalId	Internal identification of the recipe. This identification shall be system-wide unique and must be returned.
recipe	If the server chooses to represent the recipe in the Address Space, it shall return the NodeId of the newly created entry in the Recipes folder here. If the server uses only method-based recipe management, this shall be null. Note that, even if the server uses the Recipes folder to expose recipe data in the Address Space, this may be empty, if the newly created recipe does not fit the selection criteria of the server for the entries in this folder.
product	If the server chooses to represent product information in the Address Space, it shall return the NodeId of a newly created entry in the Products folder here. If the server uses only method-based recipe management, this shall be null. Note that, even if the server uses the Products folder to expose product data in the Address Space, this may be null if the newly created product does not fit the selection criteria of the server for the entries in the Products folder.
transferRequired	In this argument, the server returns whether the vision system assumes that a transfer of the file content of the recipe is required. Note that this is only a hint for the client. If the server returns TRUE, the client will have to assume that the vision system needs the recipe content and shall transfer it. If the server returns FALSE, the client may transfer the recipe content anyway.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 32 – AddRecipe Method AddressSpace Definition

Attribute	Value
BrowseName	AddRecipe
References	Node Class	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If AddRecipe is called with an ExternalId not yet existing in the recipe management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is system-wide unique. The server may then return this InternalId, however the client cannot rely on this.

If the server chooses to represent all or selected recipes in the Address Space and if the new recipe matches the current selection critieria, the server shall create a new entry in the Recipes folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the recipe management of the vision system, it is expected that the recipe content does not yet exist either in the local recipe storage of the vision system, and therefore needs to be transferred.

If the ProductId argument is non-empty, it is expected that the vision system creates an appropriate management structure linking the newly created recipe for use with this ProductId. If the ProductId does not yet exist on the vision system, it is expected that it is created.

If the ProductId argument is empty, no such linking takes place. Note that it will not be possible to start a job based on a ProductId not linked to a recipe.

If the server chooses to represent all or selected products in the Address Space and if the ProductId matches the selection criteria, the server shall create a new entry in the Products folder in the Address Space.

If the server chooses to represent all or selected recipes in the Address Space and if the given recipe matches the selection criteria, the ProductId shall be added to the list of products within the appropriate Recipe node.

If AddRecipe is called with an ExternalId already existing in the recipe management of the vision system, it is expected that the vision system checks whether an identical version of the recipe already exists, provided that the content of the ExternalId allows for such a check (most likely using the hash value).

Note that the method has no way of checking this with the actual recipe content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the system comes to the conclusion that the recipe already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the recipe content anyway.

If the server represents recipes in the Address Space, no new entry shall be created in the recipes folder.

The behavior with regard to the ProductId argument is as described above for a new ExternalId. This way of calling AddRecipe can be used to link an existing recipe with another product.

If AddRecipe comes to the conclusion that the content of the recipe to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the recipe metadata and recipe content is entirely application-defined. The vision system may decide to create a new management structure with a new InternalId and add the recipe content to the local recipe store, or it may decide to re-use the existing ExternalId and overwrite the recipe content.

If the server chooses to represent recipes in the Address Space, the behavior with respect to these recipe objects should mirror the behavior of the vision system in its internal recipe management

The behavior with regard to the ProductId argument is as described above for a new ExternalId. If the vision system stores both recipe versions, it is implementation-defined whether both are linked to the ProductId or not.

Note that overwriting a recipe shall result in a change to the internalId of the recipe. The change may effect only the hash value, the identifier may remain the same. Historical storage is not required.

This is not, strictly speaking, a use-case of the method AddRecipe, but results are comparable, therefore, the use-case is described here.

If a recipe is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the recipe is added without using the AddRecipe method, then this recipe shall have a system-wide unique InternalId, just like a recipe added through the method.

If an existing recipe which was uploaded to the vision system through AddRecipe is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two recipes cannot be confused. Of course the vision system may record the history from which recipe it was derived.

If the server represents recipes in the Address Space and if the locally created or edited recipes match the current filter criteria, then they shall be represented as nodes in the Recipes folder, with their system-wide unique InternalIds, but without ExternalIds.

An important special case is the local editing of an already prepared recipe, described in Section B.1.2.3. Since after local editing, the already prepared recipe is different from before, effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).

This method is used to prepare a recipe so that it can be used for starting a job on the vision system.

Signature

PrepareRecipe ([in]RecipeIdExternalDataTypeexternalId[in]RecipeIdInternalDataTypeinternalIdIn[out]RecipeIdInternalDataTypeinternalIdOut[out]BooleanisCompleted[out]Int32error);

Table 33 – PrepareRecipe Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment which is to be prepared.
internalIdIn	Internal identification of the recipe which is to be prepared. The client can use either the externalId or the internalIdIn, leaving the other empty. If both are given, the InternalIdIn takes precedence.
internalIdOut	Internal identification of the recipe selected based on the given externalId or internalId.
isCompleted	Flag to indicate that the recipe has been completely prepared before the method returned. If False, the client needs either to check the properties of the recipe to determine when preparation has completed or wait for the RecipePrepared event.
Error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 34 – PrepareRecipe Method AddressSpace Definition

Attribute	Value
BrowseName	PrepareRecipe
References	Node Class	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If the vision system is in state Initialized, it is expected to change into state Ready after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId.

If the vision system is already in state Ready when PrepareRecipe is called, it is expected to be in state Ready again after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId. Depending on the capabilities of the vision system, it may temporarily leave state Ready for state Initialized, then return to Ready, or, if the system is capable of preparing recipes in the background, it may stay in state Ready and react instantaneously to Start jobs for other, already prepared, recipes. Also depending on the capabilities of the vision system, preparing an additional recipe may unprepare others if the number of recipes being prepared at the same time is limited.

The preparation of a recipe may be a time-consuming operation. The client cannot necessarily assume that the recipe is completely prepared when the method returns. The client should therefore check the preparedness of the recipe after a reasonable amount of time or wait for a RecipePrepared event with the correct ExternalId to be fired. During the time required for preparing a recipe, the system may or may not be capable of reacting to a start method. However, the server is free to handle PrepareRecipe as a synchronous method, returning only after the recipe is completely prepared unless an error has occurred.

Not that the local editing of an already prepared recipe, as described in Sections 7.5.2.1.5 and B.1.2.3 is considered to be the same as the preparation of a new recipe, because after local editing, the already prepared recipe is different from before, so effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).

Some recipes may exclude each other from being in prepared state at the same time, for example, when there are mechanical movements involved. Having two such recipes prepared at the same time would mean that an instantaneous reaction to calling the Start method for a prepared recipe would not be possible. However, this is at the discretion of the vision system. The client may merely notice an unusually long reaction time between calling the Start method and the actual state change, or the vision system may prevent the simultaneous preparation by returning an error.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. The vision system will prepare only a single one of these recipes, which may be the latest one or the latest externally defined one.

This method is used to revert the preparation of a recipe so that it can no longer be used for starting a job on the vision system.

Signature

UnprepareRecipe ([in]RecipeIdExternalDataTypeexternalId[in]RecipeIdInternalDataTypeinternalIdIn[out]RecipeIdInternalDataTypeinternalIdOut[out]Int32error);

Table 35 – UnprepareRecipe Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment which is to be un-prepared.
internalIdIn	Internal identification of the recipe which is to be un-prepared. The client can use either the externalId or the internalIdIn, leaving the other empty. If both are given, the InternalIdIn takes precedence.
internalIdOut	Internal identification of the recipe selected based on a given externalId or internalId. This is for verification by the client.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 36 – UnprepareRecipe Method AddressSpace Definition

Attribute	Value
BrowseName	UnprepareRecipe
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If the vision system is in Ready state when UnprepareRecipe is called, and the recipe to be unprepared is the only recipe currently prepared, the vision system is expected to change into state Initialized after successful reversion of the preparation of the recipe.

If there are additional recipes in prepared state, the vision system is expected to remain in state Ready and be able to be called by a Start method with one of the remaining prepared recipes. Depending on the capabilities of the vision system, it may temporarily leave state Ready for state Initialized, then return to Ready.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. However, it is expected that the vision system will handle the ambiguity in the same way as for method PrepareRecipe so that UnprepareRecipe is exactly reciprocal to PrepareRecipe.

This method is used to get a list of recipes matching certain filter criteria. It concerns itself only with the metadata of the recipe, the actual content is transferred by a RecipeTransferType object.

Signature

GetRecipeListFiltered ([in]RecipeIdExternalDataTypeexternalId[in]ProductIdDataTypeproductId[in]TriStateBooleanDataTypeisPrepared[in]UInt32maxResults[in]UInt32startIndex[in]Int32timeout[out]BooleanisComplete[out]UInt32resultCount[out]HandlerecipeHandle[out]RecipeIdInternalDataType[]recipeList[out]Int32error);

Table 37 – GetRecipeListFiltered Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment used as a filter.
productId	Identification of a product, used as a filter.
isPrepared	This argument is used to filter for prepared recipes (for value TRUE_1), non-prepared recipes (for value FALSE_0) or without regard for the preparedness of recipes (for value DONTCARE_2).
maxResults	Maximum number of recipes to return in one call; by passing 0, the client indicates that it does not put a limit on the number of recipes.
startIndex	Shall be 0 on the first call, multiples of maxResults on subsequent calls to retrieve portions of the entire list, if necessary.
Timeout	With this argument the client can give a hint to the server how long it will need access to the configuration data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the client will not need anything besides the data returned by the method call. A value < 0 indicates that the client cannot give an estimate. The client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the server to optimize its resource management.
isComplete	Indicates whether there are more results in the entire list than retrieved according to startIndex and resultCount.
resultCount	Gives the number of valid results in recipeList.
recipeHandle	The server shall return to each client requesting recipe data a system-wide unique handle identifying the recipe set / client combination. This handle has to be used by the client to release the recipe set.
recipeList	List of InternalIDs matching the filters.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 38 – GetRecipeListFiltered Method AddressSpace Definition

Attribute	Value
BrowseName	GetRecipeListFiltered
References	Node Class	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

The input arguments are used as filters. Strings or TrimmedStrings as arguments or structure components of arguments can contain * and ? to be used as wildcards. Empty elements are considered to match everything, or in other words are not taken into account for filtering at all. The notion of emptiness is defined together with the respective DataTypes.

In RecipeList, the method returns a list of all recipes whose ExternalIds or ProductIds match the filters.

For RecipleList method there are the following cases with the respect to the number of results:

• The number of recipes to be returned according to the filter is less or equal to maxResults; the first call, with nstartIndex =0, returns isComplete =TRUE, so the client knows that no further calls are necessary. resultCount gives the number of valid elements in the recipeList array.
• The number of recipes to be returned is larger than maxResults; the first N calls (N > 0 with N ≤ (number of recipes) divisor MaxResults), with startIndex =(N-1)*maxResults, return isComplete =FALSE, so the client knows that further calls are necessary. The following call returns isComplete =TRUE, so the client knows, no further calls are necessary. resultCount gives the number of valid elements in the recipeList array (on each call, so on the first N calls, this should be maxResults).

This method is used to inform the server that the client has finished processing a given recipe set allowing the server to free resources managing this recipe set.

The server should keep the data of the recipe set available for the client until the ReleaseRecipeHandle method is called or until a timeout given by the client has expired. However, the server is free to release the data at any time, depending on its internal resource management, so the client cannot rely on the data being available. ReleaseRecipeHandle is merely a hint allowing the server to optimize its internal resource management. For timeout usage see the description in Section 7.5.2.4.

Signature

ReleaseRecipeHandle ([in]HandlerecipeHandle[out]Int32error);

Table 39 – ReleaseRecipeHandle Method Arguments

Argument	Description
recipeHandle	Handle returned by GetRecipeById or GetRecipeListFiltered methods, identifying the recipe set/client combination.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 40 – ReleaseRecipeHandle Method AddressSpace Definition

Attribute	Value
BrowseName	ReleaseRecipeHandle
References	Node Class	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

This method is used to remove a recipe from the recipe management of the vision system.

Signature

RemoveRecipe [([in]RecipeIdExternalDataTypeexternalId[out]Int32error);

Table 41 – RemoveRecipe Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 42 – RemoveRecipe Method AddressSpace Definition

Attribute	Value
BrowseName	RemoveRecipe
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

It is expected that the vision system removes the recipe matching the given ExternalId from its management structures. Whether the vision system also removes the actual recipe content is implementation-defined.

Application Note:

The removed recipe may still be referenced by stored results from the vision system. Therefore, it is strongly recommended that the InternalId of a removed recipe is not re-used by the vision system. Otherwise, traceability of results to recipes will be impaired and the vision system may no be able to fulfil certain external requirements, e.g.the FDA Part 11 requirements for pharmaceutical equipment.

However, this standard makes no requirements on the way the vision system creates and maintains its internal management data.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. For example, the vision system may remove all these recipes or only the externally defined ones or any number of other possibilities.

If the server chooses to represent recipes in the Address Space, the server shall remove the recipe node in the same way as the vision system cleans up its management structures.

This method is used to prepare a product so that it can be used for starting a job on the vision system.

Signature

PrepareProduct ([in]ProductIdDataTypeproductId[out]RecipeIdInternalDataTypeinternalId[out]Int32error);

Table 43 – PrepareProduct Method Arguments

Argument	Description
productId	Identification of a product, which can be used in a Start method.
internalId	Internal identification of the recipe which is actually being used to work on the product.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 44 – PrepareProduct Method AddressSpace Definition

Attribute	Value
BrowseName	PrepareProduct
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

In effect, the vision system will use a recipe to work on the product. Therefore, the vision system is expected to select a recipe linked to the given ProductId. If more than one recipe is linked to the product, the resolution of this ambiguity is implementation defined.

The vision system shall return the internal identification of the recipe selected. If there is more than one recipe linked to the given ProductId, it is implementation-defined how this ambiguity will be handled. It is expected that the resolution of the ambiguity will be implemented in a systematic manner throughout the vision system.

Since preparing a product is in effect the same as preparing a recipe which has been selected by the vision system on the basis of the ProductId, state handling is identical to the PrepareRecipe method.

This method is used to revert the preparation of a product so that it can no longer be used for starting a job on the vision system.

Signature

UnprepareProduct ([in]ProductIdDataTypeproductId[out]RecipeIdInternalDataTypeinternalId[out]Int32error);

Table 45 – UnprepareProduct Method Arguments

Argument	Description
productId	Identification of a product, which is to be unprepared.
internalId	Internal identification of the recipe which is actually unprepared.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 46 – UnprepareProduct Method AddressSpace Definition

Attribute	Value
BrowseName	UnprepareProduct
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

It is expected that the vision system will select a recipe based on the ProductId in the same way as in method PrepareProduct and then unprepare that recipe so that UnprepareProduct is exactly reciprocal to PrepareProduct.

Therefore, state handling is identical to UnprepareRecipe method.

This method is used to remove the link between a recipe and a product in the vision system

Signature

UnlinkProduct ([in]RecipeIdInternalDataTypeinternalId[in]ProductIdDataTypeproductId[out]Int32error);

Table 47 – UnlinkProduct Method Arguments

Argument	Description
internalId	Identification of the recipe used by the system.
productId	Identification of a product, the recipe is to be used for.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 48 – UnlinkProduct Method AddressSpace Definition

Attribute	Value
BrowseName	UnlinkProduct
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

It is expected that the vision system removes a link between recipes with the given InternalId and products with the given ProductId from its internal management structures.

UnlinkProduct uses the InternalId to ensure that it is unambiguous which recipe the link is removed from. If need be, the client can get the InternalIds for given ExternalIds using the GetRecipeListFiltered method (7.5.2.4).

Starting jobs based on this ProductId will no longer lead to this recipe being used. If there is no link left between this ProductId and any recipe, it will no longer be possible to start a job based on that ProductId.

If the server chooses to represent recipes in the Address Space, the server shall remove the given ProductId from the appropriate recipe node.

If the server chooses to represent products in the Address Space, and there are no recipes linked to a product anymore, it is expected that the server removes the corresponding product node.