Changeset 13 for rxprtutl

Timestamp:

May 2, 2013, 3:35:06 PM (12 years ago)

Author:

Alex Taylor

Message:

Added RPUPortQuery function, improved discussion of port driver settings in 'notes'.

Location:

rxprtutl/trunk

Files:

• notes (modified) (4 diffs)
• rxprtutl.c (modified) (13 diffs)
• rxprtutl.def (modified) (2 diffs)
• testlib.cmd (modified) (1 diff)

rxprtutl/trunk/notes

@@ -1 @@
-USING RPUPortSet
+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 )))
+
+
+SERIAL.PDR, PARALLEL.PDR
+------------------------
 
 The standard serial and parallel port drivers do not support the SplPdSet API.
 
-The PAR1284 port driver takes a data structure with the following format:
 
+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                        */
@@ -74 +102 @@
    ULONG   ulpszDeviceID;       /* -> 1284 deviceID for printer on port  */
 } PORTSETTINGS, *PPORTSETTINGS;
-#define PAR12_SIGNATURE
 
+/* 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
@@ -84 +136 @@
 } PPTIMEOUTCHANNEL, *PPPTIMEOUTCHANNEL;
 
+(Refer to the header file wpshell\src\wpsh\par1284\pdrtypes.h from the IBM
+DDK for more information.)
 
 
+CUPS.PDR
+--------
 
-Port settings structure for CUPS.PDR:
+The eCups port driver (CUPS.PDR) uses the following port settings structure:
 
 typedef struct _PORTSETTINGS {
@@ -94 +150 @@
 } PORTSETTINGS, *PPORTSETTINGS;
 
+(At least version 1.04 of CUPS.PDR is required.)
 
 
-Port setting structure for SMB.PDR:
+SMB.PDR
+-------
 
-/* szPortData contains all of the port parameters in a single buffer:  */
-/*   host                                                              */
-/*   printer                                                           */
-/*   workgroup                                                         */
-/*   userid                                                            */
-/*   copies                                                            */
-/*   password                                                          */
-/* All except 'password' are verbatim character strings; 'password' is */
-/* a hexadecimal string.  Fields are separated by '#'.  All fields are */
-/* required; those with unspecified values are left empty.             */
+The Samba port driver (SMB.PDR) takes a single 256-byte buffer.  This
+buffer must take the following format:
 
-typedef struct _PORTSETTINGS {
-    CHAR  szPortData[ 256 ];
-} PORTSETTINGS, *PPORTSETTINGS;
+    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
+

rxprtutl/trunk/rxprtutl.c

@@ -60 +60 @@
 #define SZ_LIBRARY_NAME         "RXPRTUTL"  // Name of this library
 #define SZ_ERROR_NAME           "RPUERROR"  // REXX variable used to store error codes
-#define SZ_VERSION              "0.2.1"     // Current version of this library
+#define SZ_VERSION              "0.2.2"     // Current version of this library
 
 #define APPNAME_LEAD_STR        "PM_"
@@ -73 +73 @@
 
 // Values that should be defined in pmsplb.h if it actually existed
+#define TYPE_SHORT_WAIT         1
 #define TYPE_LONG_WAIT          2
 #define BIDI_SET_PORTDRV        0x19
+#define BIDI_Q_PORTDRV          0x8019
 
 // Values used by WinOpenObject
@@ -131 +133 @@
     "RPUPortDialog",
     "RPUPortInstall",
+    "RPUPortQuery",
     "RPUPortSet",
     "RPUPrinterCreate",
@@ -153 +156 @@
 RexxFunctionHandler RPUPortDialog;
 RexxFunctionHandler RPUPortInstall;
+RexxFunctionHandler RPUPortQuery;
 RexxFunctionHandler RPUPortSet;
 RexxFunctionHandler RPUPrinterCreate;
@@ -168 +172 @@
 ULONG   UniqueDeviceName( PSZ pszName );
 BOOL    WriteCompoundVariable( PSZ pszStem, PSZ pszTail, PSZ pszValue );
