Difference between revisions of "Extensions.DiagCom.GetComChannel"

From emotive
Jump to navigation Jump to search
 
(22 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
[[Category:DiagCom]]
+
{{DISPLAYTITLE:OTX '''GetComChannel'''}}[[Category:DiagCom]]
 
== Classification ==
 
== Classification ==
−
{{ClassificationActivity | GetComChannel | Represents a connection to the control unit at runtime | [[Term]] | [[DiagCom|OTX DiagCom extension]] | [[ComChanel related terms]] | [[UnknownTargetException]] <br/> [[LossOfComException]] | - }}
+
{{ClassificationActivity | GetComChannel | Represents a connection to the control unit at runtime | [[Term]] | [[Extensions.DiagCom|OTX DiagCom extension]] | [[Extensions.DiagCom#Terms|ComChannel related terms]] | [[Extensions.DiagCom.UnknownTargetException|UnknownTargetException]] <br/> [[Extensions.DiagCom.LossOfComException|LossOfComException]] | [[Extensions.DiagCom.DiagComChk100|DiagCom_Chk100]]<br/>[[Extensions.DiagCom.DiagComChk101|DiagCom_Chk101]] }}
  
−
== Pseudo-Code Syntax ==
+
== OTL Syntax ==
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
−
GetComChannel(String identifier, String ecuVariantName, Boolean performVariantSelection);
+
ComChannelTerm DiagCom.GetComChannel(StringTerm identifier, StringTerm ecuVariantName, BooleanTerm performVariantSelection);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== Description ==
 
== Description ==
−
'''GetComChannel''' is a term to create a new communication channel via the runtime system diagnosis . The communication channel represents a connection to only one control unit (Logical Link).
+
'''GetComChannel''' is a term to create a new communication channel to an [[ECU]]. The communication channel represents a connection to only one control unit (Logical Link).
  
−
To create a connection to the control unit, the following rules apply:
+
To create a connection to the [[ECU]], the following rules are applied:
 +
* The [[Extensions.DiagCom.ComChannel|ComChannel]] is created at the time this term is executed.
 +
* If the [[Extensions.DiagCom.ComChannel|ComChannel]] already exists, no additional action is carried out by the execution of this term.
 +
* The [[Extensions.DiagCom.ComChannel|ComChannel]] is created when it is first needed for actual diagnostic communication.
  
−
* The connection is created when this term is called.  
+
No matter which approach is chosen, the term '''GetComChannel''' will always return a handle to the same [[Extensions.DiagCom.ComChannel|ComChannel]] for a given [[ECU]]. It is possible to manually control the lifecycle of a [[Extensions.DiagCom.ComChannel|ComChannel]] object by closing a [[Extensions.DiagCom.ComChannel|ComChannel]] handle using the [[Extensions.DiagCom.CloseComChannel|CloseComChannel]] action. The OTX runtime environment will clean up all opened [[Extensions.DiagCom.ComChannel|ComChannel]] handlesat the end of a diagnostic session.
−
* If a link has already been created, it is used and it is carried out, no further action.  
+
{{ComChannelMemoryUsageNote}}
−
* Even without explicitly creating the connection, the connection will be established automatically when it is needed the first time.  
 
  
−
It is possible to manually control the lifecycle of a [[ComChannel]] object by closing a ComChannel handle using the [[CloseComChannel]] action. The OTX runtime environment will clean up all opened ComChannel handles at the end of a diagnostic session.
+
An [[Extensions.DiagCom.GetComChannel#ECU_variant_selection|ECU variant selection]] can be performed, see below.
  
−
An [[GetComChannel#ECU_variant_selection|ECU variant selection]] can be performed, see below.
+
{{TermReturnValue| [[Extensions.DiagCom.ComChannel|ComChannel]] | Returns a handle to the [[Extensions.DiagCom.ComChannel|ComChannel]] for a given [[ECU]]}}
−
 
 
−
{{TermReturnValue| [[ComChannel]] | Returns a handle to the ComChannel for a given ECU.  }}
 
  
 
== Properties ==
 
== Properties ==
 
{| {{TableHeader}}
 
{| {{TableHeader}}
 
{{TableRowPropertiesHeader}}
 
{{TableRowPropertiesHeader}}
−
{{TableRowPropertie1| Identifier | [[String]] | [[Term]] | - | [1] | String that the Communication Channel identified (Logical Link)}}
+
{{TableRowPropertie2| Identifier | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | - | [1] |This element represents a string identifying the communication channel which will be created.
−
{{TableRowPropertie2| EcuVariantName | [[String]] | [[Term]] | "" | [0..1] | Optionally you can select "manual" a special version here.}}
+
{{Note|In case a MVCI/ODX system is used the identifier specifies the '''SHORT-NAME''' of the '''MCDLogicalLink''' to be used for communication.}}}}
−
{{TableRowPropertie1| PerformVariantSelection | [[Boolean]] | [[Term]] | false | [0..1] | Select whether a [[Variant Identification]] is to be performed or not.}}
+
{{TableRowPropertie1| EcuVariantName | [[Core.DataTypes.SimpleDataType.String|String]] | [[Term]] | "" | [0..1] | This optional element allows an OTX sequence to explicitly specify a particular ECU variant that the ComChannel will be associated with.
 +
{{Note|In case a MVCI/ODX system is used the <ecuVariantName> element specifies the '''SHORT-NAME''' of the '''MCDDbEcuVariant''' to be associated with the logical link.}}}}
 +
{{TableRowPropertie2| PerformVariantSelection | [[Core.DataTypes.SimpleDataType.Boolean|Boolean]] | [[Term]] | false | [0..1] | This optional element can be used by the OTX author for controlling whether an implicit variant selection will be done.}}
 
|}
 
|}
  
 
==ECU variant selection==
 
==ECU variant selection==
−
An [[EcuVariantSelection|ECU variant selection]] can be performed after opening the channel and returns a handle to the selected ECU-Variant. The variant identification functionality also exists as a separate action called [[IdentifyAndSelectVariant]].
+
An '''ECU variant selection''' can be performed after opening the channel and returns a handle to the selected ECU-Variant. The variant identification functionality also exists as a separate action called [[Extensions.DiagCom.IdentifyAndSelectVariant|IdentifyAndSelectVariant]].
  
 
{| {{TableHeader}}
 
{| {{TableHeader}}
Line 45: Line 47:
 
|}
 
|}
  
−
== Examples ==
+
== OTL Examples ==
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
 
<syntaxhighlight lang="java" enclose="div" style="font-size: medium;">
−
ComChannel myComCannel = GetComChannel("LL_AirbaUDS", "", false);
+
/// Local Declarations
 +
 
 +
DiagCom.ComChannel ComChannel1;
 +
 
 +
/// Flow
 +
 
 +
ComChannel1 = DiagCom.GetComChannel("LL_GatewUDS", "EV_GatewLear_006", false);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== See also ==
 
== See also ==
−
[[GetComChannelIdentifierFromResponse]] <br/>
+
[[Extensions.DiagCom.GetComChannelIdentifierFromResponse|GetComChannelIdentifierFromResponse]] <br/>
−
[[GetComChannelEcuVariantName]] <br/>
+
[[Extensions.DiagCom.GetComChannelEcuVariantName|GetComChannelEcuVariantName]] <br/>
−
[[IsVariant]] <br/>
+
[[Extensions.DiagCom.IsVariant|IsVariant]] <br/>
−
[[ExecuteDiagService]]
+
[[Extensions.DiagCom.ExecuteDiagService|ExecuteDiagService]]

Latest revision as of 09:52, 12 September 2019

Classification

Name GetComChannel
Short Description Represents a connection to the control unit at runtime
Class Term
Extension OTX DiagCom extension
Group ComChannel related terms
Exceptions UnknownTargetException
LossOfComException
Checker Rules DiagCom_Chk100
DiagCom_Chk101
Standard Compliant Yes

OTL Syntax

ComChannelTerm DiagCom.GetComChannel(StringTerm identifier, StringTerm ecuVariantName, BooleanTerm performVariantSelection);

Description

GetComChannel is a term to create a new communication channel to an ECU. The communication channel represents a connection to only one control unit (Logical Link).

To create a connection to the ECU, the following rules are applied:

  • The ComChannel is created at the time this term is executed.
  • If the ComChannel already exists, no additional action is carried out by the execution of this term.
  • The ComChannel is created when it is first needed for actual diagnostic communication.

No matter which approach is chosen, the term GetComChannel will always return a handle to the same ComChannel for a given ECU. It is possible to manually control the lifecycle of a ComChannel object by closing a ComChannel handle using the CloseComChannel action. The OTX runtime environment will clean up all opened ComChannel handlesat the end of a diagnostic session.

Exclamation.png Important: Long-time running procedures should note that the OTX runtime will close open ComChannels (see GetComChannel) solely via the CloseComChannel activity! This has an impact on the long-time stability of the runtime environment. To avoid memory leaks, ComChannels should not be opened implicitly, like 
ExecuteDiagService(CreateDiagServiceByName(GetComChannel("LL_AirbaUDS","",false), "DiagnServi_ReadDataByIdentECUIdent"), ...);

because the resources cannot be released until the completion of runtime execution. Better use: 

ComChannel comChannel = GetComChannel("LL_AirbaUDS","",false);
DiagService diagService = CreateDiagServiceByName(comChannel, "DiagnServi_ReadDataByIdentECUIdent"));
ExecuteDiagService(diagService, ...);
...
CloseComChannel(comChannel);

For the short-dated execution of procedures, this is of minor importance!

An ECU variant selection can be performed, see below.

Return Value

The Term returns the value, see table below.

Icons Note.png In OTX, Terms are categorized according to its return data type!
Data Type Description
ComChannel Returns a handle to the ComChannel for a given ECU

Properties

Name Data Type Class Default Cardinality Description
Identifier String Term - [1] This element represents a string identifying the communication channel which will be created.
Icons Note.png In case a MVCI/ODX system is used the identifier specifies the SHORT-NAME of the MCDLogicalLink to be used for communication.
EcuVariantName String Term "" [0..1] This optional element allows an OTX sequence to explicitly specify a particular ECU variant that the ComChannel will be associated with.
Icons Note.png In case a MVCI/ODX system is used the <ecuVariantName> element specifies the SHORT-NAME of the MCDDbEcuVariant to be associated with the logical link.
PerformVariantSelection Boolean Term false [0..1] This optional element can be used by the OTX author for controlling whether an implicit variant selection will be done.

ECU variant selection

An ECU variant selection can be performed after opening the channel and returns a handle to the selected ECU-Variant. The variant identification functionality also exists as a separate action called IdentifyAndSelectVariant.

EcuVariantName PerformVariantSelection
Empty False No ECU variant selection is performed
Empty True An ECU variant selection is performed for the BaseVariant descriped in Identifier
NotEmpty True An ECU variant selection is performed. The channel is created to point at the desired ECUVariant and variant selection is performed on the link afterwards.

OTL Examples

/// Local Declarations

DiagCom.ComChannel ComChannel1;

/// Flow

ComChannel1 = DiagCom.GetComChannel("LL_GatewUDS", "EV_GatewLear_006", false);

See also

GetComChannelIdentifierFromResponse
GetComChannelEcuVariantName
IsVariant
ExecuteDiagService

Retrieved from "http://emotive.de/wiki/index.php?title=Extensions.DiagCom.GetComChannel&oldid=9649"