Trilobyte Software Systems

This technical note documents the file transfer program command-line parameters and the use of the "program-controlled" features added with version 4.04.

FILE TRANSFER COMMAND LINE PARAMETERS
Syntax:

   WT400XFR.EXE [transferfile | batchfile]  [/Ddirectoryname] 
                        [ /B | /R | /F | /T | /P[nnnn] ]

where:
transferfile
is the name (and, optionally, path) of the transfer request file to be loaded. Transfer request file names have the extension of "A2P" (for a download request), or "P2A" (for an upload request).
batchfile
is the name (and, optionally, path) of the text file that contains the fully qualified name(s) of the transfer request files to be executed if the "/B" program switch is specified. See the technical note Batch Transfer for more information.
directoryname
is the fully qualified name of the default directory to be used for locating and saving transfer request files. If not specified, the default directory is the directory from which the transfer program was loaded. Note that the directory name must immediately follow (no intervening space) the "/D" program switch.
/D program switch
specifies the use of an alternate default directory. See "directoryname", above for more information.
/B program switch
specifies that the file named on the command line is a "batch" of transfer requests. See "batchfile", above, for more information.
/R program switch
specifies that the transfer request file named on the command line is to be executed immediately.
/F program switch
directs the transfer program to initially display the "download" dialog window. This switch should not be used if a transfer request file name is specifed on the command line.
/T program switch
directs the transfer program to initially display the "upload" dialog window. This switch should not be used if a transfer request file name is specifed on the command line.
/P[nnnn] program switch
indicates that the transfer program is to execute the named transfer request file without operator intervention. nnnn is an optional 4-digit number that controls the logging of transfer results. If a valid number is specified, the results of the transfer will be recorded in the file "WTXFRPGM.LOG" in the default directory. A different log file may be specified by adding the key "PgmLogFile=" to the "[General]" section of the transfer request file. See the following topics for more information.
Note that all program switches, with the exception of the "/D" switch, are mutually exclusive. Unpredictable results may occur if more than one switch is specified.
ADDITIONAL NOTES ABOUT THE "/P" SWITCH, LOGGING AND SECURITY
The addition of the "/P" switch helps to overcome some of the security concerns voiced by many system administrators. Among these concerns are:

  1. Users can still modify transfer requests, as password protection applies only to the execution of the requests.

  2. Even if the transfer program is re-named (so that WinAPPC display emulation can't call it from a menu command) a user who knows the new name can still access the program to create/modify requests.

WinTran addresses these concerns with the "/P" switch, and other program modifications made for version 4.04:

  1. The presence of the "/P" switch on the command line will not allow the user to modify the transfer request. (The user may still cancel the request, causing the program to exit.)

  2. If the WinTran program is re-named (from "WT400XFR.EXE"), the program will not execute without the presence of the "/P" switch followed by a valid, non-zero decimal number (which initiates logging of the transfer's execution).

  3. Logging of the transfer's execution will be performed if the "/P" switch is followed by a valid, non-zero decimal number. Transfer results are logged by default to the file "WTXFRPGM.LOG" in the default directory. The log file for a particular request may be changed by adding the keyname "PgmLogFile=" to the "[General]" section of the transfer request file.

The log file is a standard ASCII text file with entries in the following formats:

          nnnn ssss cccc yy.mm.dd/hh:mm:ss fffffffffff....

                              (or)

                      iiiiiiiiiiiiiiiiiiiiiiiiii......   

where:
nnnn
is the four digit number following the "/P" switch.
ssss
is the status of the transfer request. Possible are:
"*Pgm" - the WinTran program could not be started; Additional information should follow.
"*Beg" - The transfer request has started.
"*End" - The transfer request has ended.
"*Err" - The transfer request encountered an error; Additional information may follow, depending upon the nature of the error.
cccc
is a hexadecimal error code for *Pgm and *Err entries. For *Beg and *End entries, or error entries where no error code is available, the field will contain ASCII dashes ("----" ). Normally, host-detected or translation errors will return a code, and some errors will provide additional information. Additional information will usually (hopefully) follow an error entry if the error code is not present.
yy.mm.dd/hh:mm:ss
is the system date and time when the entry is logged.
ffffffffff....
is the fully-qualified path name of the transfer request file being executed.
iiiiiiiii....
is additional information (if present) following an *Err or *Pgm entry. The text of the information begins in column 11 on the line (the text follows 10 spaces).
Note that the presence of the "/P" switch does not negate password security, but a program-controlled file transfer CAN override the password prompt to facilitate unattended operation. (See the topic, "FILE TRANSFER UNDER PROGRAM CONTROL", later in this document, for more information.)
For the truly concerned system administrator, maximum protection against unauthorized file transfer can be effected as follows:

  1. Password-protect the transfer program from unauthorized execution.

  2. Rename the transfer program so that it cannot be called from the WinAPPC display emulation menu, or called without the "/P" switch.

  3. Write-protect the transfer program and all transfer request files.

  4. Write a program (or programs) to call the renamed file transfer program, incorporating security measures satisfactory to your particular needs.

No security measures are perfect, of course, but the above steps will prevent most inadvertent or casual misuse of the file transfer program.
FILE TRANSFER UNDER PROGRAM CONTROL
With version 4.04 of WinTran it is possible to execute file transfers from a user-written program. Of course this was always possible but, prior to version 4.04, WinTran offered the calling program no clue about the success or failure of the attempted transfer -- a serious deficiency. The "/P" program switch, new in this version, overcomes this deficiency.

The presence of the "/P" switch on the command line causes WinTran to:

  1. execute the transfer request file named on the command line (without giving users an opportunity to modify the request);

  2. optionally log the results of the file transfer to a file (See the following topic, "ADDITIONAL NOTES ABOUT THE "/P" SWITCH, LOGGING AND SECURITY", for more information about logging);

  3. broadcast status messages that can be processed by the calling program.
    The third action, the broadcast message, allows user-written programs to monitor the success or failure of a file transfer.

In overview, a program written to automatically execute file transfer(s) (and monitor results) must:

  1. construct a command line containing the transfer request file name and path, if necessary, and the "/P" switch; (If logging is desired, or if the transfer program has been re-named, the "/P" switch must be followed immediately by a 4-digit, non-zero decimal number.)

  2. register the Windows message, "XfrPgmCtlMsg";

  3. execute the Wintran program (using the Windows "WinExec" function), pointing to the previously contructed command line;

  4. monitor (in a message loop) for messages from WinTran, taking action as appropriate.

Messages broadcast by WinTran are retrieved by the user program via a "GetMessage" or "PeekMessage" Windows function call.

The message structure returned by these functions will contain:
MSG.message
will contain the unsigned integer that matches the one returned by the "RegisterWindowMessage" call to register the "XfrPgmCtlMsg" message.
MSG.wParam
will contain the value of the number that immediately followed the "/P" switch if a valid number was given, or zero.
MSG.lParam
will contain two WORD values. The LOW-order word holds the reason for the message, as follows: 0 = File transfer beginning 1 = File transfer ended 2 = Error in file transfer 3 = File transfer program could not be started The HIGH-order word will contain, for reasons 2 or 3, an error code (if available). Otherwise, this word will be zero.

Some notes on processing messages from the file transfer program:

  1. Bear in mind that multiple file transfers can be executed simultaneously (one of the reasons for the wParam value).

  2. WinTran will write to the log file BEFORE posting the status message.

  3. If a "file transfer beginning" message (LOW word of lParam = 0) is received, a "file transfer ended" (LOW word of lParam = 1) will also be received, even if an intervening error (LOW word of lParam = 2) occurs. Invalid passwords and operator cancellation of the transfer are considered errors. If the transfer program can not start (LOW word of lParam = 3), no further messages will be forthcoming.

One additional feature of WinTran allows for unattended operation under program control. If transfer execution is password-protected, a program can override the entry of the password by specifying "SW_HIDE" for the "uCmdShow" parameter of the "WinExec" function call that evokes the file transfer program.

For additional information on writing programs to control file transfer, read the other topics, above, and see the sample source file in the tech note WTXSAMP2.C.