+BOOL    WriteSimpleVariable( PSZ pszName, PSZ pszValue );
 BOOL    WriteStemElement( PSZ pszStem, ULONG ulIndex, PSZ pszValue );
 void    WriteErrorCode( ULONG ulError, PSZ pszContext );
@@ -523 +528 @@
     PSZ          pszToken;
     HOBJECT      hObj;                  // printer WPS object handle
+
+    /* Note: SPL_PR_LOCAL_ONLY apparently doesn't prevent SplEnumPrinter from
+     *       including remote printers, it only stops it from probing them
+     *       to query the remote queue information in addition to the local
+     *       queue.  Specifying it here prevents a 'stall' when the remote
+     *       host is offline or unavailable.
+     */
     ULONG        flType     = SPL_PR_QUEUE | SPL_PR_DIRECT_DEVICE | SPL_PR_LOCAL_ONLY,
                  cbBuf      = 0,
@@ -620 +632 @@
              * of the print device(s) connected to it.
              */
-
-#if 0
-            if ( pPInfo->pszComputerName ) {
-                /* Network printer.  Just display the local information and
-                 * don't try to query the remote queue.
-                 */
-                sprintf( szStemNode, "%s.%u", szStem, ++ulCount );
-                WriteCompoundVariable( szStemNode, "!name",
-                                       pPInfo->pszPrintDestinationName );
-                WriteCompoundVariable( szStemNode, "!description",
-                                       pPInfo->pszDescription );
-                WriteCompoundVariable( szStemNode, "!queue",
-                                       pPInfo->pszPrintDestinationName);
-                WriteCompoundVariable( szStemNode, "!flags", "");
-                WriteCompoundVariable( szStemNode, "!handle", "");
-                WriteCompoundVariable( szStemNode, "!host",
-                                       pPInfo->pszComputerName );
-                continue;
-            }
-#endif
-
             rc = SplQueryQueue( pPInfo->pszComputerName,
                                 pPInfo->pszPrintDestinationName,
@@ -787 +778 @@
  *      installed and registered in OS2.INI already.         (REQUIRED)      *
  *   2. The name of the new port to be created.  If not specified, the port  *
- *      driver will be responsible for using a default name. (DEFAULT: none) *
+ *      driver will be responsible for using a default name.  This should    *
+ *      generally be specified, as the driver is not guaranteed to support   *
+ *      omitting it.                                         (DEFAULT: none) *
  *                                                                           *
  * REXX RETURN VALUE:                                                        *
@@ -857 +850 @@
         WriteErrorCode( rc, "SplPdInstallPort");
         MAKERXSTRING( *prsResult, "0", 1 );
+    }
+
+finish:
+    DosFreeModule( hPdr );
+cleanup:
+    WinTerminate( hab );
+    return ( 0 );
+}
+
+
+/* ------------------------------------------------------------------------- *
+ * RPUPortQuery                                                              *
+ *                                                                           *
+ * Queries the specified port's configuration settings.  IMPORTANT: not all  *
+ * port drivers support this; the standard OS/2 serial and parallel port     *
+ * drivers do NOT.  When this API is not supported, the return value should  *
+ * be ''.  Otherwise, the format of the returned configuration data is a     *
+ * string of binary data in port driver-specific format (the caller assumes  *
+ * responsibility for knowing how to interpret it).                          *
+ *                                                                           *
+ * REXX ARGUMENTS:                                                           *
+ *   1. The name of the port driver without any extension.  This must be     *
+ *      installed and registered in OS2.INI already.              (REQUIRED) *
+ *   2. The name of the port to be queried.                       (REQUIRED) *
+ *                                                                           *
+ * REXX RETURN VALUE:                                                        *
+ *   Binary data representing the port configuration, in whatever format is  *
+ *   returned by the driver's SplPdQuery->BIDI_Q_PORTDRV routine.  This      *
+ *   depends on the particular port driver; consult its API documentation.   *
+ *   '' will be returned if an error occurred.                               *
+ * ------------------------------------------------------------------------- */
+ULONG APIENTRY RPUPortQuery( PSZ pszName, ULONG argc, RXSTRING argv[], PSZ pszQueue, PRXSTRING prsResult )
+{
+    HAB     hab;                        // desktop anchor-block handle
+    HMODULE hPdr = NULLHANDLE;          // handle to port driver module
+    PFN     pfnQueryPort;               // pointer to driver's SplPdSet entrypoint
+    ULONG   ulCB,                       // return value from PrfQueryProfileString()
+            cBuf;                       // size of configuration buffer
+    PSZ     pszPdrName  = NULL,         // name of the specified port driver
+            pszPortName = NULL;         // name of the new port to create
+    CHAR    szPathName[ CCHMAXPATH+1 ]; // FQN of the port driver module
+    PBYTE   pBuf;                       // Pointer to configuration buffer
+    APIRET  rc = 0;                     // return code from Dos...() functions
+
+
+    // Reset the error indicator
+    WriteErrorCode( 0, NULL );
+
+    // Make sure we have exactly two valid arguments
+    if ( argc != 2 ||
+         !RXVALIDSTRING( argv[0] ) ||
+         !RXVALIDSTRING( argv[1] ))
+        return ( 40 );
+    pszPdrName  = strupr( argv[0].strptr );
+    pszPortName = strupr( argv[1].strptr );
+
+    // Get the path to the installed port driver
+    hab = WinInitialize( 0 );
+    if ( !hab ) {
+        WriteErrorCode( 0, "WinInitialize");
+        MAKERXSTRING( *prsResult, "", 0 );
+        return ( 0 );
+    }
+
+    ulCB = PrfQueryProfileString( HINI_SYSTEMPROFILE, APPNAME_PM_PORT_DRIVER,
+                                  pszPdrName, NULL, (PVOID) szPathName, CCHMAXPATH );
+    if ( !ulCB ) {
+        WriteErrorCode( ERRORIDERROR( WinGetLastError( hab )), "PrfQueryProfileString");
+        MAKERXSTRING( *prsResult, "", 0 );
+        goto cleanup;
+    }
+
+    // Load the port driver DLL and register its query routine
+    rc = DosLoadModule( NULL, 0, szPathName, &hPdr );
+    if ( rc != NO_ERROR || !hPdr ) {
+        WriteErrorCode( rc, "DosLoadModule");
+        MAKERXSTRING( *prsResult, "", 0 );
+        goto cleanup;
+    }
+    rc = DosQueryProcAddr( hPdr, 0, "SPLPDQUERY", &pfnQueryPort );
+    if ( rc != NO_ERROR ) {
+        WriteErrorCode( rc, "DosQueryProcAddr");
+        MAKERXSTRING( *prsResult, "", 0 );
+        goto finish;
+    }
+
+    // Now get the port configuration
+    rc = pfnQueryPort( pszPortName, TYPE_SHORT_WAIT, BIDI_Q_PORTDRV, NULL, 0, NULL, &cBuf );
+    if ( cBuf && ( rc == NO_ERROR ) ||
+                 ( rc == ERROR_MORE_DATA ) || ( rc == NERR_BufTooSmall ))
+    {
+        pBuf = (PBYTE) malloc( cBuf );
+        if ( pBuf ) {
+            rc = pfnQueryPort( pszPortName, TYPE_SHORT_WAIT, BIDI_Q_PORTDRV, NULL, 0, pBuf, &cBuf );
+            if ( rc == NO_ERROR ) {
+                // Write the data contents to our return RXSTRING
+                if ( !SaveResultString( prsResult, pBuf, cBuf ))
+                    MAKERXSTRING( *prsResult, "", 0 );
+            }
+            else {
+                WriteErrorCode( rc, "SplPdQuery 2");
+                MAKERXSTRING( *prsResult, "", 0 );
+            }
+            free( pBuf );
+        }
+        else {
+            WriteErrorCode( ERROR_NOT_ENOUGH_MEMORY, "malloc");
+            MAKERXSTRING( *prsResult, "", 0 );
+        }
+    }
+    else {
+        WriteErrorCode( rc, "SplPdQuery 1");
+        MAKERXSTRING( *prsResult, "", 0 );
     }
 
@@ -924 +1030 @@
          !RXVALIDSTRING( argv[2] )  )
         return ( 40 );
