SplPdSet

SplPdSet is an API exported by port drivers. It is called by PrtSet to set printer device information.

Syntax

SplPdSet(pszPortName, ulType, ulCommand, pInData, cbInData);

Parameters

pszPortName (PSZ) - input: Port name.

Following is an example of a port name:

   LPT1

This will be a locally defined port name.

ulType (ULONG) - input: Type of query and options.

Values are as follows:

TYPE_SHORT_WAIT(1) Sends information via a communications channel with the printer that can be used while a job is being sent to the printer.

An example would be using NPAP or SNMP. If the requested information cannot be sent using this type of channel (for instance, if a PJL command is required to get this information), ERROR_INFO_NOT_AVAIL is returned.

TYPE_LONG_WAIT(2) Sends information using any necessary communications channel with the printer, even if the request has to wait for the current job being sent to the printer to complete.

If the printer supports only one command channel, and this channel can be used while a job is being sent to the printer, TYPE_SHORT_WAIT(1) and TYPE_LONG_WAIT(2) will behave in the same way.

TYPE_WITHOUT_WRAPPER(4) Indicates the information being sent does not have any packet wrapper around it.

This is useful for BIDI_SEND_PASSTHRU as it allows an application to send and receive printer-interpreter language commands without having to know the format of the BIDI protocol's data wrappers. An example would be sending a PostScript query to the printer, and the NPAP protocol converter adds the necessary NPAP wrapper before transmitting the data to the printer.

If BIDI_SEND_PASSTHRU is used without this value, the calling application must have already wrapped the passthru data.

Note: If this value is used with any command other than BIDI_SEND_PASSTHRU, ERROR_INVALID_PARAMETER is returned.

ulCommand (ULONG) - input: Generic command code.

The BIDI protocol converter may be called to generate protocol-specific command data to satisfy set requests. See BIDI Command Structures and Command Flow for contents of pInData and pOutData for each of the following commands.

Current command values are as follows:

BIDI_SEND_PASSTHRU(8001h) : Printer protocol-specific command will be issued to the printer.
BIDI_STARTJOB(2h) : Signals start of print job.
BIDI_ENDJOB(3h): Signals end of print job.
BIDI_HOLDJOB(4h): Holds printer job.
BIDI_RELEASEJOB(5h) : Releases printer job.
BIDI_CANCELJOB(6h): Cancels printer job.
BIDI_INIT_PORTDRV(8h): Initializes a port driver.
BIDI_RESET(9h) : Resets the printer.
BIDI_SHUTDOWN(Ah) : Releases all threads waiting for this port. Used to shut down a printer port. Sent to the protocol converter before being sent to the port driver.
BIDI_INIT(Bh): Sets printer in BIDI mode. Changes printer from unidirectional to bidirectional. Does not call the protocol converter.
BIDI_TERM(Ch) : Sets printer in unidirectional mode. Changes printer from bidirectional to unidirectional. Does not call the protocol converter.
BIDI_RESPONSE_FMT(Dh): Defines the format of printer-to-host messages.
BIDI_PACKET_SIZE(Eh): Defines printer-to-host maximum packet size.
BIDI_SET_PORTDRV(19h): Sets port driver configuration.
BIDI_START_PASSTHRU(1Ah): Initiates a passthru session with the printer.
BIDI_END_PASSTHRU(1Bh) : Terminates a passthru session with the printer.
BIDI_NOTIFY_ENDJOBCONNECT(20h): Notifies port driver that jobs are complete.
BIDI_NOTIFY_PORT_SELECTED(21h): Notifies port driver that printer is connected to print queue. * BIDI_NOTIFY_PORT_RELEASED(22h): Notifies port driver that printer is not connected to print queue.
BIDI_SET_DEVICE_ID(23h) : Tells port driver the printer's device ID.
BIDI_ENABLE_ALERT(24h) : Enables printer alerts.
BIDI_DISABLE_ALERT(25h) : Disables printer alerts.
BIDI_ADD_VIRTUAL_PORT(26h) : Adds a virtual port.
BIDI_DEL_VIRTUAL_PORT(27h): Deletes a virtual port.
BIDI_DEL_PORT(28h) : Indicates a spooler port has been deleted.
0x0000B000 - 0x0000BFFF : Port-driver-specific commands.

pInData (PVOID) - input: May contain information required by SplPdSet.

If BIDI_SEND_PASSTHRU is set, this parameter contains the command sequence to pass to the printer and will not be altered by the port driver.

If BIDI_SEND_PASSTHRU is not set, this parameter may contain information required by SplPdSet. See BIDI Command Structures and Command Flow for specific information definitions.

cbInData (ULONG) - input: Length of information in pInData, in bytes.

Returns

rc (ULONG) - returns: Return codes.

0 Success

1(ERROR_INVALID_FUNCTION) The command code is not supported. This lack of support may occur if a new command is sent to an old spooler, port driver, or protocol converter.

2(ERROR_FILE_NOT_FOUND) The pszPortName given is not a valid port name configured for this port driver.

5(ERROR_ACCESS_DENIED) Not authorized to access printer port.

8(ERROR_NOT_ENOUGH_MEMORY) Not enough memory to satisfy request.

29(ERROR_WRITE_FAULT) Failure attempting to write to the device. The printer might not have received the set request.

87(ERROR_INVALID_PARAMETER) An invalid parameter was specified; most likely an invalid buffer pointer was given.

211(ERROR_INFO_NOT_AVAIL) The requested information is not available in the protocol converter cache, or the request cannot be sent with the given ulType value. The request should be reissued with a different ulType value.

640(ERROR_TIMEOUT) The set command was not able to be sent to the printer within the time allotted.

683(ERROR_BIDI_NO_SUPPORT) The printer is not in bidirectional mode, therefore query requests are not honored. The port also may be in the process of being shut down.

0x1403(PMERR_ALREADY_INITIALIZED) The port driver has already been initialized for the port.

0x4005(PMERR_SPL_INV_HSPL) Not currently in a passthru session.

0x4011(PMERR_SPL_INV_JOB_ID) The Job ID is not known.

0x403D(PMERR_SPL_CNV_NOT_INIT) The protocol converter or port driver has not been initialized for this port.

Remarks

Example Code


#define INCL_SPL
#define INCL_SPLBIDI
#include <os2.h>

PSZ      pszPortName;  /*  Port name. */
ULONG    ulType;       /*  Type of query and options. */
ULONG    ulCommand;    /*  Generic command code. */
PVOID    pInData;      /*  May contain information required by SplPdSet. */
ULONG    cbInData;     /*  Length of information in pInData, in bytes. */
ULONG    rc;           /*  Return codes. */

rc = SplPdSet(pszPortName, ulType, ulCommand, pInData, cbInData);

Related Functions

[[]]