XModemReceive

int XModemReceive (int portNumber, char fileName[]);

Purpose

Receives packets of information over a COM port and writes the packets to a file.

XModemReceive uses the XModem file transfer protocol. The transmitter also must follow this protocol for this function to work properly.

The XModem protocol requires that the sender and receiver agree on the error checking protocol. The sender and receiver negotiate this agreement at the beginning of the transfer, which can cause a significant delay. XModemReceive tries (maximumNumOfRetries + 1)/2 times to negotiate a CRC error check transfer. If there is no response, it tries to negotiate a check sum transfer up to (maximumNumOfRetries — 1)/2 times. By default, the maximumNumOfRetries is 10. You can change this value by calling XModemConfig.

XModemReceive opens the file in binary mode and does not treat carriage returns and linefeeds as special characters. The function writes them to the RS-232 line untouched.

If the size of the file being sent is not an even multiple of the packet size, the file received is padded with ASCII NUL (0) bytes. For example, if the file being sent contains only the string HELLO, the file written to disk contains the letters HELLO followed by (packet size — 5) NUL bytes. If the packet size is 128, the file contains the five letters in HELLO and 123 NUL bytes.

The standard XModem protocol supports only 128 and 1,024 as packet sizes. The sender sends an SOH ASCII character (0x01) to indicate that the packet size is 128 or an STX ASCII character (0x02) to indicate that the packet size is 1,024. LabWindows/CVI attempts to support any packet size. As a receiver, when LabWindows/CVI receives an STX character from the sender, it switches to 1,024 packet size regardless of what you specify. When it receives an SOH character from the sender, it uses the packet size you specify. You can specify the packet size by calling XModemConfig.

For transfers with a large packet size and a low baud rate, National Instruments recommends a large delay period.

Example Code

/* Receive the file c:\test\data from COM1. */
/* NOTE: use \ in pathname in C instead of \. */
int n;
OpenComConfig(1, "", 9600, 1, 8, 1, 256, 256);
n = XModemReceive (1, "c:\test\data");
if (n != 0)

FmtOut ("Error %d in receiving file",rs232err);

else

FmtOut ("File successfully received.");

Parameters

Return Value

Additional Information

Library: RS-232 Library

Include file: rs232.h

LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later