|
PLCnext API Documentation
22.9.0.33
|
•All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
|
PLCnext API Documentation
22.9.0.33
|
Services for the subscription. More...
#include <ISubscriptionService.hpp>
Public Types | |
| using | Ptr = std::shared_ptr< ISubscriptionService > |
| using | AddVariablesResultDelegate = delegate< void(IRscReadEnumerator< DataAccessError > &)> |
| using | AddVariablesVariableNamesDelegate = delegate< void(IRscWriteEnumerator< RscString< 512 > > &)> |
| using | GetRecordInfosRecordInfosDelegate = delegate< void(IRscReadEnumerator< VariableInfo > &)> |
| using | GetTimeStampedVariableInfosVariableInfoDelegate = delegate< void(IRscReadEnumerator< VariableInfo > &)> |
| using | GetVariableInfosVariableInfoDelegate = delegate< void(IRscReadEnumerator< VariableInfo > &)> |
| using | ReadRecordsRecordsDelegate = delegate< void(IRscReadEnumerator< RscVariant< 512 > > &)> |
| using | ReadTimeStampedValuesValuesDelegate = delegate< void(IRscReadEnumerator< RscVariant< 512 > > &)> |
| using | ReadValuesValuesDelegate = delegate< void(IRscReadEnumerator< RscVariant< 512 > > &)> |
 Public Types inherited from Arp::System::Rsc::Services::IRscService | |
