dvc_open()

Purpose

Selects a printer. (Use dvc_choose() or dvc_choose(NO_SELECT) in preference to this function.)

Old name

#define printer dvc_open

Syntax

boolean dvc_open(device, printer_nr, char*file_name, ADDITIONAL)

Parameters

int device

Determines where output is to be sent

int printer_number

Number of printer

char* file_name

Null-terminated string containing name of file (if used) to which output is sent

ADDITIONAL

Indicates fixed width if in use

The parameter device determines where to send output. It can take any combination of the following values:

Value

Meaning

SCREEN

Output is sent to the screen. For more information on the behaviour of this flag refer to the documentation of dvc_choose().

PRINTER

Output is sent to the printer determined by the parameter printer_number. If the printer is in use, the output is saved in a file and printed when the program finishes

FILE

Output is put in the file named by the parameter file_name. This file will default to the directory specified in the file DATAFIT.SYS. If the string in the parameter file_name is without a suffix, ".PRN" is added

NOCTL

Used with the value FILE to prevent the inclusion of printer control characters in the file

NO_APPEND

Forces the creation of the new print file by deleting the old file of the same name

SPOOL_ALWAYS

Causes the print output to be spooled even if the printer is available. This feature is only available under CDOS

OFFER_DELETE

If the output file already exists, a menu offering options to delete the file, append to it, or cancel printing is displayed. If cancel is selected or <Esc> pressed, the value FALSE is returned and the global variable pr_available is set to -1

Description

The dvc_open() function selects a device for subsequent printing. The printer_number is the number assigned to the printer when it was set up using the utility DFSETUP. A header file called DEVICES.H containing these numbers can be generated by selecting the option Generate Device Names in DFSETUP. This header file can then be included in C programs. Note that this may create illegal C macros which should be changed or deleted.

Normally, the value 0 is used as the parameter printer_number, because the printer can be specified as a command tail (see below).

In previous versions of the function dvc_open(), the user was offered a choice between retrying and aborting the program when the selected printer is not available. Now the user is offered a "retry or abort" message and if abort is chosen, the function returns FALSE and the global variable pr_available is set to -1.

The values held in the parameter device can be overridden with command tails:

Tail

Effect

-PRINTER

Causes output to go to the printer as well as to any other specified output device

-DEVICE <device_name>

Sets the parameter printer_number to the device corresponding to <device_name>

-FILE <file_name>

Sets the parameter <file_name>, causing output to go to this file as well as to any other specified output device

The following global variables are set when the function dvc_open() is called:

pr_page

1

pr_line

0

page_depth

The page depth of the printer as set up with DFSETUP

page_width

The page width of the printer as set up with DFSETUP

print_error

Error code returned when opening the printer. The global variable pr_err_mode affects how the program reacts to printer errors. See the function dvc_check()

pr_available

Set to 1 if the selected printer is available, or no printer was selected. If spooling is possible, the global variable pr_available contains 0, otherwise it contains -1

pr_started

Set to TRUE if the printer is opened successfully, and is reset to FALSE when the function dvc_close() is called

pr_filename

Contains the name of the output file if one is being used

pr_streams

Set to the devices chosen.

pr_device

This holds the current printer number

Return values

Returns TRUE if the printer is successfully selected, otherwise FALSE. If spooling is possible, FALSE is returned and the global variable pr_available is set to 0.

See also

form(), prn_x(), dvc_choose(), prn_print(), dvc_check()

Example