SendWithLineEnd (Socket function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (link repair)
 
(5 intermediate revisions by 3 users not shown)
Line 8: Line 8:


The <var>SendWithLineEnd</var> function, which may be invoked with a <var>Call</var> statement,
The <var>SendWithLineEnd</var> function, which may be invoked with a <var>Call</var> statement,
has an effect similar to <var>[[$Sock_Sendln]]</var>.
has an effect similar to <var>[[$Sock_SendLn]]</var>.


==Syntax==
==Syntax==
Line 15: Line 15:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%rc</th>
<tr><th>%number</th>
<td>If specified, this is a numeric variable to contain the returned indicator of success of the function. The return value is either of these:  
<td>If specified, this is a numeric variable to contain the returned indicator of success of the function. The return value is either of these:  
<table>  
<table>  
Line 23: Line 23:
<td>The socket is not open, and <code>ONRESET CONTINUE</code> is in effect for the socket. </td></tr>
<td>The socket is not open, and <code>ONRESET CONTINUE</code> is in effect for the socket. </td></tr>
</table></td></tr>
</table></td></tr>
<tr><th>socket</th>
<tr><th>socket</th>
<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr>
<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr>
<tr><th>string</th>
<tr><th>string</th>
<td>The string to send.</td></tr>
<td>The string to send.</td></tr>
<tr><th>opt</th>
 
<td>This optional argument is an option string that may contain any of the following:  
<tr><th><var>Options</var></th>
<td>This optional, [[Notation conventions for methods#Named parameters|name allowed]], argument is an option string that may contain any of the following:  
<table class="syntaxTable">  
<table class="syntaxTable">  
<tr><th><var>BINARY</var> </th>
<tr><th><var>BINARY</var> </th>
<td>Regardless of whether the <var>BINARY</var> or <var>CHAR</var> parameter is in effect for the socket's port, data '''is not translated''' when sent. The argument can be the result of a previous translation using the <var>[[TranOut (Socket function)|TranOut]]</var></td></tr>  
<td>Regardless of whether the <var>BINARY</var> or <var>CHAR</var> parameter is in effect for the socket's port, data '''is not translated''' when sent. The argument can be the result of a previous translation using the <var>[[TranOut (Socket function)|TranOut]]</var></td></tr>  
<tr><th><var>CHAR</var> </th>
<tr><th><var>CHAR</var> </th>
<td>Regardless of whether the <var>BINARY</var> or <var>CHAR</var> parameter is in effect for the socket's port, data '''is translated''' when sent. The translation is specified by the output table defined by the socket's <var>XTAB</var> paramete</td></tr>  
<td>Regardless of whether the <var>BINARY</var> or <var>CHAR</var> parameter is in effect for the socket's port, data '''is translated''' when sent. The translation is specified by the output table defined by the socket's <var>XTAB</var> paramete</td></tr>  
<tr><th><var>FIN</var> </th>
<tr><th><var>FIN</var> </th>
<td>After <var class="term">string</var> is sent, no more data will be sent on the socket. This transmits the <code>FIN</code> indication to the remote partner.
<td>After <var class="term">string</var> is sent, no more data will be sent on the socket. This transmits the <code>FIN</code> indication to the remote partner.
Line 40: Line 45:
<td>Ensures that the data being sent on the socket is immediately sent to the receiver. Normally, data to be sent is buffered and may not be sent immediately.
<td>Ensures that the data being sent on the socket is immediately sent to the receiver. Normally, data to be sent is buffered and may not be sent immediately.


Using PUSH is '''not''' necessary if:
Using <var>PUSH</var> is '''not''' necessary if:
<ul>
<ul>
<li>You are specifying FIN, since a push operation is implied by FIN.
<li>You are specifying <var>FIN</var>, since a push operation is implied by <var>FIN</var>.
<li>You are alternating sends and receives on a socket, since receive-processing methods (<var>Receive</var> and <var>ReceiveAndParse</var>) always do a push before receiving.
<li>You are alternating sends and receives on a socket, since receive-processing methods (<var>Receive</var> and <var>ReceiveAndParse</var>) always do a push before receiving.
</ul></td></tr>
</ul></td></tr>
<tr><th><var>LINEND</var> <i><b>hexstr</b></i></th>
 
<tr><th nowrap><var>LINEND</var> <i><b>hexstr</b></i></th>
<td>The line-end string to send. The string whose hexadecimal representation is <var class="term">hexstr</var> is used rather than the current <var>LINEND</var> parameter setting in effect for the socket. For example:
<td>The line-end string to send. The string whose hexadecimal representation is <var class="term">hexstr</var> is used rather than the current <var>LINEND</var> parameter setting in effect for the socket. For example:
<p class="code">%sock:SendWithLineEnd('GO', 'LINEND 07')
<p class="code">%sock:SendWithLineEnd('GO', 'LINEND 07')
Line 53: Line 59:


==Usage notes==
==Usage notes==
 
<ul>
Whether it's set on the port definition, via the <var>[[Set (Socket function)|Set]]</var> method, or as an argument
<li>Whether it's set on the port definition, via the <var>[[Set (Socket function)|Set]]</var> method, or as an argument
on the <var>SendWithLineEnd</var> function, <var>LINEND</var> must not be <code>NONE</code>
on the <var>SendWithLineEnd</var> function, <var>LINEND</var> must not be <code>NONE</code>
when using <var>SendWithLineEnd</var>.
when using <var>SendWithLineEnd</var>.
</ul>


==Example==
==Examples==
 
The following example uses a combination of <var>Send</var> and <var>SendWithLineEnd</var>.
The following example uses a combination of <var>Send</var> and <var>SendWithLineEnd</var>.
<p class="code"> ...
<p class="code">...
%domain = 'www.sirius-software.com'
%domain = 'www.sirius-software.com'
%page  = 'main.html'
%page  = 'main.html'
Line 71: Line 77:
%rc = %socket:SendWithLineEnd(' HTTP/1.0')
%rc = %socket:SendWithLineEnd(' HTTP/1.0')
%rc = %socket:SendWithLineEnd('')
%rc = %socket:SendWithLineEnd('')
...
...
</p>
</p>
In this example, the <var>Set</var> method specifies a line-end string of
In this example, the <var>Set</var> method specifies a line-end string of

Latest revision as of 21:42, 17 December 2014

Send a string plus line end character (Socket class)


This method sends a string and an untranslated line-end string over a Janus Sockets connection. The line-end string may be set on the port definition via the Set method or as an argument on the SendWithLineEnd function.

The SendWithLineEnd function, which may be invoked with a Call statement, has an effect similar to $Sock_SendLn.

Syntax

[%number =] socket:SendWithLineEnd( string, [[Options=] string])

Syntax terms

%number If specified, this is a numeric variable to contain the returned indicator of success of the function. The return value is either of these:
0 The function completed successfully.
-1 The socket is not open, and ONRESET CONTINUE is in effect for the socket.
socket A variable or an expression that is a reference to a Socket object.
string The string to send.
Options This optional, name allowed, argument is an option string that may contain any of the following:
BINARY Regardless of whether the BINARY or CHAR parameter is in effect for the socket's port, data is not translated when sent. The argument can be the result of a previous translation using the TranOut
CHAR Regardless of whether the BINARY or CHAR parameter is in effect for the socket's port, data is translated when sent. The translation is specified by the output table defined by the socket's XTAB paramete
FIN After string is sent, no more data will be sent on the socket. This transmits the FIN indication to the remote partner. Note that when FIN is sent, print capturing is automatically turned OFF for the socket.
PUSH Ensures that the data being sent on the socket is immediately sent to the receiver. Normally, data to be sent is buffered and may not be sent immediately.

Using PUSH is not necessary if:

  • You are specifying FIN, since a push operation is implied by FIN.
  • You are alternating sends and receives on a socket, since receive-processing methods (Receive and ReceiveAndParse) always do a push before receiving.
LINEND hexstr The line-end string to send. The string whose hexadecimal representation is hexstr is used rather than the current LINEND parameter setting in effect for the socket. For example:

%sock:SendWithLineEnd('GO', 'LINEND 07')

Usage notes

  • Whether it's set on the port definition, via the Set method, or as an argument on the SendWithLineEnd function, LINEND must not be NONE when using SendWithLineEnd.

Examples

The following example uses a combination of Send and SendWithLineEnd.

... %domain = 'www.sirius-software.com' %page = 'main.html' %socket is Object Socket %socket = New('TEST', %domain) %socket:Set('LINEND', '0D0A') %socket:Send('GET /') %rc = %socket:Send(%page) %rc = %socket:SendWithLineEnd(' HTTP/1.0') %rc = %socket:SendWithLineEnd() ...

In this example, the Set method specifies a line-end string of hexadecimal '0D0A'. Then, lines are sent for which the protocol does not require line-end delimiters: the "GET," and the HTML page defined in %page. Then the SendWithLineEnd function sends the HTTP specification with a line-delimiter.

This example highlights the fact that the programmer needs to know the requirements of the communication protocol before they know the appropriate method to use to send strings to the socket.