See Also: File I/O Commands, Close_Output, Direct_Input, Get_Channel_Position, Set_Channel_Position, Write, Writeln, Seqeof, Appending Data to an Output File, Channel command component


To add output to a sequential file, a printer, or the Windows clipboard.


General syntax:

Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {driver} {file/device}

For sequential file input:

Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {FileName}

For Windows clipboard input:

Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] "clipboard:"


{FileName} is a string with any valid file name

{ChannelNumber} may be 0 through 9, and if omitted, will be assumed to be 0 (default for input) or the last channel number explicitly specified in code executed previously

Only {FileName} and {ChannelNumer} may be contained in variables; the term Channel must be hard-coded. The colons are required as shown after each element and each value.

File Modes:

{FileMode} may be either binary: or pc-text:. If omitted, it will be pc-text:.

{FileModeOption} may be any or all of:

    cr: AsciiValue (defaults: binary: -1, pc-text: 13)

    eol: AsciiValue (defaults: binary: 10, pc-text: 10)

    eof: AsciiValue (defaults: binary: -1, pc-text: 26)

    width: bytes (default: 2048)

AsciiValue -1 means not used (no value).

If any {FileModeOption} is omitted, its default AsciiValue or bytes will depend on the mode.


[driver:] {file/device} may be:

    file: FileName

    direct: FileName

    clipboard: (the Windows clipboard)

    direct: FileName

If driver is omitted, it will be file:.

What It Does

Append_Output sets the destination for sequential output of the program. Append_Output differs from Direct_Output in that Append_Output adds output to an existing file whereas Direct_Output starts writing the sequential file at the beginning of the file. There are three supported sequential file output options for DataFlex: a sequential file, the printer, or the clipboard.

The channel feature is used when you need more than one output destination or more than one input source at the same time in your program. If the channel is omitted, the default channel for sequential output (1) will be used.

The position at which data is written into the file can be changed with the Set_Channel_Position command, and queried with the Get_Channel_Position command. If Set_Channel_Position is used to append to some point within the file, the remaining contents are overwritten.

Append_Output to a Sequential File

This is the simplest case of sequential file output.


The following program shows how easy it is to append to a sequential file.

Procedure DoOutputData String sFileName

    Integer iCount

    // Create a text file. Appends to the end of the file if it already exists.

    Append_Output sFileName

    For iCount From 1 To 10

        Writeln "Line: " iCount " - Hello!"





This example is a slightly modified version of the above example to properly use channels. We highly recommend using channels in all sequential input and output operations to improve code reusability. However, for the purposes of what needs to be demonstrated in the examples of the Append_Output command this is not necessary and we will not repeat the channel usage in each example.

If you place code that uses channels and code that does not use channels in the same program, you may encounter unexpected and undesirable behavior. See the Seq_New_Channel function and channel for proper use of the channel command component.

Use Seq_chnl.pkg


Procedure DoOutputData String sFileName

    Integer iCount iChOut


    // obtain an available channel for output

    move (Seq_New_Channel()) to iChOut


    // no channel available 


        send Info_Box "No Channel Available for Output" "Error"




    // Create a text file. Appends to the end of the file if it already exists.

    Append_Output Channel iChOut sFileName

    For iCount From 1 To 10

        Writeln Channel iChOut "Line: " iCount " - Hello!"



    // close output channel 

    Close_Output Channel iChOut

    // release channel for reuse 

    send Seq_Release_Channel iChOut 

End_Procedure  // DoOutputData

Append_Output to a Printer

The printer allows a set of options to be defined. The following are all examples of valid Append_Output commands:

Append_Output "WinLST: Font: Arial"

Append_Output "WinLST: Font: Courier New: Points: 20"

Append_Output "WinLST: LANDSCAPE: Font: Comic Sans MS: Points: 9"


Append_Output "WinLST: LaserJet 4M Plus: LANDSCAPE: Points: 24"

Append_Output "WinLST: LPT1:"

Append_Output "WinLST: \\OurServer\HP4MPlus"

Each parameter must be separated from the next parameter by a colon, ':', character. There is no need for a trailing colon after the last parameter. A printer name can be added to the WinLST: device name. This feature allows a printer that is not the default printer to be used as the printer for a given sequential file channel.