-    pszPdrName  = argv[0].strptr;
+    pszPdrName  = strupr( argv[0].strptr );
     pszPortName = strupr( argv[1].strptr );
     pBuf        = argv[2].strptr;
@@ -1014 +1120 @@
          !RXVALIDSTRING( argv[1] )  )
         return ( 40 );
-    pszPdrName  = argv[0].strptr;
+    pszPdrName  = strupr( argv[0].strptr );
     pszPortName = strupr( argv[1].strptr );
 
@@ -1262 +1368 @@
 
     // Try and destroy the WPS object
+    //  - NB This causes a long delay when deleting an offline LAN printer
     if ( hObj != NULLHANDLE ) WinDestroyObject( hObj );
 
@@ -1877 +1984 @@
 
 /* ------------------------------------------------------------------------- *
+ * WriteSimpleVariable                                                       *
+ *                                                                           *
+ * Creates a variable in the calling REXX program using the REXX shared      *
+ * variable pool interface.                                                  *
+ *                                                                           *
+ * ARGUMENTS:                                                                *
+ *   PSZ pszName  : The name of the variable to write.                       *
+ *   PSZ pszValue : The value to write to the variable.                      *
+ *                                                                           *
+ * RETURNS: BOOL                                                             *
+ * ------------------------------------------------------------------------- */
+BOOL WriteSimpleVariable( PSZ pszName, PSZ pszValue )
+{
+    SHVBLOCK shvVar;                   // REXX shared variable pool block
+    ULONG    ulRc;
+    CHAR     szText[ US_COMPOUND_MAXZ ];
+
+    strncpy( szText, pszValue, US_COMPOUND_MAXZ-1 );
+    MAKERXSTRING( shvVar.shvname,  pszName, strlen(pszName) );
+    MAKERXSTRING( shvVar.shvvalue, szText,  strlen(szText) );
+    shvVar.shvnamelen  = RXSTRLEN( shvVar.shvname );
+    shvVar.shvvaluelen = RXSTRLEN( shvVar.shvvalue );
+    shvVar.shvcode     = RXSHV_SYSET;
+    shvVar.shvnext     = NULL;
+    ulRc = RexxVariablePool( &shvVar );
+    if ( ulRc > 1 ) {
+        WriteErrorCode( shvVar.shvret, "RexxVariablePool (SHVBLOCK.shvret)");
+        return FALSE;
+    }
+    return TRUE;
+}
+
+
+/* ------------------------------------------------------------------------- *
  * WriteErrorCode                                                            *
  *                                                                           *

rxprtutl/trunk/rxprtutl.def

@@ -1 +1 @@
 LIBRARY     RXPRTUTL INITINSTANCE TERMINSTANCE
 DATA        MULTIPLE NONSHARED
-DESCRIPTION '@#Alex Taylor:0.2.1#@##1## 21 Apr 2013 18:10:57     REINFORCE::::::@@REXX Printer Management Utilities'
+DESCRIPTION '@#Alex Taylor:0.2.2#@##1## 1 May 2013 18:18:54      REINFORCE::::::@@REXX Printer Management Utilities'
 
 EXPORTS     RPULoadFuncs
@@ -13 +13 @@
 RPUPortDialog
 RPUPortInstall
+RPUPortQuery
 RPUPortSet
 RPUOpenView

rxprtutl/trunk/testlib.cmd

@@ -14 +14 @@
     ELSE DO
         SAY devs.0 'devices supported by' test_driver'.DRV'
-    /*
+/*
         DO i = 1 TO devs.0
             SAY ' -' devs.i
         END
-    */
+*/
     END
     SAY