| typedef std::shared_ptr< IRscService > | Ptr |
Public Member Functions | |
| ISubscriptionService (void)=default | |
| Constructs an ISubscriptionService instance. More... | |
| virtual uint32 | CreateSubscription (SubscriptionKind kind)=0 |
| Creates a subscription of the given Arp.Plc.Gds.Services.SubscriptionKind. More... | |
| virtual uint32 | CreateRecordingSubscription (uint16 recordCount)=0 |
| Creates a subscription of Arp.Plc.Gds.Services.SubscriptionKind.Recording. More... | |
| virtual DataAccessError | AddVariable (uint32 subscriptionId, const RscString< 512 > &variableName)=0 |
| Extends the subscription with the given id by inserting the given variable name More... | |
| virtual void | AddVariables (uint32 subscriptionId, AddVariablesVariableNamesDelegate variableNamesDelegate, AddVariablesResultDelegate resultDelegate)=0 |
| Extends the subscription with the given id by inserting a range of new variables. More... | |
| virtual DataAccessError | RemoveVariable (uint32 subscriptionId, const RscString< 512 > &variableName)=0 |
| Removes the variable with the specific variable name from the subscription. More... | |
| virtual DataAccessError | Subscribe (uint32 subscriptionId, uint64 sampleRate)=0 |
| Subscribes the subscription with the given id. More... | |
| virtual DataAccessError | Resubscribe (uint32 subscriptionId, uint64 sampleRate)=0 |
| Resubscribes the subscription with the given id. More... | |
| virtual DataAccessError | Unsubscribe (uint32 subscriptionId)=0 |
| Unsubscribes the subscription with the given id. More... | |
| virtual DataAccessError | DeleteSubscription (uint32 subscriptionId)=0 |
| Deletes the subscription. More... | |
| virtual DataAccessError | GetVariableInfos (uint32 subscriptionId, GetVariableInfosVariableInfoDelegate variableInfoDelegate)=0 |
| Get the subscribed variable information of the subscription. More... | |
| virtual DataAccessError | GetTimeStampedVariableInfos (uint32 subscriptionId, GetTimeStampedVariableInfosVariableInfoDelegate variableInfoDelegate)=0 |
| Get the subscribed variable information including information of timestamps of the subscription. More... | |
| virtual DataAccessError | GetRecordInfos (uint32 subscriptionId, GetRecordInfosRecordInfosDelegate recordInfosDelegate)=0 |
| Get the subscribed variable information as a record of the subscription. More... | |
| virtual DataAccessError | ReadValues (uint32 subscriptionId, ReadValuesValuesDelegate valuesDelegate)=0 |
| Read the data from the subscription with the given id. More... | |
| virtual DataAccessError | ReadTimeStampedValues (uint32 subscriptionId, ReadTimeStampedValuesValuesDelegate valuesDelegate)=0 |
| Read the data including timestamps from the subscription with the given id. More... | |
| virtual DataAccessError | ReadRecords (uint32 subscriptionId, uint16 count, ReadRecordsRecordsDelegate recordsDelegate)=0 |
| Read the data including timestamps from the subscription with the given id separated in task records. More... | |
| Public Member Functions inherited from Arp::System::Rsc::Services::IRscService | |
| IRscService (void)=default | |
| Constructs an IRscService instance. More... | |
| virtual | ~IRscService (void)=default |
| Destructs this instance and frees all resouces. More... | |
Static Public Member Functions | |
| static IRscServiceProxyFactory & | GetProxyFactory (void) |
| Static Public Member Functions inherited from Arp::System::Rsc::Services::IRscService | |
| static IRscServiceProxyFactory & | GetProxyFactory (void) |
| Returns a reference to service proxy factory to create a proxy instance of the service More... | |
Services for the subscription.
The subscription functionality is a more elegant way reading values from variables, in contrast to permanently reading (polling). A client can subscribe a selection of variables of interest and the subscription will copy the data values to a internal buffer. This is the recommended mechanism to “read” variable values from th PLC system. All read data are always task consistent, because the data is written by the task itself.
The data updating rate depends of the task to which the variable belongs. Because global variables haven't a task affiliation, each global variable will be updated by default from the task 'Globals'. This task has a default cycling time of 50ms which is configurable via the ESM configuration. For more information to the update rate see Arp.Plc.Gds.Services.ISubscriptionService.Subscribe.
Initially, the internal buffers are initialized with null values (Arp.Plc.Commons.DataType.Void). This is important to know, especially if values are read immediately after the subscription is created. More precisely if the data are read before the tasks have written the data.
Additionally a subscription is able to generate timestamps which will be generated at the end of the variable source task. Arp.Plc.Gds.Services.ISubscriptionService.ReadTimeStampedValues
A client can subscribe to different types of variables provided in Arp.Plc.Commons.DataType. Currently supported variable types are listed below:
| Type | Supported variables | Description |
|---|---|---|
| Arp.Plc.Commons.DataType.Primitive | YES | |
| Arp.Plc.Commons.DataType.DateTime | Yes | |
| Arp.Plc.Commons.DataType.String | (YES) | Please use Arp.Plc.Commons.DataType.StaticString or Arp.Plc.Commons.DataType.IecString. |
| Arp.Plc.Commons.DataType.Enum | YES | |
| Arp.Plc.Commons.DataType.Struct | YES | |
| Arp.Plc.Commons.DataType.FunctionBlock | YES | |
| Arp.Plc.Commons.DataType.Pointer | YES | |
| Arp.Plc.Commons.DataType.Array | YES |
To address a variable, the full variable name (uri) is necessary. Some valid examples are given below:
A Subscription can created in the PLC process, in other processes and also on remote targets.
All subscriptions will be removed after a Arp.Plc.Domain.Services.PlcStartKind.Cold, Arp.Plc.Domain.Services.PlcStartKind.Warm and Arp.Plc.Domain.Services.PlcStartKind.RestoreWarm start and after a download change. While a download change is in process the subscription service will be disabled and each function will be return the error code Arp.Plc.Gds.Services.DataAccessError.CurrentlyUnavailable.
Procedure of usage: tdb
This service is defined in library Arp.Plc.Gds.
|
default |
Constructs an ISubscriptionService instance.
|
pure virtual |
Extends the subscription with the given id by inserting the given variable name
The added variable is stored in a internal container and will be subscribed after calling Arp.Plc.Gds.Services.ISubscriptionService.Subscribe. If the subscription has already been subscribed, it is necessary to call Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe to subscribe the new added variable finally.
If the same full variable name is added multiple times, the old variable will be overridden. In case, a variable name is invalid or doesn't exists a specific error code will be returned Arp.Plc.Gds.Services.DataAccessError, on success the code Arp.Plc.Gds.Services.DataAccessError.None of the added variable will be returned. A variable which doesn't returned with Arp.Plc.Gds.Services.DataAccessError.None won't be added to the subscription and won't be subscribed.
A single array element can added with its index in brackets e.g.:
Or a rage of an array can added with tow indexes separated with a colon in brackets e.g.:
If an array variable is added without a variable specification, the entire array will be added to the subscription.
An alternative way to insert variables to the subscription is by using the function Arp.Plc.Gds.Services.ISubscriptionService.AddVariables.
| subscriptionId | The id of the subscription where the variable is add to. |
| variableName | The full name of the variable. |
|
pure virtual |
Extends the subscription with the given id by inserting a range of new variables.
Allows to add a range of variables to the subscription. The returned array of type Arp.Plc.Gds.Services.DataAccessError, is in the same order as the given array of variable names and indicates if the given variables are valid and exist. For further information see Arp.Plc.Gds.Services.ISubscriptionService.AddVariable.
| subscriptionId | The id of the subscription where the variables are added to. |
| variableNames | An array of full variable names. |
|
pure virtual |
Creates a subscription of Arp.Plc.Gds.Services.SubscriptionKind.Recording.
This method creates a subscription of the kind Arp.Plc.Gds.Services.SubscriptionKind.Recording. Compared to the method Arp.Plc.Gds.Services.ISubscriptionService.CreateSubscription, it allows to configure the capacity of the internal used ring buffer. For further information see Arp.Plc.Gds.Services.ISubscriptionService.CreateSubscription.
| recordCount | The maximum number of storable records. |
|
pure virtual |
Creates a subscription of the given Arp.Plc.Gds.Services.SubscriptionKind.
This method allows other components, also from remote targets, to create a subscription which is able to subscribe each PLC variable. On success it returns a unique SubscriptionId which is created internally. The SubscriptionId has to be exposed to the SDK user, due to the usage on remote targets. The SubscriptionId is the reference to a created subscription at the PLC target and is needed in each subscription method exclude this and Arp.Plc.Gds.Services.ISubscriptionService.CreateRecordingSubscription.
Each subscription contains at least one buffer which kind depends on the Arp.Plc.Gds.Services.SubscriptionKind. The number of buffer depends on the different tasks which contains the added variables. The buffer are initialized with a Arp.Plc.Commons.DataType specific initial value e.g.: int8 = 0 or boolean = false. Apart from Arp.Plc.Gds.Services.SubscriptionKind.DirectRead, the buffer will filled by the task. How often the task stores the data to the buffer depends on the task cycle time and the configured subscription sample interval.
The Arp.Plc.Gds.Services.SubscriptionKind decides which kind of a subscription will be created. Each kind has its own benefits and differs in consistence, performance and memory usage. The available kinds are listed below:
| kind | description |
|---|---|
| Arp.Plc.Gds.Services.SubscriptionKind.DirectRead | The subscription itself triggers the copy process and will read the data directly from the source. This could be the fastest way and with no influence to the real time, to get the current data, but the task consistency is not guaranteed. Usage example: Asynchronous data collection for non critical data. |
| Arp.Plc.Gds.Services.SubscriptionKind.HighPerformance | This subscription uses a Usage example: Standard way to collect the variable data. |
| Arp.Plc.Gds.Services.SubscriptionKind.RealTime | This subscription uses a Usage example: For variables which are running in high speed tasks and for which it is necessary to guarantee the fastest access to the current written data. Note that in most cases the Arp.Plc.Gds.Services.SubscriptionKind.HighPerformance is sufficient. |
| Arp.Plc.Gds.Services.SubscriptionKind.Recording | This subscription uses a Usage example: If all records are to be captured without gaps (loss-free) and if the consuming task is called less frequently than a task in which a variable to be recorded is instantiated, the self-defined size can be selected in such a way that all value changes in the more frequently called task between 2 calls of the consuming task can be buffered in the record Note that this kind uses a lot of memory! |
After the subscription is created successfully, variables could be added with Arp.Plc.Gds.Services.ISubscriptionService.AddVariable or Arp.Plc.Gds.Services.ISubscriptionService.AddVariables with the SubscriptionId just returned in this method.
| kind | The kind of the subscription. |
The unique subscription id on success, otherwise 0.
|
pure virtual |
Deletes the subscription.
Deletes the subscription with the given id. After that the id is no longer valid and all data, containing in the subscription will be removed.
| subscriptionId | The id of the subscription. |
|
pure virtual |
Get the subscribed variable information as a record of the subscription.
This function is not supported yet!
| subscriptionId | The id of the subscription. |
| recordInfos | An array of Arp.Plc.Gds.Services.VariableInfo. |
|
pure virtual |
Get the subscribed variable information including information of timestamps of the subscription.
This service function relates to the read function Arp.Plc.Gds.Services.ISubscriptionService.ReadTimeStampedValues. The provided information contains information of the added and currently subscribed variables and additionally information about the timestamps. Note that a subscription could contain multiple timestamps, related on the number of used tasks from which the added variables are from. The timestamp is always the first value followed by all to the task related variable information.
Example:
Each containing timestamp has the variable name timestamp and the data type Arp.Plc.Commons.DataType.Int64 which is provided in Arp.Plc.Gds.Services.VariableInfo like each other variable information.
For further information see Arp.Plc.Gds.Services.ISubscriptionService.GetVariableInfos.
| subscriptionId | The id of the subscription. |
| variableInfo | An array of Arp.Plc.Gds.Services.VariableInfo. |
|
pure virtual |
Get the subscribed variable information of the subscription.
The subscription service provides several read functions (Arp.Plc.Gds.Services.ISubscriptionService.ReadValues, Arp.Plc.Gds.Services.ISubscriptionService.ReadTimeStampedValues and Arp.Plc.Gds.Services.ISubscriptionService.ReadRecords) which will return the plain values without any information of type and order. To assign this plain values to the added variables, this function returns the currently subscribed variable information in a array of Arp.Plc.Gds.Services.VariableInfo in the same order as the read functions will do. This order and type information wont change, till Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe was called. Note that this order does not have to be the same order like the variables has been added to the subscription.
This service function relates to the read function Arp.Plc.Gds.Services.ISubscriptionService.ReadValues. The provided information contains only information of the added and currently subscribed variables. It doesn't contain information of timestamps. Timestamps could be read by the function Arp.Plc.Gds.Services.ISubscriptionService.ReadTimeStampedValues and its related information with Arp.Plc.Gds.Services.ISubscriptionService.GetTimeStampedVariableInfos.
Example:
| subscriptionId | The id of the subscription. |
| variableInfo | An array of Arp.Plc.Gds.Services.VariableInfo in a static order without timestamp information. |
|
pure virtual |
Read the data including timestamps from the subscription with the given id separated in task records.
This service function returns the plain data values from the added and subscribed variables including timestamps separated in task records. The data values are returned in a static order and doesn't contain any type information. To figure out which value belongs to the added variable, it is necessary to call the related information function Arp.Plc.Gds.Services.ISubscriptionService.GetRecordInfos. As long as the subscription doesn't resubscribed with Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe, all the information are valid and both, the read value data and information data, are in a static order.
The number of returned value records depends on the count of tasks, the number of sampled data and the number of the given count parameter.
The structure how the values are returned is strictly defined: The first array (records) contains n arrays (task records) and where n depends on the number of tasks. The array from the second dimension (task records) contains n arrays (record), where n depends on the number of collected data, one data record per task cycle. The array from the third dimension (record) contains the plain values, starting with the timestamp.
The read data may contain null values (Arp.Plc.Commons.DataType.Void) if the read call was executed before the tasks initially have written the data.
Example:
| subscriptionId | The id of the subscription. |
| count | Number of maximum records to be copied per task. If set to zero, all available records will be copied. |
| records | Array for the subscribed data records including timestamps. |
|
pure virtual |
Read the data including timestamps from the subscription with the given id.
This service function returns the plain data values from the added and subscribed variables including timestamps. The data values are returned in a static order and doesn't contain any type information. To figure out which value belongs to the added variable, it is necessary to call the related information function Arp.Plc.Gds.Services.ISubscriptionService.GetTimeStampedVariableInfos. As long as the subscription doesn't resubscribed with Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe, all the information are valid and both, the read value data and information data, are in a static order.
The read data may contain null values (Arp.Plc.Commons.DataType.Void) if the read call was executed before the tasks initially have written the data.
Example:
| subscriptionId | The id of the subscription. |
| values | Contains the plain values including the timestamps of the given and subscribed variables. |
|
pure virtual |
Read the data from the subscription with the given id.
This service function returns the plain data values from the added and subscribed variables. The data values are returned in a static order and doesn't contain any type information. To figure out which value belongs to the added variable, it is necessary to call the related information function Arp.Plc.Gds.Services.ISubscriptionService.GetVariableInfos. As long as the subscription doesn't resubscribed with Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe, all the information are valid and both, the read value data and information data, are in a static order.
Note that this values doesn't contain timestamps! If the timestamp is needed use the function Arp.Plc.Gds.Services.ISubscriptionService.ReadTimeStampedValues instead.
The read data may contain null values (Arp.Plc.Commons.DataType.Void) if the read call was executed before the tasks initially have written the data.
Example:
| subscriptionId | The id of the subscription. |
| values | Contains the plain values of the given and subscribed variables. |
|
pure virtual |
Removes the variable with the specific variable name from the subscription.
Removes the variable that compare equal to the given variable name, from the internal variable list. If the subscription has already been subscribed, it is necessary to call Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe to remove the given variable from the internal created buffer.
| subscriptionId | The id of the subscription. |
| variableName | The full name of the variable to be removed from the subscription. |
|
pure virtual |
Resubscribes the subscription with the given id.
Resubscribes the subscription, which will trigger a completely rebuild process of the whole subscription, including previously done variable modification which have been done after the first call of Arp.Plc.Gds.Services.ISubscriptionService.Subscribe. It destroys the internal buffer and subscribes the subscription again (for further information see Arp.Plc.Gds.Services.ISubscriptionService.Subscribe). Note that the subscription is not able to collect data from the variables, while the resubscribe process is in progress.
This method has only an effect if the given subscription is currently subscribed, otherwise nothing will happen.
| subscriptionId | The id of the subscription. |
| sampleRate | The desired sample rate in microseconds. |
|
pure virtual |
Subscribes the subscription with the given id.
All previously added variables including in the given subscription will be subscribed. Internally the variables are separated in the respective tasks, a buffer for each task will be created and connected to the task executed event. At this point the task will copy the selected variable data into the task buffer (excluded subscriptions from kind Arp.Plc.Gds.Services.SubscriptionKind.DirectRead). How often the task stores the data to the buffer depends on the task cycle time and the configured subscription sample rate.
Calling this method on a already subscribed subscription has no effect, even if new variables have been added or removed. To make variable modification effective, use Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe. Calling this method while the subscription is in the state Unsubscribed, because Arp.Plc.Gds.Services.ISubscriptionService.Unsubscribe has been called, will only connect the already constructed buffer to the respective tasks and will set the given sampleRate. Compare to the first and initial call of this method, this call cost more less time because the buffer are already created. This also means that variable modification which have been done after the first call of Arp.Plc.Gds.Services.ISubscriptionService.Subscribe, have also no effect. At this point it is also necessary to call Arp.Plc.Gds.Services.ISubscriptionService.Resubscribe.
A subscribed subscription can operates in different sample rates (excluded subscriptions from kind Arp.Plc.Gds.Services.SubscriptionKind.DirectRead) which depends on several factors. First, each variable belongs to a program which runs in a task and this task has a cycle rate which determines the sample rate. This means that at the end of each task cycle, all variable data, subscribed and related to this task, will be written to the corresponding buffer. Note that all global variables are assigned to the task 'Globals'. Thats the case if the given sample rate is set to zero, which means the subscription operates in 'real-time', the same sample rate the task is operating in. This is also the fastest possible rate for a subscription. Note that it's possible that one subscription could contain variables from different tasks, which has the consequence that the subscription operates in different rates! If the given sample rate desire to a specific rate, the subscription tries to operate in this rate, for each variable, no matter from which task this variable comes. Potential self defined sample rates for a subscription are the task cycle rate or a multiple of them, otherwise the given rate will rounded down. E.g.:
Special handling for global Varibales: If there isn't a given sample rate by the user (value is zero), the global variables will be recored by default from the 'Globals' task (50ms, configured in the ESM.config). But if there is a given sample rate (value is greater than zero) the global variables will be connected a task which fits the given sample rate. If no task exists with the given sample rate, the fastest available task will be picked and used for downsampling (see above). So it is possible to record data of global variables in the fastest availble interval or an multiple of them.
| subscriptionId | The id of the subscription. |
| sampleRate | The desired sample rate in microseconds. |
|
pure virtual |
Unsubscribes the subscription with the given id.
Unsubscribes the subscription from all task executed events. The subscription data are still exist and could be get by the respective read-methods. To subscribe the subscription again, call Arp.Plc.Gds.Services.ISubscriptionService.Subscribe.
This method has only an effect if the given subscription is currently subscribed, otherwise nothing will happen.
| subscriptionId | The id of the subscription. |
1.9.1