SplPdSendCmd
SplPdSendCmd is an API exported by port drivers. It is called by a protocol converter to send protocol-specific commands to the printer. SplPdSendCmd does not return any response data from the printer. This is an optional API.
If the port driver exports SplPdSendCmd, the spooler passes the address of this function to the BIDI protocol converter SplProtSendCmd. The purpose is to achieve better performance of query requests.
Syntax
SplPdSendCmd(pszPortName, flOptions, 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.
- flOptions (ULONG) - input
- Flags defining how to send the data to the printer.
- All other bits must be clear. Values are as follows:
- FLG_MUSTCOMPLETE - 0x00000001 : If set, the caller does not want to return until the command sequence is sent to the printer.
- If this flag is not set, the caller returns immediately if unable to send the command. For example, the command might not be sent if the printer is being sent a job and the printer cannot accept commands inside a job boundary.
- FLG_SYNCH - 0x00000002 : If set, waits for any current job to finish being sent to the printer before sending this command sequence.
- FLG_MORECMDS - 0x00000004 : If set, more SplPdSendCmd calls are necessary to complete the current query or set command.
- FLG_DATACHANNEL - 0x00000008 : If set, the data channel should be used for this command.
- The data channel is the channel into the printer on which print job data is sent. Some printers also support a command channel, such as SNMP, which can be used to send commands into the printer.
- However, some commands must be sent to the printer using the data channel instead of the command channel (for example, sending a PJL query requires sending the PJL command via the data channel.)
- FLG_SNMPCHANNEL - 0x00000010 : If set, the SNMP channel should be used for this command.
- If this flag is set and there is no SNMP channel available, ERROR_INVALID_PATH(253) is returned.
- FLG_RESERVEDCHANNEL - 0x00000020 : This bit may be used to access a special channel in the port driver. If this flag is set and the port driver does not support a special channel, the default command channel should be used to send this data to the printer.
- FLG_MUSTCOMPLETE - 0x00000001 : If set, the caller does not want to return until the command sequence is sent to the printer.
- ulCommand (ULONG) - input
- Generic command code.
- This code is given to the port driver for information only. The pInData parameter contains the BIDI software protocol-specific packet to send to the printer.
- Current commands are as follows:
- BIDI_Q_SW(800Ch) : Query BIDI software capabilities.
- BIDI_Q_DEVICE(800Dh) : Query printer device characteristics.
- BIDI_Q_INTERPRETER(800Eh) : Query interpreters available in the printer.
- BIDI_Q_INPUTBINS(800Fh) : Query input bins.
- BIDI_Q_OUTPUTBINS(8010h) : Query output bins.
- BIDI_Q_FONTS(8012h) : Query fonts for a particular interpreter.
- BIDI_Q_JOBS_COMPLETE(8013h) : Query list of completed jobs.
- BIDI_Q_JOBS_QUEUED(8014h) : Query list of queued jobs.
- BIDI_Q_STATUS(8015h) : Query current status of the print device.
- BIDI_Q_STORAGE(8023h) : Return printer storage media.
- pInData (PVOID) - input
- Contains the command sequence to pass to the printer.
- This parameter will not be altered by the port driver.
- cbInData (ULONG) - input
- Length of command sequence in pInData, in bytes.
Returns
- rc (ULONG) - returns
- Return codes.
- 0 Success
- 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 command sequence.
- 87(ERROR_INVALID_PARAMETER) : An invalid buffer was given.
- 253(ERROR_INVALID_PATH) : Invalid channel requested.
- 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.
- 0x4013(PMERR_SPL_JOB_PRINTING)
- A job is being sent to the printer, the printer cannot accept commands while receiving job data, and FLG_MUSTCOMPLETE is clear.
- 0x403D(PMERR_SPL_CNV_NOT_INIT) :The protocol converter or port driver has not been initialized for this port.
Sample
#define INCL_SPL
#define INCL_SPLBIDI
#include <os2.h>
PSZ pszPortName; /* Port name. */
ULONG flOptions; /* Flags defining how to send the data to the printer. */
ULONG ulCommand; /* Generic command code. */
PVOID pInData; /* Contains the command sequence to pass to the printer. */
ULONG cbInData; /* Length of command sequence in pInData, in bytes. */
ULONG rc; /* Return codes. */
rc = SplPdSendCmd(pszPortName, flOptions,
ulCommand, pInData, cbInData);
Remarks
The caller will only wait for a response inside the protocol converter, because the protocol converter is the only part of the system that can match a command with the printer's response.
If the last SplPdSendCmd has FLG_MORECMDS set and no new SplPdSendCmd is issued for the port driver's timeout, then the port driver should allow a job to be sent. This can happen only when there is a problem with the protocol converter.