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.
Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {driver} {file/device}
Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] {FileName}
Append_Output [Channel {ChannelNumber} {FileMode}: {FileModeOption}] "clipboard:"
Where
{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.
{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:.
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.
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!"
Loop
Close_Output
End_Procedure
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
if (iChOut=DF_SEQ_CHANNEL_NOT_AVAILABLE) begin
send Info_Box "No Channel Available for Output" "Error"
procedure_return
end
// 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!"
Loop
// close output channel
Close_Output Channel iChOut
// release channel for reuse
send Seq_Release_Channel iChOut
End_Procedure // DoOutputData
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: PORTRAIT: NO_OEMTRANSLATE"
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.
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
Close_Output
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"
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
Loop
Close_Input
Close_Output
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:
\\{ServerName}\{PrinterName}
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) 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.
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.
When two or more output destinations or input sources need to be open at the same time, use the Channel option to open additional channels. We highly recommend using channels in all sequential input and output operations to improve code reusability. 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 for proper use of the channel command option.
If {FileName} does not exist when Append_Output is executed, the file is created. If {FileName} does exist when Append_Output is executed, the file is opened and subsequent output directed to this file is appended to the end of the file. The channel position can be set to another value using the Set_Channel_Position command.
When Append_Output command occurs on a channel already open for output, the old destination is closed, and the new one is opened.
Using
Append_Output with the Channel {ChannelNumber} component, but
without a device name causes the current output channel number to
change to the mentioned channel, and does not close the previously
opened device on that channel. This technique is useful when the channel
dependent variables (such as SeqEOF) need to be processed.
Caution: Unexpected behavior can result from mixing sequential
I/O code that uses channels with code that does not, since sequential
I/O code that does not use explicit channel numbers will use
the default channel or the last channel explicitly specified. We recommend
always explicitly using channel numbers.
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