The dst parameter specifies the destination (where the updated text from the editing operation will be returned), and is interpreted in conjunction with the TXC.DOCFMT'DST field of the txtctl parameter in one of the ways listed below. Note that while the destination and destination format are independent of the source, they can also be the same (i.e. the same filename or the same text buffer variable).
| • | File: To output to a file, set dst to the filename, and specify the TXFF_FILE flag in the TXC.DOCFMT'DST field of txtctl. |
| • | In the ATE environment (i.e. when running under Unix with an ATE client), if the filename does not contain a drive letter or backslash, then it is interpreted as being resident on the server. Since the editing takes place on the workstation, the output is first saved to the local %ATECACHEDIR% directory and the transferred to the server. |
| • | Internal Memory Buffer: If you set the TXF_DEFERSAVE flag, the updated text is held in an internal memory buffer owned by the control, and the dst parameter is ignored. (The idea here is that you will subsequently make another call to reedit the control using opcode TXOP_REEDIT.) |
| • | String Buffer: To output the updated text to a string variable, map dst as a string of suitable size, and do not set the TXFF_FILE flag in TXC.DOCFMT'DST field. If the amount of text in the control is too much to fit, then the TXC.OVERFLOW field in the txtctl parameter will be set to 1, and only the amount that actually will fit will be output. At that point, your application has the option of retrieving the text using one or more subsequent calls using opcode TXOP_SAVE. Initially the TXC.SAVEOFFSET field will be set to the position of the first unsaved byte (e.g. the size of dst), and subsequent save operations will start from that offset and then update the TXC.SAVEOFFSET field accordingly. If you prefer to get the entire text into a single text buffer, you can first allocate a string variable of sufficient size (probably using the DIMX statement), and then set the TXC.SAVEOFFSET field to -1 before calling XTEXT with opcode TXOP_SAVE. (If you set TXC.SAVEOFFSET to 0 rather than -1 it will not realize that there was a previously incomplete save operation and will behave unpredictably.) |
The TXC.OUTBYTES field will be set to the total size of the updated text. So to retrieve the entire text in a single step without the possibility of overflowing, you can first edit the control with the TXF_DEFERSAVE flag set, then allocate a dst variable of size matching TXC.OUTBYTES, then use opcode TXOP_SAVE to retrieve the text in one step.
Warning: the dst and src parameters must reference separate variables, else the initialization of the dst string will clear the src string before it gets displayed.
