$Sock SendLn: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle">Send string followed by LINEND</span>
<span class="pageSubtitle">Send string followed by LINEND</span>
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
methods. There is currently no direct OO equivalent for this $function.</p>
methods. The OO equivalent for <var>$Sock_SendLn</var> is the <var>[[SendWithLineEnd (Socket function)|SendWithLineEnd]]</var> method.</p>


<var>$Sock_SendLn</var> sends an argument string and the untranslated <var>LINEND</var> string
<var>$Sock_SendLn</var> sends an argument string and the untranslated <var>LINEND</var> string

Revision as of 21:54, 23 July 2013

Send string followed by LINEND

Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_SendLn is the SendWithLineEnd method.

$Sock_SendLn sends an argument string and the untranslated LINEND string over a Janus Sockets connection.

It is also a callable function.

Syntax

[%rc =] = $Sock_SendLn(sockNum, string, [opts])

Syntax terms

%rc A numeric error code (described further below), or if the operation could not be performed as requested, a 0 value. For more details, see "$Sock_RecvPrs return values".
sockNum The socket number.
string The string to send. Model 204 limits this to a length of 255 bytes.
opts This optional argument is an option string, which can contain any of the following:
BINARY Indicates that regardless of the socket's BINARY or CHAR parameter, data is not translated when sent. The argument can be the result of a previous translation using $Sock_Tran_Out.
CHAR Indicates that regardless of the socket's BINARY or CHAR parameter, data is translated when sent. The translation is specified by the output table defined by the socket's XTAB parameter.
FIN Indicates that after the string argument and the LINEND string are sent, no more data will be sent on the socket. This transmits the FIN indication to the remote partner. See "Socket states: OPEN, RESET, FIN indicator" for a discussion of the FIN indicator.

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 functions ($Sock_Recv and $Sock_RecvPrs) always do a push before receiving.
LINEND hexstr The string whose hexadecimal representation is hexstr is used rather than the current LINEND parameter of the socket.

Usage notes

  • Whether it is set on the port definition, via $Sock_Set, or as an argument on the $Sock_SendLn function, LINEND must not be NONE when using $Sock_SendLn.
  • These are the $Sock_SendLn return codes:
    • 0, if the function completes successfully.
    • -1, if the socket is not open and ONRESET CONTINUE is in effect for the socket.

Example

The following example uses a combination of $Sock_Send and $Sock_SendLn.

%domain = 'www.sirius-software.com' %page = 'main.html' %socket = $Sock_Conn('TEST', %domain) %s = $Sock_Set(%socket, 'LINEND', '0D0A') %rc = $Sock_Send(%socket, 'GET /') %rc = $Sock_Send(%socket, %page) %rc = $Sock_SendLn(%socket, ' HTTP/1.0') %rc = $Sock_SendLn(%socket, )

In this example, $Sock_Set is used to specify a line-end string of hexadecimal '0D0A'. Then, a few lines are sent for which the protocol does not require line-end delimiters: the GET / and the name of the HTML page defined in %page. Then the HTTP specification is sent with a line-delimiter via the $Sock_SendLn function.

This example highlights the fact that the programmer needs to know the requirements of the communication protocol they are using before they know the appropriate function to use in sending strings to the socket.