Using RPUPortQuery & RPUPortSet
===============================

These functions return or accept a buffer (passed as a REXX string) which
contains the current port configuration data as raw bytes.  The format of
this data depends on the port driver which controls the particular port
being queried or set.

The data formats for several common port drivers are described below.

NOTE: All data must be in raw byte (or 'character') form.  This is the form
      outputted by functions like D2C() or X2C().

      In addition, multi-byte integer values like (U)LONG and (U)SHORT must
      be passed in little-endian order.

      i.e.
      To convert <number> to USHORT:  ushort = REVERSE( X2C( D2X( number, 4 )))
      To convert <number> to ULONG:   ulong  = REVERSE( X2C( D2X( number, 8 )))

      Fixed-length string (character array) fields MUST append a 0 byte to
      the end of the string value, and SHOULD pad the rest of the array (up
      to the defined length) with 0 bytes as well.


SERIAL.PDR, PARALLEL.PDR
------------------------

The standard serial and parallel port drivers do not support the SplPdSet API.


PAR1284.PDR
-----------

The high-speed BIDI parallel port (PAR1284) driver uses a data structure with
the following format (information taken from IBM DDK headers):

typedef struct _PORTSETTINGS{
   ULONG   signature;           /* Must be 0x52464E49 ('INFR')               */
   ULONG   ulVersion;           /* Must be 0x00000001                        */
   ULONG   flStatus;            /* Status flags:                             */
                                /* 0x00000001  BIDI_Q_PORT set (bidi enabled)*/
                                /* 0x00000002  Set after 1st attempt at bidi */
                                /* 0x00000004  Port connected to print queue */
                                /* 0x00000008  Port already open             */
                                /* 0x00000010  Port open in progress         */
                                /* 0x00000020  SplPdOpen being processed     */
                                /* 0x00000040  SplPdClose being processed    */
                                /* 0x00000080  XlateCmd has more alerts left */
                                /* 0x00000100  New printer or powered off    */
                                /* 0x00000200  Set when deviceId was checked */
                                /*             after first good write to a   */
                                /*             unidirectional printer.       */
                                /* 0x00000400  Set when last write was sent  */
                                /*             using ECP mode cmd channel.   */
                                /* 0x00000800  Set when printer put in bidi  */
                                /*             mode and DeviceID received.   */
                                /* 0x00001000  Set when CommStatChange alert */
                                /*             was posted to spooler.        */
                                /*             Cleared after BIDI_Q_PORT     */
                                /* 0x00002000  Set when CommStatChange alert */
                                /*             should not be set             */
                                /* 0x00004000  Set when port has a network   */
                                /*             connection                    */
   ULONG   flBidiCapabilities;  /* PRTPORT.flBidiCapabilities _CAPS_     */
   ULONG   flBidiProtocol;      /* PRTPORT.flBidiProtocol _TYPE_         */
   ULONG   flJob;               /* PRTSW.flJob flags                     */
   ULONG   flDevice;            /* PRTSW.flDevice flags                  */
   ULONG   ulModeSelected;      /* Mode selected by user(see PARMODE_)   */
   ULONG   ulCurrentMode;       /* Current mode of port(see CURMODE_)    */
   BOOL    fShareAccess;        /* Share port with DOS/Windows           */
   ULONG   ulPrintTimeOut;      /* Seconds to continue to retry job      */
                                /*  write request in SplPdWrite().       */
                                /*  Default: 45 seconds                  */
   ULONG   ulNoQueryTimeOut;    /* Seconds from last query until         */
                                /*  port drops printer connection        */
                                /*  Default: 180 seconds                 */
   ULONG   ulNoJobTimeOut;      /* Seconds from last job sent until      */
                                /*  port drops printer connection        */
                                /*  NOTE: Connection can be dropped      */
                                /*        sooner if PDR receives         */
                                /*        BIDI_NOTIFY_ENDJOBCONNECT      */
                                /*        This is used if we lose        */
                                /*        a job acknowledgement so       */
                                /*        that other Apps can use the    */
                                /*        infrared port.                 */
                                /*  Default: 300 seconds                 */
                                /*                                       */
   PPTIMEOUTCHANNEL TimeOut;    /* Read and Write timeouts               */
                                /*                                       */
                                /*                                       */
                                /* The following ulpsz fields are        */
                                /*  offsets from the beginning of        */
                                /*  this PORTSETTINGS structure to       */
                                /*  the variable length strings.         */
                                /* This allows us to pass the buffer     */
                                /*  intact to PrtQuery and PrtSet,       */
                                /*  even across the network.             */
                                /* All strings are packed immediately    */
                                /*  after the fixed-length PORTSETTINGS  */
                                /*  structure.                           */
                                /*                                       */
                                /* An offset of 0 means no string        */
                                /*                                       */
   ULONG   ulpszPortName;       /* -> name of port info is for           */
   ULONG   ulpszDeviceID;       /* -> 1284 deviceID for printer on port  */
} PORTSETTINGS, *PPORTSETTINGS;

