XModemReceive

int XModemReceive (int COMPort, 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.

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

/* 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

Input
Name Type Description
COMPort integer A number that indicates the COM port on which to operate.

This number is paired with deviceName, which represents the COM port, during the OpenComConfig function call.

Default Value: 1—COM1
Valid Range: 1—1,000
fileName string The pathname of the file to be received.

Return Value

Name Type Description
result integer The result of this function call. This code is a negative value that specifies the type of error that occurred.