help/info/call.html

   1 <!--
   2  Copyright (c) 2000-2016 Ericsson Telecom AB
   3  All rights reserved. This program and the accompanying materials
   4  are made available under the terms of the Eclipse Public License v1.0
   5  which accompanies this distribution, and is available at
   6  http://www.eclipse.org/legal/epl-v10.html
   7
   8  Contributors:
   9   Baji, Laszlo
  10   Balasko, Jeno
  11   Farkas, Laszlo
  12   Feher, Csaba
  13   Forstner, Matyas
  14   Szabados, Kristof
  15   Szabo, Janos Zoltan – initial implementation
  16 -->
  17 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20 <meta http-equiv="Content-Language" content="en-us">
  21 <title>call</title>
  22 </head>
  23 <body bgcolor="#DAD3C5" vlink="#0094D2" link="#003258">
  24 <table align="left" border="0" cellspacing="0" cellpadding="0" valign=top>
  25   <tr>
  26     <td width=105 height=40><a href="https://projects.eclipse.org/projects/tools.titan"><img src="../images/titan_transparent.gif" border=0 width=105 height=40 align="left" alt="Titan"></a></td>
  27   </tr>
  28 </table>
  29 <table border="0" align="right" cellpadding="0" cellspacing="0">
  30   <tr>
  31     <td><a href="../titan_main.html" alt="contents"><img border="0" src="../images/ao.jpg" width="53" height="40"></a></td>
  32     <td><a href="../titan_index.html" alt="index"><img border="0" src="../images/up.jpg" width="53" height="40"></a></td>
  33     <td><a href="break.html" alt="previous"><img border="0" src="../images/left.jpg" width="53" height="40"></a></td>
  34     <td><a href="case.html" alt="next"><img border="0" src="../images/right.jpg" width="53" height="40"></a></td>
  35   </tr>
  36 </table>
  37 <p><br clear="all">
  38 </p>
  39 <hr>
  40 <h1>call</h1>
  41 <hr align="left" width="75%">
  42 <p>The operation belongs to the family of procedure-based communication operations. It is used to specify that a test component calls a procedure in the system under test or in another test
  43 component. The communication may be either <a href="#Blocking">blocking</a> or <a href="#Non-blocking">non-blocking</a>.
  44 <ul>
  45   <li>The operation can be used on connected procedure-based (or mixed) ports.</li>
  46   <li>In case of multiple connections the receiver may be addressed.</li>
  47 </ul>
  48 <p>Related keywords:</p>
  49 <ul>
  50   <li><a href="address.html"><b><font face="Courier New" color="#003258" size="4">address</font></b></a></li>
  51   <li><a href="catch.html"><b><font face="Courier New" color="#003258" size="4">catch</font></b></a></li>
  52   <li><a href="create.html"><b><font face="Courier New" color="#003258" size="4">create</font></b></a></li>
  53   <li><a href="getreply.html"><b><font face="Courier New" color="#003258" size="4">getreply</font></b></a></li>
  54   <li><a href="modifies.html"><b><font face="Courier New" color="#003258" size="4">modifies</font></b></a></li>
  55   <li><a href="nowait.html"><b><font face="Courier New" color="#003258" size="4">nowait</font></b></a></li>
  56   <li><a href="param.html"><b><font face="Courier New" color="#003258" size="4">param</font></b></a></li>
  57   <li><a href="signature.html"><b><font face="Courier New" color="#003258" size="4">signature</font></b></a></li>
  58   <li><a href="system.html"><b><font face="Courier New" color="#003258" size="4">system</font></b></a></li>
  59   <li><a href="to.html"><b><font face="Courier New" color="#003258" size="4">to</font></b></a></li>
  60 </ul>
  61 <hr align="left" width="75%">
  62 <p>1. <a name="Non-blocking">Non-blocking</a> communication</p>
  63 <hr align="left" width="50%">
  64 <div align="center">
  65 <center>
  66 <table border="0" width="90%" bgcolor="#FFB599" cellpadding="4">
  67   <tr>
  68     <td width="100%">
  69     <h3 align="center"><i>port_reference</i><font face="Courier New" color="#003258" size="5"><b>.call (</b></font><i> template_instance&nbsp; </i>[ <font face="Courier New" color="#003258"
  70       size="5"><b>,nowait</b></font> ] <font face="Courier New" color="#003258" size="5"><b>) </b></font>[ <font face="Courier New" color="#003258" size="5"><b>to </b></font><i>address_reference</i> ]<font
  71       face="Courier New" color="#003258" size="5"><b>;</b></font> &nbsp;</h3>
  72     </td>
  73   </tr>
  74 </table>
  75 </center>
  76 </div>
  77 <ul>
  78   <li>
  79   <p><i> port_reference</i> points out the port where the procedure is called at.</p>
  80   </li>
  81   <li>
  82   <p>The <b><font face="Courier New" color="#003258" size="4">call</font> </b> keyword introduces the procedure call.</p>
  83   </li>
  84   <li>
  85   <p><i>template_instance</i> is one of the following:</p>
  86   <ul>
  87     <li>in-line signature template (see the <a href="#Example 1">example1</a>);</li>
  88     <li>a specific value signature template (see the <a href="#Example 2">example 2</a>);</li>
  89     <li>a modified signature template (see the <a href="#Example 3">example 3</a>);<br>
  90     &nbsp;</li>
  91   </ul>
  92   </li>
  93   <table border="0" width="100%" bgcolor="#C9C2BB" cellpadding="4">
  94     <tr>
  95       <td width="100%">
  96       <p><u>TITAN specific restriction compared to the standard:</u></p>
  97       <ul>
  98         <li>
  99         <p>&nbsp;modified template is not implemented. When encountered in the TTCN-3 program, an error message will be generated.</p>
 100         </li>
 101       </ul>
 102       </td>
 103     </tr>
 104   </table>
 105   <li>
 106   <p>The optional keyword <b><font face="Courier New" color="#003258" size="4">nowait</font></b> is used when the signature is intended for blocking communication. but the process call should be
 107   made in a non-blocking way.</p>
 108   </li>
 109   <li>
 110   <p>The optional <b><font face="Courier New" color="#003258" size="4">to</font> </b> keyword is used when a port is connected to several entities and identification of the communication partner
 111   is required.</p>
 112   </li>
 113 </ul>
 114 <ul>
 115   <li>
 116   <p><i>address_reference</i> is one of the following:</p>
 117   <ul>
 118     <li>a component reference (cf. <a href="create.html"><b><font face="Courier New" color="#003258" size="4">create</font></b></a>)&nbsp; or the keyword <a href="system.html"
 119       target="_blank"><b><font face="Courier New" color="#003258" size="4">system</font></b></a>, in case of one-to-many connections.</li>
 120     <li>an address reference (cf. <a href="address.html"><b><font face="Courier New" color="#003258" size="4">address</font></b></a>) , when there are several entities within the
 121     system under test.</li>
 122   </ul>
 123   </li>
 124 </ul>
 125 <hr align="left" width="75%">
 126 <p>2. <a name="Blocking">Blocking</a> communication</p>
 127 <hr align="left" width="50%">
 128 <div align="center">
 129 <center>
 130 <table border="0" width="90%" bgcolor="#FFB599" cellpadding="4">
 131   <tr>
 132     <td width="100%">
 133     <h3 align="center"><i>port_reference</i><font face="Courier New" color="#003258" size="5"><b>.call (</b></font><i> template_instance&nbsp; </i>[ <font face="Courier New" color="#003258"
 134       size="5"><b>,</b></font><i>call_timer&nbsp;</i> ] <font face="Courier New" color="#003258" size="5"><b>) </b></font>[ <font face="Courier New" color="#003258" size="5"><b>to </b></font><i>address_reference</i>
 135     ]<font face="Courier New" color="#003258" size="5"><b> {</b></font>[ <i>response_handling_part</i> ]&nbsp; [ <i>exception_handling_part</i>&nbsp; ]<font face="Courier New" color="#003258" size="5"><b>};</b></font>
 136     &nbsp;</h3>
 137     </td>
 138   </tr>
 139 </table>
 140 </center>
 141 </div>
 142 <ul>
 143   <li>
 144   <p><i> port_reference</i> points out the port where the procedure is called at.</p>
 145   </li>
 146   <li>
 147   <p>The <b><font face="Courier New" color="#003258" size="4">call</font> </b> keyword introduces the procedure call.</p>
 148   </li>
 149   <li>
 150   <p><i>template_instance</i> is one of the following:</p>
 151   <ul>
 152     <li>in-line signature template;</li>
 153     <li>a specific value signature template;</li>
 154     <li>a modified signature template ;<br>
 155     &nbsp;</li>
 156   </ul>
 157   </li>
 158   <table border="0" width="100%" bgcolor="#C9C2BB" cellpadding="4">
 159     <tr>
 160       <td width="100%">
 161       <p><u>TITAN specific restriction compared to the standard:</u></p>
 162       <ul>
 163         <li>
 164         <p>&nbsp;modified template is not implemented. When encountered in the TTCN-3 program, an error message will be generated.</p>
 165         </li>
 166       </ul>
 167       </td>
 168     </tr>
 169   </table>
 170   <li>
 171   <p>The optional <i>call_timer</i> (a floating point value) determines the waiting time for a response in seconds.</p>
 172   </li>
 173   <li>
 174   <p>The optional <b><font face="Courier New" color="#003258" size="4">to</font> </b> keyword is used when a port is connected to several entities and identification of the communication partner
 175   is required.</p>
 176   </li>
 177 </ul>
 178 <ul>
 179   <li>
 180   <p><i>address_reference</i> is one of the following:</p>
 181   <ul>
 182     <li>a component reference (cf. <a href="create.html"><b><font face="Courier New" color="#003258" size="4">create</font></b></a>)&nbsp; or the keyword <a href="system.html"
 183       target="_blank"><b><font face="Courier New" color="#003258" size="4">system</font></b></a>, in case of one-to-many connections.</li>
 184     <li>an address reference (cf. <a href="address.html"><b><font face="Courier New" color="#003258" size="4">address</font></b></a>) , when there are several entities within the
 185     system under test.</li>
 186   </ul>
 187   </li>
 188 </ul>
 189 <ul>
 190   <li>
 191   <p>The response and exception handling part between curly brackets is used to handle responses and exceptions. It has the same structure as an <a href="alt.html"><b><font
 192     face="Courier New">alt</font></b></a> statement. Its elements may occur several times; they are separated by semicolons (see the <a href="#Example 4:">example 4</a>).</p>
 193   <ul>
 194     <li><i>&nbsp;response_handling_part</i> begins with a pair of brackets: [] Inside the bracket there may be an optional Boolean expression. The following statements are examined only when it
 195     is true. The following <a href="getreply.html"><b><font face="Courier New" color="#003258" size="4">getreply</font></b></a> keyword&nbsp; introduces the description of response
 196     handling. ;</li>
 197     <li><i>exception_handling_part</i>&nbsp; begins with a pair of brackets: [] Inside the bracket there may be an optional Boolean expression. The following statements are examined only when it
 198     is true. The following <a href="catch.html"><b><font face="Courier New" color="#003258" size="4">catch</font></b></a> keyword&nbsp; introduces the description of exception
 199     handling. When applicable, timout conditions are also handled here.</li>
 200   </ul>
 201   </li>
 202 </ul>
 203 <hr align="left" width="50%">
 204 <p><a name="Example 1">Example 1</a>: in-line signature template
 205 <p><font face="Courier New">signature S_MyProc (out integer pl_MyPar1, inout boolean pl_MyPar2, in charset pl_MyPar3) noblock;<br>
 206 <br>
 207 MujPort_PCO.call(S_MyProc:{ -, true, &quot;marcipaan&quot;}) to system;</font>
 208 <p>The signature S_MyProc suitable for non-blocking communication is defined in the first line. It has three parameters (pl_MyPar1, pl_MyPar2 and pl_MyPar3).<br>
 209 In the second line, the procedure is called at&nbsp; the port MujPort_PCO. The port is connected to several components therefore it must be addressed, in our case to the test system interface. The
 210 first parameter has no value assigned because it is an out parameter from the point of view of the called procedure. The second parameter (pl_MyPar2) has the value true, the third one contains
 211 &quot;marcipaan&quot;.</p>
 212 <hr align="left" width="50%">
 213 <p><a name="Example 2">Example 2</a>: signature template</p>
 214 <p><font face="Courier New">template S_MyProc t_NiaTemplate (boolean pl_param) := {<br>
 215 &nbsp;&nbsp;&nbsp;field1 := 16,<br>
 216 &nbsp;&nbsp;&nbsp;field2 := pl_param,<br>
 217 &nbsp;&nbsp;&nbsp;field3 := &quot;massepain&quot;<br>
 218 }</font>
 219 <p><font face="Courier New">MujPort_PCO.call (t_NiaTemplate(true));</font></p>
 220 <p>The parameterized template (t_NiaTemplate) has three fields. When called as shown in the second line, the values true and &quot;massepain&quot; will be sent to the port MujPort_PCO. The first
 221 parameter is don't care because it is defined as an out parameter.</p>
 222 <hr align="left" width="50%">
 223 <p><a name="Example 3">Example 3</a>: modified signature template</p>
 224 <p><font face="Courier New">MujPort_PCO.call (modifies t_NiaTemplate(false) := {field3 := &quot;pate d'amande&quot;});</font></p>
 225 <p>The template defined in example 2 is modified. When sent as shown, the values false and &quot;&quot;pate d'amande&quot; will be sent to the port MujPort_PCO as second and third parameters.</p>
 226 <hr align="left" width="50%">
 227 <p><a name="Example 4:">Example 4:</a> blocking communication</p>
 228 <p><font face="Courier New">signature S_MyProcc (in integer pl_MyPar41, inout integer pl_MyPar42) return integer exception (integer, float);<br>
 229 <br>
 230 MujPort_PCO.call(S_MyProcc:{512, 1024}, 1E-1) to system {<br>
 231 &nbsp;&nbsp;&nbsp;[] MujPort_PCO.getreply(MyProcc:{?, ?}) -&gt; value v_MyResult param (v_MyPar1Var,v_MyPar2Var) { }&nbsp;<br>
 232 &nbsp;&nbsp;&nbsp;[] MujPort_PCO.catch(MyProcc, MyExceptionOne) {&nbsp;<br>
 233 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;setverdict(fail);&nbsp;<br>
 234 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;stop;&nbsp;<br>
 235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;<br>
 236 &nbsp;&nbsp;&nbsp;[] MujPort_PCO.catch(MyProcc, ExceptionTypeTwo : ?) {&nbsp;<br>
 237 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;setverdict(inconc);&nbsp;<br>
 238 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;<br>
 239 &nbsp;&nbsp;&nbsp;[v_MyCondition] MujPort_PCO.catch(MyProcc, MyExceptionThree) { }&nbsp;&nbsp;&nbsp;<br>
 240 &nbsp;&nbsp;&nbsp;[] MyPort.catch(timeout) {<br>
 241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;setverdict(fail);&nbsp;<br>
 242 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;stop;&nbsp;<br>
 243 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;&nbsp;&nbsp;<br>
 244 }</font>
 245 <p>The signature S_MyProcc suitable for blocking communication is defined in the first line. It has two parameters (pl_MyPar41 and pl_MyPar42). The procedure returns an integer value and may raise
 246 exceptions, the type of the latter is integer respective float.<br>
 247 In the second line, the procedure is called with a time supervision of 100 ms at&nbsp; the port MujPort_PCO. The port is connected to several components therefore it must be addressed, in our case to
 248 the test system interface. The first parameter has the integer value 512, the second one (pl_MyPar2) has the integer value 1024.<br>
 249 The first alternative in the response and exception handling part processes the reply: all values are matched, the returned integer value is stored in the variable v_MyResult and the two returned
 250 parameters are stored in the variables v_MyPar1Var and v_MyPar2Var respectively.<br>
 251 The second alternative catches the first exception using the template MyExceptionOne, sets the verdict to fail and stops the test case.<br>
 252 The third alternative catches the second exception using the template MyExceptionTwo and sets the verdict to inconc.<br>
 253 The fourth alternative catches the third exception using the template MyExceptionThree provided that the varibale v_MyCondition equals true and does nothing.<br>
 254 The fifth alternative is activated when timeout occurs, sets the verdict to fail and stops the test case.</p>
 255 <hr align="left" width="25%">
 256 <hr align="left" width="25%">
 257 <p><a HREF="BNF.html#callstatement">BNF definition</a> of <font face="Courier New"> call</font></p>
 258 </body>
 259 </html>