FB_IPCDiag_ReadParameter

Die Parameter sind in Gruppen unterteilt. Einige dieser Gruppen entsprechen den Modulen der ‚Configuration Area‘ im MDP. Module können mehrfach instanziiert sein. Ein Parameter eines mehrfach instanziierten Moduls ist dementsprechend mehrfach vorhanden bzw. hat dementsprechend viele Werte.

Andererseits gibt es Listenparameter, deren Bezeichner dies bereits kenntlich macht. Entsprechend der Anzahl der Listeneinträge ist der Parameter hier auch mehrfach vorhanden bzw. hat mehrere Werte.

VAR_INPUT

VAR_INPUT
    bExecute       : BOOL;
    eParameterKey  : E_IPCDiag_ParameterKey;
    nModuleIdx     : USINT := 0;   (* optional module selection for parameters of configuration area; 0:all corresponding modules are read (or rather the first module is read in case of list parameters) *) 
    tTimeout       : TIME := DEFAULT_ADS_TIMEOUT; (* ADS communication timeout *)
    sNetId         : T_AmsNetId := '';            (* keep empty '' for the local device *)
END_VAR
VAR_IN_OUT CONSTANT
    fbRegister     : FB_IPCDiag_Register;
END_VAR

bExecute: Mit einer positiven Flanke am Eingang bExecute wird der Funktionsbaustein aufgerufen, sofern der Baustein nicht aktiv ist.

eParameterKey: An diesem Eingang wird der Parameter, welcher abgefragt werden soll, als Enumerationswert vom Typ E_IPCDiag_ParameterKey ausgewählt.
Handelt es sich bei dem Parameter um einen Listenparameter, wird die komplette Liste auf einmal ausgelesen und zur Verfügung gestellt.

nModuleIdx: An diesem Eingang kann optional der Modulindex angegeben werden, sofern der Parameter zu einem Modul gehört, welches mehrfach vorhanden ist.
Sollte der Parameter zu einem mehrfach vorhandenen Modul gehören und der Eingang nModuleIdx bei 0 belassen werden, so werden die Parameterwerte aller Modulinstanzen ausgelesen.
Handelt es sich bei dem Parameter jedoch um einen Listenparameter kann nur eine Modulinstanz ausgelesen werden.

tTimeout: Gibt eine maximale Zeitdauer für die Ausführung der internen ADS Kommunikation an.

sNetId: Um die Anfrage auf dem lokalen Gerät durchzuführen, bedarf es keiner Angabe dieser Eingangsvariablen. Alternativ kann ein leerer String angegeben werden. Um die Anfrage an einen anderen Computer zu richten, kann hier dessen AMS Net Id (vom Typ T_AmsNetId) angegeben werden.

fbRegister: Die Instanz von FB_IPCDiag_Register muss übergeben werden, damit der Funktionsbaustein die vorhandenen Informationen zur IPC Diagnose Konfiguration auf dem Zielsystem nutzen kann.
Diese Instanz muss zuvor aufgerufen worden sein. Andernfalls wird ein Fehler ausgegeben.

VAR_OUTPUT

VAR_OUTPUT
    bValid          : BOOL;        (* read data available (equal IF NOT bBusy AND NOT bError) *)
    bBusy           : BOOL;
    bError          : BOOL;
    hrErrorCode     : HRESULT;
    ipErrorMessage  : I_TcMessage;
    nReadParameterValues : USINT;    (* number of read parameter values *)
    nModuleCount         : USINT;    (* number of module instances (configuration area) with the demanded parameter *)
END_VAR

bValid: Dieser Ausgang ist TRUE, sofern bBusy=FALSE und bError=FALSE sind.

bBusy: Dieser Ausgang ist TRUE, solange der Funktionsbaustein aktiv ist.

bError: Wird TRUE, sobald eine Fehlersituation eintritt.

hrErrorCode: Liefert bei einem gesetzten bError-Ausgang einen Fehlercode.

ipErrorMessage: Liefert bei einem gesetzten bError-Ausgang detaillierte Informationen. Der hierzu verwendete Schnittstellenzeiger ist immer gültig (ungleich Null) und vom Typ I_TcMessage. Insbesondere ist der entsprechende Fehler im PLC-OnlineView sofort als Klartext zu sehen.

nReadParameterValues: Dieser Ausgang gibt die Anzahl der gelesenen Parameterwerte an. So werden bei Listenparametern immer alle Listeneinträge automatisch gelesen und zur Verfügung gestellt.

nModuleCount: Dieser Ausgang gibt die Anzahl der Modulinstanzen an, welche den gewählten Parameter beinhalten.
Hierzu muss der Parameter aus der MDP Configuration Area stammen. Andernfalls ist nModuleCount=0.

Methoden

Nachdem der Lesevorgang erfolgreich abgeschlossen wurde, kann der Parameter mittels einer der folgenden Methoden kopiert werden.

GetParameter() :

METHOD GetParameter : HRESULT
VAR_INPUT
    pBuffer        : PVOID;    // buffer for parameter with a given size of nParameterSize
    nBufferSize    : UDINT;    // buffer size in bytes (for one or more values)
END_VAR

Die Methode GetParameter() bietet einfachen Zugriff auf den gelesenen Parameter. Sofern der Parameter mehrfach vorhanden war, liegen alle Werte vor. Es werden dann alle Werte auf einmal kopiert. Beziehungsweise werden so viele Werte kopiert, wie der angegebene Puffer groß ist. Es kann also ein ARRAY vom entsprechenden Datentyp verwendet werden, um eine komplette Liste zu erhalten.
Mit Parametern vom Typ STRING ist dies aufgrund der unterschiedlichen Länge nicht möglich. Sollte ein Parameter vom Typ STRING mehrfach vorhanden sein oder ein Listenparameter vom Typ STRING vorliegen, so muss zum Auslesen der weiteren Werte eine andere Methode verwendet werden.

GetParameterByIdx() :

METHOD GetParameterByIdx : HRESULT
VAR_INPUT
    pBuffer          : PVOID;            // buffer for parameter with a given size of nParameterSize
    nBufferSize      : UDINT;            // buffer size in bytes (for one or more values)
    nParameterIdx    : USINT(1..255);    // selection of parameter value (1..nReadParameterValues)
END_VAR

Sofern der Parameter mehrfach vorhanden war und einzelne Werte kopiert werden sollen, wird diese Funktion benötigt. Mit dem Eingang nParameterIdx wird spezifiziert, welcher Parameterwert kopiert werden soll. Handelt es sich um einen Listenparameter, geben Sie dort den gewünschten Listenindex an. Handelt es sich nicht um einen Listenparameter, aber einen Parameter, über den mehrere Modulinstanzen verfügten, geben Sie den Modulindex an. Beide Indexe beginnen jeweils mit 1.

GetParameterStrings() :

METHOD GetParameterStrings : HRESULT
VAR_INPUT
    pBuffer     : PVOID;    // buffer for parameter with a given size of nParameterSize
    nBufferSize : UDINT;    // buffer size in bytes (for one or more values)
    nStrings    : USINT;    // number of strings to be copied (each string with size=nBufferSize/nStrings)
END_VAR

Sofern der Parameter mehrfach vorhanden war und vom Datentyp her eine Zeichenkette (STRING) darstellt, können mit Hilfe dieser Methode mehrere Zeichenketten zugleich kopiert werden. Mit dem Eingang nStrings wird spezifiziert, wie viele Zeichenketten kopiert werden sollen. Als Puffer kann ein ‚ARRAY[1..nStrings] OF STRING‘ dienen.

Voraussetzungen