dvc_choose()

Purpose

Selects a printer

Old name

#define ask_output_device dvc_choose

Syntax

int dvc_choose(device, printer_nr, file_name, ADDITIONAL)

Parameters

int device_flags

Indicates where output is to send plus other options as detailed below

 

int printer_nr

Number of the DFSETUP POD device to be used. If you need to hard code a device you should use DFSETUP to generate a suitable include file.

 

char *file_name

File name used for output if FILE is selected for output

 

ADDITIONAL

Two optional variables, including the default suffix of the file name and also the fixed width

 

The device_flags parameter is a combination of the following values:

 

Flag Meaning

 

SCREEN

Output is sent to the screen. The data is displayed below any maps on the screen and is scrolled, or from release 4.621 and if the use_viewer setting is in effect, is displayed using the designated viewer program when dvc_close() is called. If a DFPRINT device is selected DFPRINT will default to Landscape format instead of Portrait format unless PRINTER is also specified. Normally DFPRINT works in interactive mode when SCREEN is specified. To print immediately in Landsape format, without user interaction you need to also specify NO_SELECT and NOCTL. (Note that this means printing will take place even though the PRINTER flag is not specified. If the DFPRINT device specifies that the output should be saved to a file, then in this situation the output will be saved to the appropriate type of file instead)

 

PRINTER

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

 

FILE
DP4_FILE

Output is sent to the file named by the parameter file_name. This file defaults to the directory specified in the DP4 licence file. If the parameter file_name has no suffix, .PRN is added, or the extension specied as thr fourth parameter if FT_DEFAULT is also passed in device flags. The FILE pre-processor define makes it difficult to use ANSI C file output functions. You can prevent FILE from being defined by defining NO_ANSI_POLLUTE before including dp4capi.h. DP4_FILE is a synonym for FILE that is defined in the 4.620 header files.

The file is formatted using the characterstics of the device specified.

 

NOCTL

Used with DP4_FILE to prevent printer control characters from being sent to the file (they are still sent to the printer)

 

NO_APPEND

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

 

FT_DEFAULT

If this flag is used, the ADDITIONAL (char*) parameter should also be used to give the default suffix for the output file. This is displayed in the Select output devices dialog box instead of the normal default "(.PRN)"

 

NONE_ALLOWED

This disables the validation that ensures at least one of SCREEN,PRINTER or FILE is chosen.

 

NO_SELECT

This stops the user from being asked any questions. However, if the printer is not successfully selected and the global variable pr_available is -1, this value has no effect unless the NO_RETRY flag is also used

 

FIXED_WIDTH

This causes all lines to be forced to the width given by a fifth parameter. If FT_DEFAULT is not used you need to specify a dummy fourth parameter.

 

NO_RETRY

If the output values have been obtained from the user and the global variable pr_available is -1, the user has to re-enter the values even if NO_SELECT is passed. If this flag is used, the function dvc_choose() returns FALSE and the global variable pr_available is set to -1

Description

The dvc_choose() function replaces the older function dvc_open() for selecting a printer.

Unless the flag NO_SELECT is used, the function displays the "Select output devices" dialog on the screen, with the initial default values are given by the parameters to dvc_choose(). The user can fill in the fields and select the logical printer from a pop up.

If an output file is chosen and the file already exists, a delete/append/cancel menu is offered. If the user chooses cancel or presses Esc at this point, the "Select output devices" dialog reappears (even if NO_SELECT was specified) unless dvc_choose() is called with the flag NO_RETRY, in which case the function returns 0 and the global variable pr_available is set to -1.

A program that calls dvc_choose() may be invoked with these command tails:

 
Tail Effect
−PRINTER

This causes output to go to the printer as well as to any other selected output device

−DEVICE device_name

This sets the printer_number parameter to the corresponding device_name

−FILE file_name

This causes the output to go the file given by file_name as well as to any other selected output device. The specified file_name overrides the hard-coded file name

−SCREEN

This causes the output to go the screen as well as to any other selected output device.

 

The following global variables are set when dvc_choose() is called:

 

Global Variable

Set To

 

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 updated device value. You should use this value and not the device value passed to the function to test which output devices are being used

 

pr_device

This holds the current printer number

Return values

Returns ESCAPE if the user has pressed Esc or 0 if the printer is not available but is being spooled. Returns 1 if the printer is available

See also

dvc_open()

Example 

/*
 C Functions Reference Manual
 ----------------------------
 Filename: DVC_CHOO.C
 Example: dvc_choose
 Purpose: simple customer listing reoprt output to  devices.
*/
/*
#db salesord
#c
#libtype 1
#tables customer,
        index_cust_name;
#end
*/
#include "dp4.h"
#include "dvc_choo.h"
 /* generate this file by running LIBMAKE */
 /* prototypes */
void cust_report(void);
void process()
{
   map_draw(1,RETAIN);
   cust_report();
}
void cust_report()
{
   if (dvc_choose(PRINTER|SCREEN,0,"","") != ESCAPE)
   {
      int srch = FIRST;
      form(1);
      /* fetch and print all customers */
      while (rec_fetch(srch,&customer.l,_INDEX_CUST_NAME,0))
      {
         srch = NEXT;
         form(2);
         prnc(2,1,customer.name,DEFAULT);
         prnn(2,2,customer.customer_number,DEFAULT);
         prnc(2,3,customer.address[0],DEFAULT);
         prnn(2,4,customer.credit_limit,DEFAULT);
         prnn(2,5,customer.balance,DEFAULT);
         prn_print(FALSE);
      }
      dvc_close(0);
   }
}