Direct_Output

Purpose

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

Syntax

General syntax:

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

For sequential file input:

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

For Windows clipboard input:

Direct_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 1 (default for output) 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.

Drivers:

[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

Direct_Output sets the destination for sequential output from the program. There are three supported sequential file output options for DataFlex: a sequential file, the printer, or the clipboard.

A sequential file is generally opened at the beginning of file. Use Set_Channel_Position command to change the point from which data will be read. Get_Channel_Position returns the current position of the input channel.

The Flush_Output command immediately forces a write of this cached data. This can be useful when writing to a log file while troubleshooting application crashes. Note that doing a flush is not necessary when closing the output, as the Close_Output command itself already does this.

Direct_Output to a Sequential File

This is the simplest case of sequential file output.

Example

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

Procedure DoOutputData String sFileName

Integer iCount

// Create a text file. Replaces the file if it already exists.

Direct_output sFileName

For iCount From 1 To 10

Writeln "Line: " iCount " - Hello!"

Loop

Close_Output

End_Procedure

Example

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 Direct_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. Replaces the file if it already exists.

Direct_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

Direct_Output to a Printer

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

Direct_Output "WinLST: Font: Arial"

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

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

Direct_Output "WinLST: PORTRAIT: NO_OEMTRANSLATE"

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

Direct_Output "WinLST: LPT1:"

Direct_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.

Example

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

Direct_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

Example

In either of the following example code lines, the direct_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.

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

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

Direct_Output to the Windows Clipboard

The Direct_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"

Direct_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)

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.

Drivers:

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.

Example

Direct_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.

Notes

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 a Direct_Output is executed, the file is created. Direct_output always opens a file for output at the beginning of the file. The channel position can be set to another value using the Set_Channel_Position command.
To open a file without erasing it, use the Append_Output command.
When Direct_Output command occurs on a channel already open for output, the old destination is closed, and the new one is opened.
Using Direct_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.

Example

Direct_Output Channel 1 "MyFile.Txt"

// Now the current output channel is 1

Direct_Output Channel 2 "MyOtherFile.Txt"

// Now the current output channel is 2

Direct_Output Channel 1

// Now the current output channel is 1 again