Editing mirc/on events/on sockread

{{mirc title|On Sockread - Events}}
The '''ON SOCKREAD''' triggers when there is info waiting to be read on the specified TCP socket connection. You can read this info using the {{mIRC|/sockread}} command.

'''Note''': If this event triggers but no {{mIRC|/sockread}} is performed to attempt to read the buffer, it is assumed that no script exists that is handling this buffer, so it is cleared and the info it contained is lost.

== Synopsis ==
<pre>ON <level>:SOCKREAD:<matchtext>:<commands></pre>

== Parameters ==
<span style="display: inline-block; width: 105px;"> '''<level>'''</span>The corresponding {{mIRC|access levels}} for the event to trigger.

<span style="display: inline-block; width: 105px;">'''<matchtext>'''</span>The name of the socket you want the event to trigger on.

<span style="display: inline-block; width: 105px;">'''<commands>'''</span>The commands to be performed when the event listener's criteria is met.

== Connection State ==

It's important to check the value of {{mIRC|$sockerr}} to determine if any connection errors occurred and handle that case. Here is a list of possible values returned by $sockerr in the on SOCKREAD event:

* '''0''' - Data received correctly.
* '''3''' - Error occurred on connected socket: $sock($sockname).wsmsg will contain a more specific error message.

== Examples ==

You can find more information and examples in the {{mIRC|/sockread}} command page.

Here is a basic outline:
<source lang="mirc">
on *:sockread:example:{

  ;if an error occurred ($sockerr is not 0)
  if ($sockerr) {
    echo -s An error occurred: $sock($sockname).wsmsg
  }

  ;no error occurred ($sockerr was 0)
  else {

    ;perform commands related to reading the data

    ;declare %r as a local variable for use in /sockread
    var %r

    ;read a line into %r from the buffer (this variable is subject to mIRC's Line Length Limit - see the /sockread page for more information)
    sockread %r

    ;do things with %r, such as checking its value or extracting parts to output later

  }
}
</source>
'''Note''': A single /sockread may not be enough to read the entire buffer. You should keep reading until $sockbr (bytes read) is set to zero. This is far faster than letting mIRC re-trigger the event. If your script does not read the whole buffer, the on sockread event is re-triggered if:

* a) you were reading into a &binvar.
* b) you were reading into a %var and there is still a terminated line in the buffer waiting to be read.

You can find an example showing how to do that {{mIRC|/sockread#Example|here}}

== Compatibility ==
{{mIRC compatibility|3.5}}

== See Also ==
* {{mirc|on events/on sockopen|on sockopen}}
* {{mirc|on events/on sockwrite|on sockwrite}}
* {{mirc|on events/on socklisten|on socklisten}}
* {{mirc|on events/on sockclose|on sockclose}}
* {{mIRC|/sockopen}}
* {{mIRC|/sockwrite}}
* {{mIRC|/sockread}}
* {{mIRC|/sockclose}}
* {{mIRC|/sockaccept}}
* {{mIRC|/sockpause}}
* {{mIRC|$sockname}}
* {{mIRC|$sock}}
* {{mIRC|$sockbr}}
* {{mIRC|$sockerr}}

[[Category:mIRC on events|sockread]]