Search    
 

   
 

 
PRAGMA PROGRAM REFERENCE MANUAL
Index
All Operation

Expand All      ADDENDUM
RECEIVE FILE RVF Standard Verb Input/Output Operation
Target = EXTERNAL ECHO (XE), FILE STATUS (FST)

Allows any file, either text or binary, to be received with a protocol.
It uses the communications port that is currently selected and the port para-
meters are expected to be set correctly.
Any baud rate, no parity, 8 data bits and 1 stop bit are available. No hand-
shake protocol must be used. Beware that this verb performs a CLOSE ALL FILES
and therefore all THIS pointers will be lost.

RECEIVE FILE filename FILENAME using protocol PROTOCOLNAME

FILENAME may be any valid operating system name, including path and drive.
Wild card characters are not supported in file names.
The following protocols are supported by PROTOCOLNAME:
"XMODEM", "YMODEM" and "KERMIT".

SEE ALSO: RECEIVE / RECEIVE LAYOUT / SEND FILE

SEND FILE (SDF)
RECEIVE FILE (RVF)



The two verbs SEND FILE, SDF and RECEIVE FILE, RVF, allow to send and receive any file at the operating system level, either text or binary. There is no support for modem handling (i.e. dialing) nor terminal emulation.

These verbs use the communications port that is currently selected, and the port parameters are expected to be set correctly. If not, they must be set at the operating system level using whatever means are available. No parity, 8 data bits, and 1 stop bit are required at any baud rate. No handshake protocol is necessary, and may in fact interfere with the operation of the software if used.

Like SYSTEM CALL, these verbs perform a CLOSE ALL FILES, and therefore cause all THIS pointers to be lost.


Two parameters are used with each of these verbs; the first is the file name, and the second is the protocol.


FILENAME

The file name may be any valid operating system name, including path and drive letter. The path and drive letter are only used at the local system. Wild card characters are not supported in file names. In some cases, noted below, the filename is ignored, because the protocol gets the file name from the other connected system in the transmission.


PROTOCOL

The protocol is either "XMODEM", "YMODEM", or "KERMIT". Case is insignificant.

Xmodem and Ymodem protocols are very similar, have a number of variants, and in many cases are confused for each other. There is Xmodem checksum, Xmodem CRC, Xmodem 1K, Ymodem checksum, Ymodem CRC, Ymodem Batch, and perhaps even more than this. It is often hard to tell just what you are going to get when you choose Xmodem or Ymodem in a given software package.

The Xmodem/Ymodem code in PRAGMA attempts, as best it can, to accommodate any and all forms of these two protocols, regardless of which one you have chosen. Your protocol of choice will be the default; it will then attempt to adapt if necessary to what the other side is using. However, this is not always possible, and sometimes you may experience errors. The short answer is to try both; one will usually work better than the other if there are any strange things going on in the software you are communicating with.


When PRAGMA is sending files, using any of the protocols, only one file per command is possible. If the receiving system is using a batch protocol (Ymodem Batch or Kermit), they will see and end of batch indication after PRAGMA completes the sending of the single file. Thus, it is not possible for another system to receive files in batch mode from PRAGMA, even if you attempt to perform many SEND FILE commands in a row. Each SEND FILE command will terminate the batch on the receiving end. PRAGMA can batch receive, but cannot batch send.


When a file is being sent or received, a status window appears in the center of the screen. This window is 11 x 46, appears in the error colors, and is centered. The size and location of the window are not changeable. This window will not interfere in any way with the windows of your application.


The result status of a file transfer can be found in EXTERNAL ECHO and FILE STATUS. If the transfer completes successfully, an "OK" will result; if unsuccessful, a "TRANSMISSION ERROR" will result.


File transfers in progress may be aborted by pressing Ctrl/C twice, which will also cause an entry into the debugger (if enabled).



COMIO

COMIO is necessary when using the DOS version of PRAGMA 4 for any serial communications. In addition, when using Ymodem protocol, the buffer size of COMIO should be configured when it is loaded to be big enough to hold one complete Ymodem communication block. The recommended minimum size of the COMIO buffers in this case is thus 1100.


COMPILING

The code that performs the communications for SEND FILE and RECEIVE FILE is contained in a separate library, COMM.LIB (or Slibcomm.a or similar under UNIX). It must be present when compiling PRAGMA applications. These library files are part of the release diskettes.



TECHNICAL DISCUSSION

For those with a technical bent follows a short description of Xmodem/Ymodem.

The Xmodem in PRAGMA defaults to Xmodem CRC. This is generally preferred, as it has higher error detection than Xmodem checksum. If the other software you are communicating with has multiple forms of Xmodem, and you do not know which one to choose, your best bet is Xmodem CRC.

The Ymodem in PRAGMA defaults to Ymodem Batch. This is also what some people call "True Ymodem". There is another form of Ymodem, without batch capability, that some people also call Xmodem 1K. This is where some of the confusion enters. The Ymodem Batch allows multiple files to be transferred in one session. Ymodem without batch and/or Xmodem 1K do not. You may experience a timeout after the first file is sent if you pair Ymodem Batch with anything else; Ymodem Batch will attempt to send packets announcing more files or end of batch, but the other side, since it does not have batch mode, will have ended and thus will not reply.

The Ymodem in PRAGMA (which is Ymodem Batch) can connect with another Ymodem Batch system, and will also fall back to Xmodem in any of its forms if it sees that come in. However, it may not connect correctly with plain Ymodem. You may see the timeout noted earlier, after the first file has completed.

In general, Ymodem is preferred over Xmodem, as it has some status information that Xmodem does not (file size, file name), but it is more complicated (because of the many forms), and thus you may encounter errors when attempting to communicate with an unknown system. Each system will have to be experimented with until a good match is found.

Kermit protocol is pretty straight forward, as it has the ability built in to reconfigure itself to any level of capability. Any Kermit can adapt to any other Kermit. In Xmodem/Ymodem, this is done outside of the protocol, and is thus not always possible.

The Kermit in PRAGMA is a basic Kermit with checksum; nothing fancy.

Both Ymodem and Kermit know the file name when doing a receive; the file name given as the first parameter to RECEIVE FILE is ignored in this case. It is only needed for Xmodem. It should be given in all cases however (in case Ymodem switches to Xmodem by itself).

When receiving with Kermit or Xmodem, the receiver does not know the size of the file; only in Ymodem is the file size transmitted to the receiver before the file is sent. The status screen (explained below) will show a blank for the file size if it is not known.

In both Ymodem Batch and Kermit, batch receives are possible. PRAGMA can receive multiple files in one receive command. When using Xmodem, only one file per command is possible.

 
CustomWare® is a registered trademark of CustomWare Designs, Inc. All rights reserved.
CustomWare® is a registered servicemark of CustomWare Designs, Inc.  All rights reserved.
All images and designs on this web site are copyrighted© 2021.
v t