Click above to get retro games delivered to your door ever month!

N_CAPSET( <cDevice>|<nDevice>, 
          <cAttribute1>|<nAttribute1>, <Setting1>
       [, <cAttribute2>|<nAttribute2>, <Setting2>... ] )
-- or --
N_CAPSET( <cDevice>|<nDevice>, <aAttribute>, <aSetting> )


Parameters

<cDevice> -- or -- <nDevice>
Capture device name or number. Valid names are LPT1 to LPT3. Use "LPT*" 
to refer to the default capture device (usually LPT1). Valid numbers 
are 0 through 3, where 1 stands for LPT1, 2 for LPT2, and 3 for LPT3. 
Use 0 to refer to the default capture device.

Note  Before you refer to the default device by using LPT* or 0, 
you must first have set the default device with N_CAPDFLT().  The 
default capture device is generally LPT1 at program startup, but this 
varies from system to system.

<cAttribute> -- or -- <nAttribute>
Attribute to set. May be passed as a text string or as a numeric value. 
See the table below for a list of capture attributes that may be set.

<Setting>
Value to which the attribute should be set.

<aAttribute>
An array containing the names or numbers of the attributes you wish to 
set. This is an alternative to passing a series of <Attribute>, 
<Setting> pairs.

<aSetting>
An array of values for the attributes listed in the corresponding array 
<aAttribute>.

The number of elements in <aSetting> must be equal to or greater than 
the number of elements in <aAttribute>, or attributes may be set to 
unintended values.


Returns

Zero if all attributes passed to the function were set. Otherwise,
the function returns a number corresponding to the position in the
argument list of the first item that caused the failure.

For example, if you attempt to set only one attribute and pass an
incorrect attribute name, the function will return 2. This indicates
that the second argument caused the failure. On the other hand, if
the attribute name is incorrect but the setting is invalid, the function
will return 3, indicating that the third argument caused the failure.


Description

Sets the attributes of the specified capture device to the indicated 
values. You can include as many attribute/value pairs as needed. 
Setting multiple attributes in a single call is more efficient than 
repeated calls to N_CAPSET().

Attributes may be specified by name or number. Attribute numbers are 
defined as manifest constants in CAPTURE.CH. Using constants or their 
literals will give slightly better performance than using names.

The attributes listed below may be changed.

Text          #define             Attribute
AUTOEND       CAP_AUTOEND         Auto end capture
BANNER        CAP_BANNER          Print banner
COMMAND       CAP_COMMAND         Capture command
COPIES        CAP_COPIES          # of copies
CPL           CAP_CPL             Characters per line
FNAME         CAP_FNAME           Name of form
FORMNO        CAP_FORMNO          Form type (class)
JNAME         CAP_JNAME           Job name
LPP           CAP_LPP             Lines per page
NOFF          CAP_NOFF            No form feed
NOTIFY        CAP_NOTIFY          Job completion notify
PRINTER       CAP_PRINTER         Network printer
QUEUE         CAP_QUEUE           Queue
RESET         CAP_RESET           Printer reset string
SERVER        CAP_SERVER          Server with the queue
SETUP         CAP_SETUP           Printer setup string
TABS          CAP_TABS            Tab expansion count
TIMEOUT       CAP_TIMEOUT         Timeout (seconds)
USER          CAP_USER            Banner user name

All documents subsequently spooled to the device are affected by the 
settings for these attributes. Documents currently queued are not 
affected. The data types and valid settings for the attributes are 
given below.

AUTOEND
Logical. True sets AutoEndCap On, false sets it Off. AutoEndCap Off 
directs NetWare to queue a print job when the program explicitly issues 
an EndCapture via the COMMAND attibute of N_CAPSET(), or when it 
reaches the TIMEOUT threshold set by the TIMEOUT attribute of 
N_CAPSET(). AutoEndCap On directs NetWare to queue a print job when the 
print device is closed. Normally, this is when the program ends, but 
the device is also closed by the Clipper sequence:

SET PRINTER TO LPT1  // (or LPT2, LPT3)
.
.               // Print job
.
SET PRINTER TO  // Device closed


BANNER
String (1-12 characters). Text for banner page. Lowercase will be 
forced to uppercase. A null string means do not print a banner page.