The Portrait and Landscape options allow the paper orientation to be selected. Landscape allows the page to be printed so the top of the page is really the left side of the paper. This allows for very wide reports. Portrait is the typical default setting (the top of the page is the top of the page) that is generally used.

The Font and Points setting allow the typeface and size of the printing font to be selected respectively. Windows will do the best it can to find a compatible font for the parameters that you provide.

Printing Raw Escape Sequences

Sometimes, a developer wishes to directly send escape sequences to the printer to control output. The Windows Print Manager and default Windows output device (WinLST:) normally strip out any printer escape sequences sent to the printer.

In this case, output can be directed to a specific printer port that a printer is captured to, or directly to the printer using the UNC address of the printer.

When accessing a port or printer directly using this method, additional parameters such as points or fonts may not be used.


The following example shows how to print directly to a printer captured to the LPT1: printer port and change the page orientation using printer escape sequences. The escape sequences used in this example are from PCL5.

String sEscSeq sLandscape sPortrait


Move (Character(27)) to sEscSeq

Move (sEscSeq+"+"110") to sLandscape

Move (sEscSeq+"+"100") to sPortrait


Append_Output "WinLST: LPT1:"

WriteLn sLandscape  // set orientation to landscape mode

WriteLn "Line 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1"

WriteLn "Line 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2"

WriteLn "Line 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3"

WriteLn "Line 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4"

WriteLn "Line 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5"

WriteLn sPortrait  // reset orientation to portrait mode



In either of the following example code lines, the Append_Output line will generate an error:

status <<32>> Cannot open output device

This is because additional parameters other than the printer port or the printer UNC name are used.

Append_Output "WinLST: LPT1: LANDSCAPE: Points: 24: Font: Courier New"

Append_Output "WinLST: \\OurServer\HP4MPlus: LANDSCAPE: Points: 24: Font: Courier New"

Append_Output to the Windows Clipboard

The Append_Output command is also a shortcut to writing text lines into the Windows clipboard. The following example reads the contents of a file and writes it to the clipboard.

Direct_Input "hello.txt"

Append_Output "Clipboard:"

Showln "Contents of Clipboard"

While (Not (Seqeof))

    // Read from the text file

    Readln sBuffer

    // Write to clipboard

    Writeln sBuffer




Universal Naming Convention (UNC)

Universal naming convention (UNC) is a naming convention for accessing network devices, including disk drives and printers. For printers, the UNC naming convention is the following:


Where {ServerName} is the name of the server to which the printer is connected and {PrinterName} is the name of the printer connected to the server.


Various drivers permit output in different formats from different types of files and devices. If no driver is named, the file: driver is used. This driver is suitable for output to a sequential file. The desired file must be named in FileName, complete with path, if desired. If DataFlex buffering of file output is not desired, the direct: driver may be substituted.


append_output "direct: com2:"

In this example, channel 0 (or the last previously accessed channel) is defined to receive output without DataFlex buffering from Device com2:.

Printer Control Language (PCL)

Printer Control Language (PCL) is a language for accessing a standard set of printer features developed by Hewlett-Packard (HP). PCL5 is the 5th revision of this language. Most modern printers support HP's PCL. You can obtain documentation about PCL directly from HP. Be sure to also check the documentation that came with your printer for escape sequences that can be used with it and whether the printer supports PCL.

File Modes:

For file output, three modes are available, along with options for the Carriage Return (cr:), End of Line (eol:), and End of File (eof:) characters, and maximum argument width.

The pc-text: (default) mode provides default values for cr:, eol:, and eof:. Cr: is set to ASCII 13, eol: to 10, and eof: to 26. The binary: mode, intended for (non-text) files, sets both cr: and eof: invalid, and eol: to 10. Any mode name must be followed by a colon (:).

Cr:, eol:, eof:, and width: can be specified in separate options, but it is recommended that such options be given after any mode specifications, since the mode specifications may override the options. If the keywords cr:, eol:, eof:, or width: are included followed by the desired AsciiValue or (for width:) bytes, the parameter will be reset. The value -1 may be used to specify no character for cr:, eol:, or eof:. A colon (:) must be used after each AsciiValue or bytes.




Append_Output Channel 1 "MyFile.Txt"

// Now the current output channel is 1

Append_Output Channel 2 "MyOtherFile.Txt"

// Now the current output channel is 2

Append_Output Channel 1

// Now the current output channel is 1 again