help/info/signature.html

   1 <!--
   2  Copyright (c) 2000-2015 Ericsson Telecom AB
   3
   4  All rights reserved. This program and the accompanying materials
   5  are made available under the terms of the Eclipse Public License v1.0
   6  which accompanies this distribution, and is available at
   7  http://www.eclipse.org/legal/epl-v10.html
   8  -->
   9 <html>
  10 <head>
  11 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  12 <meta http-equiv="Content-Language" content="en-us">
  13 <title>signature</title>
  14 </head>
  15 <body bgcolor="#DAD3C5" vlink="#0094D2" link="#003258">
  16 <table align="left" border="0" cellspacing="0" cellpadding="0" valign=top>
  17   <tr>
  18     <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>
  19   </tr>
  20 </table>
  21 <table border="0" align="right" cellpadding="0" cellspacing="0">
  22   <tr>
  23     <td><a href="../titan_main.html" alt="contents"><img border="0" src="../images/ao.jpg" width="53" height="40"></a></td>
  24     <td><a href="../titan_index.html" alt="index"><img border="0" src="../images/up.jpg" width="53" height="40"></a></td>
  25     <td><a href="setverdict.html" alt="previous"><img border="0" src="../images/left.jpg" width="53" height="40"></a></td>
  26     <td><a href="sizeof.html" alt="next"><img border="0" src="../images/right.jpg" width="53" height="40"></a></td>
  27   </tr>
  28 </table>
  29 <p><br clear="all">
  30 </p>
  31 <hr>
  32 <h1>signature</h1>
  33 <hr align="left" width="75%">
  34 <p>Procedure signatures (or signatures for short) are needed for procedure-based communication. Signatures are syntactically similar to <a href="function.html#5.">external
  35 functions</a> (contain the remote procedure prototype) while semantically are similar to <a href="type.html">type definitions</a> (used for template definitions). There are two classes of
  36 signatures:
  37 <ol>
  38   <li><a href="#Blocking">Signature for blocking communication</a></li>
  39   <li><a href="#Non-blocking">Signature for non-blocking communication</a></li>
  40 </ol>
  41 <ul>
  42   <li>Signature definitions may have parameters. The direction of the parameters is as seen by the called party rather than the calling party.</li>
  43   <li>Signature definitions may indicate that the remote procedure returns a value after its termination.</li>
  44   <li>Signature definitions may indicate that the remote procedure may raise exception.</li>
  45 </ul>
  46 <p>Related keywords:</p>
  47 <ul>
  48   <li><a href="exception.html"><b><font face="Courier New" color="#003258" size="4">exception</font></b></a></li>
  49   <li><a href="in.html"><b><font face="Courier New" color="#003258" size="4">in</font></b></a></li>
  50   <li><a href="inout.html"><b><font face="Courier New" color="#003258" size="4">inout</font></b></a></li>
  51   <li><a href="noblock.html"><b><font face="Courier New" color="#003258" size="4">noblock</font></b></a></li>
  52   <li><a href="out.html"><b><font face="Courier New" color="#003258" size="4">out</font></b></a></li>
  53   <li><a href="return.html"><b><font face="Courier New" color="#003258" size="4">return</font></b></a></li>
  54 </ul>
  55 <hr align="left" width="50%">
  56 <p>1. <a name="Blocking">Blocking</a> communication is blocking on the calling and the called side, i.e., TTCN-3 processing is suspended until the respective response has arrived.</p>
  57 <div align="center">
  58 <center>
  59 <table border="0" width="90%" bgcolor="#FFB599" cellpadding="4">
  60   <tr>
  61     <td width="100%">
  62     <h3 align="center"><font face="Courier New" color="#003258" size="5"><b>signature </b></font> <i>identifier&nbsp;</i> <font face="Courier New" color="#003258" size="5"><b>(</b></font> [ <i>parameter_list</i>
  63     ] <font face="Courier New" color="#003258" size="5"><b>)</b></font>[ <font face="Courier New" color="#003258" size="5"><b>return</b></font> <i>return_type</i> ] [ <font face="Courier New"
  64       color="#003258" size="5"><b>exception</b></font> <i>exception_list</i> ] <font face="Courier New" color="#003258" size="5"><b>;</b></font></h3>
  65     </td>
  66   </tr>
  67 </table>
  68 </center>
  69 </div>
  70 <ul>
  71   <li>
  72   <p>The <font face="Courier New" color="#003258" size="4"><b>signature</b></font> keyword introduces the signature definition.</p>
  73   </li>
  74   <li>
  75   <p><i>identifier</i> is the&nbsp;name used to refer to the structured type. Must begin with a letter, may contain letters, numbers and underscore characters. According to the&nbsp; <a
  76     href="../docs/naming.pdf" target="_blank">Naming convention</a>, the prefix <b> S_</b> is recommended.</p>
  77   </li>
  78   <li>
  79   <p>The optional <a name="parameter_list"> <i>parameter_list</i> </a> may contain some of the following (if more than one parameter applies, they are separated by comma)</p>
  80   </li>
  81   <ul>
  82     <li>the <a href="in.html"><b><font face="Courier New" color="#003258" size="4">in</font></b></a> keyword, the type of the parameter and the name of the parameter</li>
  83     <li>the <a href="inout.html"><b><font face="Courier New" color="#003258" size="4">inout</font></b></a> keyword, the type of the parameter and the name of the parameter</li>
  84     <li>the <a href="out.html"><b><font face="Courier New" color="#003258" size="4">out</font></b></a> keyword, the type of the parameter and the name of the parameter<br>
  85     &nbsp;</li>
  86   </ul>
  87   <li>
  88   <p><a name="The">The</a> optional <font face="Courier New" color="#003258" size="4"><b>return</b></font> keyword indicates that the called procedure will return a value.</p>
  89   </li>
  90   <li><i>return_type</i> specifies the type of the value returned by the procedure.</li>
  91 </ul>
  92 <ul>
  93   <li>
  94   <p>The optional <font face="Courier New" color="#003258" size="4"><b>exception</b></font> keyword indicates that the called procedure may raise an exception.</p>
  95   </li>
  96   <li><i>exception_list</i> enumerates the (user defined or bulit-on) types of the values representing the exception. More than one types may be specified, they are separated by comma.</li>
  97 </ul>
  98 <hr align="left" width="75%" color="#0094D2">
  99 <p>2. <a name="Non-blocking"> Non-blocking</a> communication is only blocking on the called side,&nbsp; i.e., TTCN-3 processing is suspended on the called side until the response has been sent.</p>
 100 <div align="center">
 101 <center>
 102 <table border="0" width="90%" bgcolor="#FFB599" cellpadding="4">
 103   <tr>
 104     <td width="100%">
 105     <h3 align="center"><font face="Courier New" color="#003258" size="5"><b>signature </b></font> <i>identifier&nbsp;</i> <font face="Courier New" color="#003258" size="5"><b>(</b></font> [ <i>parameter_list</i>
 106     ] <font face="Courier New" color="#003258" size="5"><b>)</b></font> <font face="Courier New" color="#003258" size="5"><b>noblock</b></font> [ <font face="Courier New" color="#003258" size="5"><b>exception</b></font>
 107     <i>exception_list</i> ] <font face="Courier New" color="#003258" size="5"><b>;</b></font></h3>
 108     </td>
 109   </tr>
 110 </table>
 111 </center>
 112 </div>
 113 <ul>
 114   <li>
 115   <p>The <font face="Courier New" color="#003258" size="4"><b>signature</b></font> keyword introduces the signature definition.</p>
 116   </li>
 117   <li>
 118   <p><i>identifier</i> is the&nbsp;name used to refer to the structured type. Must begin with a letter, may contain letters, numbers and underscore characters. According to the&nbsp; <a
 119     href="../docs/naming.pdf" target="_blank">Naming convention</a>, the prefix S_ is recommended.</p>
 120   </li>
 121   <li>
 122   <p>The optional <i>parameter_list</i> may contain the following:&nbsp;</p>
 123   </li>
 124   <ul>
 125     <li>
 126     <p>the <a href="in.html"><b><font face="Courier New" color="#003258" size="4">in</font></b></a> keyword, the type of the parameter and the name of the parameter
 127     </li>
 128     </p>
 129   </ul>
 130   <li>
 131   <p>The <font face="Courier New" color="#003258" size="4"><b>noblock</b></font> keyword indicating that the procedure signature is intended for non-blocking communication.</p>
 132   </li>
 133   <li><i>return_type</i> specifies the type of the value returned by the procedure.</li>
 134 </ul>
 135 <ul>
 136   <li>
 137   <p>The optional <font face="Courier New" color="#003258" size="4"><b>exception</b></font> keyword indicates that the called procedure may raise an exception.</p>
 138   </li>
 139   <li><i>exception_list</i> enumerates the (user defined or bulit-on) types of the values representing the exception. More than one types may be specified, they are separated by comma.</li>
 140 </ul>
 141 <hr align="left" width="50%">
 142 <p>Example 1: signature for blocking communication
 143 <p><font face="Courier New">signature P_MyRemoteProcOne ();</font>
 144 <p>P_MyRemoteProcOne will be used for blocking procedure-based communication. It has neither parameters nor a return value.</p>
 145 <hr align="left" width="25%">
 146 <p>Example 2: signature for non-blocking communication
 147 <p><font face="Courier New">signature P_MyRemoteProcTwo () noblock;</font>
 148 <p>P_MyRemoteProcTwo will be used for non blocking procedure-based communication. It has neither parameters nor a return value.</p>
 149 <hr align="left" width="25%">
 150 <p>Example 3: parameters of procedure signatures
 151 <p><font face="Courier New">signature P_MyRemoteProcThree (in integer pl_Par1, out float pl_Par2, inout integer pl_Par3);</font>
 152 <p>P_MyRemoteProcThree will be used for blocking procedure-based communication. The procedure has three parameters: pl_Par1 an in parameter of type integer, pl_Par2 an out parameter of type float
 153 and pl_Par3 an inout parameter of type integer.</p>
 154 <hr align="left" width="25%">
 155 <p>Example 4: value returning remote procedures
 156 <p><font face="Courier New">signature P_MyRemoteProcFour (in integer pl_Par1) return integer;</font>
 157 <p>P_MyRemoteProcFour will be used for blocking procedure-based communication. The procedure has the in parameter pl_Par1 of type integer and returns a value of type integer after its termination.</p>
 158 <hr align="left" width="25%">
 159 <p>Example 5: specifying exceptions
 160 <p><font face="Courier New">signature P_MyRemoteProcFive (inout float pl_Par1) return integer exception (ExceptionType1, ExceptionType2);&nbsp;</font>
 161 <p>P_MyRemoteProcFive will be used for blocking procedure-based communication. It returns a float value in the inout parameter pl_Par1 and an integer value, or may raise exceptions of type
 162 ExceptionType1 or ExceptionType2</p>
 163 <hr align="left" width="25%">
 164 <p>Example 6: specifying exceptions for non-blocking communication
 165 <p><font face="Courier New">signature P_MyRemoteProcSix (in integer pl_Par1) noblock exception (integer, float);&nbsp;</font>
 166 <p>P_MyRemoteProcSix will be used for non-blocking procedure-based communication. In case of an unsuccessful termination, P_MyRemoteProcSix raises exceptions of type integer or float.</p>
 167 <hr align="left" width="25%">
 168 <hr align="left" width="25%">
 169 <p><a HREF="BNF.html#signaturedef">BNF definition</a> of <font face="Courier New"> signature</font></p>
 170 </body>
 171 </html>