manual:chapter6:usb:cmd_usbrecv [newRPL User Manual]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
==== USBRECV ====
----
<callout type="primary" color="" icon="fa fa-book" title="Synopsis">
----
Receive an object through USB link
</callout>

<callout color="green" icon="fa fa-indent" title="Stack Diagram">
----
^  __Input Stack__  ^  ^  __Output Stack__  ^^
|  **Num<sub>time-out</sub>**  |  **→**  |  **O**  |  **1**  |
|  **Num<sub>time-out</sub>**  |  **→**  |  |  **0**  |
|  //Level 1//  |  //→//  |  //Level 2//  |  //Level 1//  | 

{{page>manual:chapter6:aux:legend&nofooter&noeditbtn&inline}}

|**Type**| [[manual:chapter5:basics#commands|Command]]  ||
|**Parallel list processing**| [[manual:chapter5:listproc#group-5one-argument-one-result-commands|Group 5]]  || 
|**Affected by flags**|  [[manual:appendix:flags#flag-47|-47]] | Automatic reception and execution of data sent via USB  |
</callout>

<callout color="orangered" icon="fa fa-comment" title="Description">
----
The ''USBRECV'' command receives an object transmitted by another calculator using the USB link, provided the connection has been successufully negotiated. Since by default object reception happens automatically without an explicit use of ''USBRECV'', the pre-condition for usage of ''USBRECV'' is the disabling of automatic reception by setting flag [[manual:appendix:flags#flag-47|-47]].

If the transfer succeeds ''USBRECV'' will leave the object ''1'' on the stack, otherwise it will leave only ''0''. The incoming object will **NOT** be ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''ted - see ''[[manual:chapter6:usb:cmd_usbautorcv|USBAUTORCV]]'' if this feature is not desired.

The ''USBRECV'' command accepts a time-out parameter expressed in seconds. After the time-out elapses ''USBRECV'' aborts with a failure. Also, transmission can be interrupted pressing **ON** before time-out ends.

To signal the user of an incoming object waiting to be received an **RX** indicator is displayed in the status area.
</callout>

<callout type="danger" icon="true" title="Compatibility">
----
This command is new in newRPL and does not exist in userRPL.
</callout>

<callout type="info" icon="true" title="Usage">
----
The following program
<code>
« @@ Send the variable name to the other side
  DO
    DUP 
  UNTIL
    USBSEND
  END
  DROP

 @@ Now create a program to RCL and send back the result...
  «
    RCL 
    DO
      DUP 
    UNTIL
      USBSEND
    END
    DROP 
  »

  @@ ...and send the program to be auto-executed over there
  DO
    DUP 
  UNTIL
    USBSEND
  END
  DROP

  @@ Wait a couple of seconds for the contents to arrive
  IF
    -47 FS?
  THEN
    2 USBRECV
    DROP
  END
»
</code>
executes a ''[[manual:chapter6:dirs:cmd_rcl|RCL]]'' through USB. See ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]'' for implementation of a USB ''[[manual:chapter6:dirs:cmd_sto|STO]]''.
</callout>

<callout color="darkgray" icon="fa fa-hand-o-right" title="Related Commands">
----
{{page>manual:chapter6:usb&nofooter&noeditbtn&inline}}
</callout>