/* Structure for setting timeouts                                        */
/*                                                                       */
/* This port driver will assume that bidi capable printers can accept    */
/* data at a reasonable rate, so the WriteIdle timeout will default to a */
/* small value(like 15 seconds). The actual WriteTimeout specified by    */
/* the user can be larger, and our PdWrite API will handle retrying      */
/* requests that do not complete.  However, we will always have a        */
/* ParReadThread for each bidi port, and this read will typically be     */
/* queued up after the write. When a write completes(even if only        */
/* partial buffer was sent), the queued read request will reverse the    */
/* channel and check for data coming from the printer.  This read must   */
/* not take a long time(to avoid performance degradation for writes).    */
/*                                                                       */
/* We set a small ReadInterrupt timeout( about 200 ms default ) so that  */
/* if no data is waiting to be read, the read request returns and lets   */
/* the write request be processed.                                       */
/*                                                                       */
/* We set a longer ReadIdle timeout( 1000 ms ) to attempt to get the     */
/* entire buffer from the peripheral if there is data waiting to be sent */
/* to the host.                                                          */
/*                                                                       */
/* For now, we set the WriteIdle and WriteInterrupt timeouts to be the   */
/* same.  This means we will always return within the WriteIdle timeout  */
/* value specified.                                                      */
/*                                                                       */
typedef struct _PPTIMEOUTCHANNEL{
   ULONG   ulReadIdleTimeOut;  // millisecs DD has to complete entire Read
   ULONG   ulReadIntTimeOut;   // millisecs DD waits for Read interrupt
   ULONG   ulWriteIdleTimeOut; // millisecs DD has to complete entire Write
   ULONG   ulWriteIntTimeOut;  // millisecs DD waits for Write interrupt
   ULONG   ulLogChannel;   // 1=use data channel, 2=use address channel
} PPTIMEOUTCHANNEL, *PPPTIMEOUTCHANNEL;

(Refer to the header file wpshell\src\wpsh\par1284\pdrtypes.h from the IBM
DDK for more information.)


CUPS.PDR
--------

The eCups port driver (CUPS.PDR) uses the following port settings structure:

typedef struct _PORTSETTINGS {
   CHAR     szHost[ 65 ];       // CUPS server hostname/IP
   CHAR     szQueue[ 65 ];      // CUPS printer queue name
} PORTSETTINGS, *PPORTSETTINGS;

(At least version 1.04 of CUPS.PDR is required.)


SMB.PDR
-------

The Samba port driver (SMB.PDR) takes a single 256-byte buffer.  This
buffer must take the following format:

    host#printer#workgroup#userid#copies#password

All fields are required; those whose values are unspecified must be left
empty.  (Replace each field name above with its corresponding value.)
The buffer is padded with 0 bytes to a length of 256 as needed.

The 'password' field is a hexadecimal string; all others are standard
character strings.

For example, to set the following configuration:
  host:      PRINTSRV
  printer:   LJET01
  workgroup: <none>
  userid:    mrmuffin
  password:  blueberry
  copies:    1

In REXX:
  params = 'PRINTSRV#LJET01##mrmuffin#1#626C75656265727279'
  IF LENGTH( params <= 256 ) THEN DO
      buffer = params || COPIES('00'x, 256 - LENGTH( params ))
      CALL RPUPortSet 'SMB', buffer
  END

(At least version 1.03 of SMB.PDR is required.)

