Updated March 2023; "ATE..." section added
The src parameter specifies the source text to be edited, and is interpreted in conjunction with the TXC.DOCFMT'SRC field of the txtctl parameter, in one of the following ways:
| • | File: To specify a file to edit, set src to the filename, and set the TXFF_FILE flag in the TXC.DOCFMT'SRC field of txtctl. In the ATE environment (i.e. when running under Unix with an ATE client), if the filename does not contain a backslash, then it is interpreted as being resident on the server and is automatically transferred to the %ATECACHEDIR% directory on the client workstation for editing. See ATE File Comments below. |
| • | String Buffer: To specify a string buffer, map src as a string variable of suitable size, load the initial text into it, and do not set the TXFF_FILE flag in TXC.DOCFMT'SRC field. |
| • | Current Control Contents: To reedit the current contents of an existing control, src is not required. Instead, set opcode to TXOP_REEDIT, TXC.CTLNO to the text control number. |
| • | Format: Independent of whether the document source is supplied as a file or in memory, the low three bits of TXC.docfmt'src should be used to specify the format. |
ATE File Transfer Comments
When editing a file in an ATE architecture, XTEXT uses the following rules to determine whether the file needs to be transferred from the server to the ATE client for editing:
| • | If running locally on Windows (not via ATE), then the source file is assumed to be (has to be) visible directly from the client (no transfer needed). Else... |
| • | If the TXFF_XFER flag bit it the TXC.DOCFMT'SRC of txtctl is set, then the source file is assumed to be on the server and gets transferred to the client for editing. Else... |
| • | If the src filespec does not contain a backslash, then it is assumed to be on the server and gets transferred to the client for editing. Else... |
| • | It is assumed to be directly accessible, either local or mapped to a shared network directory, and no transfer takes place. |
The main point of confusion occurs when ATE is connected to a Windows server, and the src is on the server but in native Windows notation, e.g. c:\somepath\somefile.txt. To force XTEXT to recognize that this is a server-based file that must be transferred to the client for editing, you either need to set the TXFF_XFER flag, or you can change the backslashes in the filespec to forward slashes. Windows accepts either, but the forward slashes will make it look like a Unix filespec to ATE and thus trigger the transfer logic.
One other detail about the file transfer that sometimes hangs people up: for Unix servers, the default transfer method is FTP. If that method is not workable, you can force the alternate method (through the ATE communication channel) by setting the TXFF_RAWBUF flag bit in the DOCFMT'SRC field. For Windows servers, it always uses the RAWBUF method.
History
2020 February, A-Shell 6.5.1676: When either XTEXT or AUI_IMAGE needs to transfer a file between the server and client via {S}FTP, they now use FTP2 rather than the older—and now deprecated—FTPDLX routine. Among other advantages of FTP2 is that it doesn't require registering a DLL on he Windows side.