COMMAND
Capture command is accepted by N_CAPSET() but not by N_CAPGET(). You 
may set it to one of the following:

Literal       #define             Meaning
C             CAP_CANCEL          Cancel capture
E             CAP_END             End capture
F             CAP_FLUSH           Flush capture
S             CAP_START           Start capture

COPIES
Numeric (1- 99). The number of copies that will be printed. The default 
is one.

CPL
Numeric. The maximum number of characters per line of the printed page. 
The default is 132.

FNAME
String (1-12 characters). Name of a form that has been defined by 
PRINTDEF. The attributes defined in a PRINTDEF form are FORM, LPP, and 
CPL. If a valid form name is specified, NetLib will automatically take 
the attributes from the form's definition, just as if they had been 
issued with N_CAPSET().

FORMNO
Numeric. Also referred to as Print Class or Form Type. When a print 
server is loaded, it normally begins printing jobs of print class zero. 
If a job is queued with another print class, the print server will 
pause, broadcast a message requesting that the appropriate form be 
mounted, and will not proceed until the user or operator responds that 
the form has been mounted. The response can be made through your 
application by using the NetLib function N_PSSET() to set the FORMNO 
attribute appropriately.

JNAME
String (1-12 characters). A name of a job defined with the NetWare 
utility PRINTCON. The attributes defined in a PRINTCON job are AUTOEND, 
BANNER, COPIES, NOFF, TABS, TIMEOUT, USER, NOTIFY, and QUEUE. If a 
valid PRINTCON job name is specified, NetLib will automatically take 
the attributes from the job definition, just as if they had been issued 
with N_CAPSET().

The JNAME attribute is accepted by N_CAPSET() but not by N_CAPGET().

LPP
Numeric. The maximum number of lines per page. The default is 66.

NOFF
Logical. False is the normal setting and means that NetWare will 
generate a page eject at the end of each print job. (This is in 
addition to any page ejects contained in the job itself.) A setting of 
true means no trailing form feed-that is, NetWare will not generate a 
page eject at the end of each print job.

NOTIFY
Logical. True tells the print server to send a broadcast message 
notifying the user when a print job is done. False means turn this 
feature Off.

Note  Not all printers support NetWare's print notify option.

PRINTER
Numeric (0-15). Generally reserved for use with NetWare 2.0x and 
earlier, or for NetWare 286/386 in 2.0x "compatibility mode." In 
NetWare 286 and later, print output is directed to print queues rather 
than to physical printers.

QUEUE
String. Name of the print queue. To specify a queue on another server, 
you can prefix the queue name with <cServer>/, as in "FS1/PRINTQ_0". If 
no server prefix is specified here or in attribute SERVER, the current 
preferred server is assumed. The preferred server can be changed with 
the N_SERVER() function.

RESET
String. Printer reset buffer. The maximum length of the string is the 
value of attribute RESETMAX, which you can obtain by calling 
N_CAPGET(). If you set attribute RESET with a string that is too long, 
no change is made. Setting the attribute to a null string clears the 
buffer.

SERVER
String. Name of the server with the queue. If no server is specified 
here or in attribute QUEUE, the current preferred server is assumed. 
The preferred server can be changed with the N_SERVER() function.

SETUP
String. Printer initialization buffer. The maximum length of the string 
is the value of attribute SETUPMAX, which you can obtain by calling 
N_CAPGET(). If you set attribute SETUP with a string that is too long, 
no change is made. Setting the attribute to a null string clears the 
buffer.

TABS
Numeric. Number of spaces that will be substituted for each tab 
character (I or ASCII 9). Zero means that there will be no tab 
expansion.

Note  When output consists of non-printing control characters such
      as in a font description file, TABS should be set to zero.

TIMEOUT
Numeric. Printer timeout value in seconds. If the program does not 
generate print output for this number of seconds, the network will 
assume that the document is complete and will place the job in the 
queue. Zero means timeout suppressed.

USER
String (1-12 characters). User name that will appear on the banner 
page, in addition to banner text, if a banner page is generated. 
Characters will be converted to uppercase. The initial value is the 
first twelve letters of the user's login name. NetWare will assign the 
same user name to all capture devices regardless of the value of the 
<nDevice> argument to N_CAPSET(). It is possible, however, for the 
BANNER attribute to be different for each device.


Files

CAPTURE.CH