source: rxprtutl/trunk/notes@ 13

Last change on this file since 13 was 13, checked in by Alex Taylor, 12 years ago

Added RPUPortQuery function, improved discussion of port driver settings in 'notes'.
File size: 10.0 KB
Line 
1Using RPUPortQuery & RPUPortSet
2===============================
3
4These functions return or accept a buffer (passed as a REXX string) which
5contains the current port configuration data as raw bytes. The format of
6this data depends on the port driver which controls the particular port
7being queried or set.
8
9The data formats for several common port drivers are described below.
10
11NOTE: All data must be in raw byte (or 'character') form. This is the form
12 outputted by functions like D2C() or X2C().
13
14 In addition, multi-byte integer values like (U)LONG and (U)SHORT must
15 be passed in little-endian order.
16
17 i.e.
18 To convert <number> to USHORT: ushort = REVERSE( X2C( D2X( number, 4 )))
19 To convert <number> to ULONG: ulong = REVERSE( X2C( D2X( number, 8 )))
20
21
22SERIAL.PDR, PARALLEL.PDR
23------------------------
24
25The standard serial and parallel port drivers do not support the SplPdSet API.
26
27
28PAR1284.PDR
29-----------
30
31The high-speed BIDI parallel port (PAR1284) driver uses a data structure with
32the following format (information taken from IBM DDK headers):
33
34typedef struct _PORTSETTINGS{
35 ULONG signature; /* Must be 0x52464E49 ('INFR') */
36 ULONG ulVersion; /* Must be 0x00000001 */
37 ULONG flStatus; /* Status flags: */
38 /* 0x00000001 BIDI_Q_PORT set (bidi enabled)*/
39 /* 0x00000002 Set after 1st attempt at bidi */
40 /* 0x00000004 Port connected to print queue */
41 /* 0x00000008 Port already open */
42 /* 0x00000010 Port open in progress */
43 /* 0x00000020 SplPdOpen being processed */
44 /* 0x00000040 SplPdClose being processed */
45 /* 0x00000080 XlateCmd has more alerts left */
46 /* 0x00000100 New printer or powered off */
47 /* 0x00000200 Set when deviceId was checked */
48 /* after first good write to a */
49 /* unidirectional printer. */
50 /* 0x00000400 Set when last write was sent */
51 /* using ECP mode cmd channel. */
52 /* 0x00000800 Set when printer put in bidi */
53 /* mode and DeviceID received. */
54 /* 0x00001000 Set when CommStatChange alert */
55 /* was posted to spooler. */
56 /* Cleared after BIDI_Q_PORT */
57 /* 0x00002000 Set when CommStatChange alert */
58 /* should not be set */
59 /* 0x00004000 Set when port has a network */
60 /* connection */
61 ULONG flBidiCapabilities; /* PRTPORT.flBidiCapabilities _CAPS_ */
62 ULONG flBidiProtocol; /* PRTPORT.flBidiProtocol _TYPE_ */
63 ULONG flJob; /* PRTSW.flJob flags */
64 ULONG flDevice; /* PRTSW.flDevice flags */
65 ULONG ulModeSelected; /* Mode selected by user(see PARMODE_) */
66 ULONG ulCurrentMode; /* Current mode of port(see CURMODE_) */
67 BOOL fShareAccess; /* Share port with DOS/Windows */
68 ULONG ulPrintTimeOut; /* Seconds to continue to retry job */
69 /* write request in SplPdWrite(). */
70 /* Default: 45 seconds */
71 ULONG ulNoQueryTimeOut; /* Seconds from last query until */
72 /* port drops printer connection */
73 /* Default: 180 seconds */
74 ULONG ulNoJobTimeOut; /* Seconds from last job sent until */
75 /* port drops printer connection */
76 /* NOTE: Connection can be dropped */
77 /* sooner if PDR receives */
78 /* BIDI_NOTIFY_ENDJOBCONNECT */
79 /* This is used if we lose */
80 /* a job acknowledgement so */
81 /* that other Apps can use the */
82 /* infrared port. */
83 /* Default: 300 seconds */
84 /* */
85 PPTIMEOUTCHANNEL TimeOut; /* Read and Write timeouts */
86 /* */
87 /* */
88 /* The following ulpsz fields are */
89 /* offsets from the beginning of */
90 /* this PORTSETTINGS structure to */
91 /* the variable length strings. */
92 /* This allows us to pass the buffer */
93 /* intact to PrtQuery and PrtSet, */
94 /* even across the network. */
95 /* All strings are packed immediately */
96 /* after the fixed-length PORTSETTINGS */
97 /* structure. */
98 /* */
99 /* An offset of 0 means no string */
100 /* */
101 ULONG ulpszPortName; /* -> name of port info is for */
102 ULONG ulpszDeviceID; /* -> 1284 deviceID for printer on port */
103} PORTSETTINGS, *PPORTSETTINGS;
104
105/* Structure for setting timeouts */
106/* */
107/* This port driver will assume that bidi capable printers can accept */
108/* data at a reasonable rate, so the WriteIdle timeout will default to a */
109/* small value(like 15 seconds). The actual WriteTimeout specified by */
110/* the user can be larger, and our PdWrite API will handle retrying */
111/* requests that do not complete. However, we will always have a */
112/* ParReadThread for each bidi port, and this read will typically be */
113/* queued up after the write. When a write completes(even if only */
114/* partial buffer was sent), the queued read request will reverse the */
115/* channel and check for data coming from the printer. This read must */
116/* not take a long time(to avoid performance degradation for writes). */
117/* */
118/* We set a small ReadInterrupt timeout( about 200 ms default ) so that */
119/* if no data is waiting to be read, the read request returns and lets */
120/* the write request be processed. */
121/* */
122/* We set a longer ReadIdle timeout( 1000 ms ) to attempt to get the */
123/* entire buffer from the peripheral if there is data waiting to be sent */
124/* to the host. */
125/* */
126/* For now, we set the WriteIdle and WriteInterrupt timeouts to be the */
127/* same. This means we will always return within the WriteIdle timeout */
128/* value specified. */
129/* */
130typedef struct _PPTIMEOUTCHANNEL{
131 ULONG ulReadIdleTimeOut; // millisecs DD has to complete entire Read
132 ULONG ulReadIntTimeOut; // millisecs DD waits for Read interrupt
133 ULONG ulWriteIdleTimeOut; // millisecs DD has to complete entire Write
134 ULONG ulWriteIntTimeOut; // millisecs DD waits for Write interrupt
135 ULONG ulLogChannel; // 1=use data channel, 2=use address channel
136} PPTIMEOUTCHANNEL, *PPPTIMEOUTCHANNEL;
137
138(Refer to the header file wpshell\src\wpsh\par1284\pdrtypes.h from the IBM
139DDK for more information.)
140
141
142CUPS.PDR
143--------
144
145The eCups port driver (CUPS.PDR) uses the following port settings structure:
146
147typedef struct _PORTSETTINGS {
148 CHAR szHost[ 65 ]; // CUPS server hostname/IP
149 CHAR szQueue[ 65 ]; // CUPS printer queue name
150} PORTSETTINGS, *PPORTSETTINGS;
151
152(At least version 1.04 of CUPS.PDR is required.)
153
154
155SMB.PDR
156-------
157
158The Samba port driver (SMB.PDR) takes a single 256-byte buffer. This
159buffer must take the following format:
160
161 host#printer#workgroup#userid#copies#password
162
163All fields are required; those whose values are unspecified must be left
164empty. (Replace each field name above with its corresponding value.)
165The buffer is padded with 0 bytes to a length of 256 as needed.
166
167The 'password' field is a hexadecimal string; all others are standard
168character strings.
169
170For example, to set the following configuration:
171 host: PRINTSRV
172 printer: LJET01
173 workgroup: <none>
174 userid: mrmuffin
175 password: blueberry
176 copies: 1
177
178In REXX:
179 params = 'PRINTSRV#LJET01##mrmuffin#1#626C75656265727279'
180 IF LENGTH( params <= 256 ) THEN DO
181 buffer = params || COPIES('00'x, 256 - LENGTH( params ))
182 CALL RPUPortSet 'SMB', buffer
183 END
184
Note: See TracBrowser for help on using the repository browser.