Changeset 17

Timestamp:

Sep 21, 2014, 8:45:02 AM (11 years ago)

Author:

Alex Taylor

Message:

More work on named-pipe and I/O functions. Added some test cases for the new functionality. Updated documentation.

Location:

rxutilex/trunk

Files:

• FUNCTIONS (modified) (9 diffs)
• TODO (modified) (1 diff)
• npcli_r.cmd (added)
• npcli_w.cmd (added)
• npsrv_r.cmd (added)
• npsrv_w.cmd (added)
• readme.txt (modified) (2 diffs)
• rxutilex.c (modified) (6 diffs)
• rxutilex.def (modified) (1 diff)
• test1 (added)
• test2 (added)
• testio.cmd (added)
• testlib.cmd (modified) (1 diff)

rxutilex/trunk/FUNCTIONS

@@ -4 +4 @@
 
 Sys2CheckNamedPipe          - Check the status of a named pipe
+Sys2Close                   - Close a file or named pipe
 Sys2ConnectNamedPipe        - Enable client sessions on a named pipe
 Sys2CreateNamedPipe         - Create a named pipe
@@ -14 +15 @@
 Sys2LoadFuncs               - Register all functions
 Sys2LocateDLL               - Search for a loaded/loadable DLL
+Sys2Open                    - Open a file or stream (with >2GB support)
 Sys2PutClipboardText        - Copy a text string to the clipboard
 Sys2QueryForegroundProcess  - Get the PID of the current foreground process
@@ -19 +21 @@
 Sys2QueryProcess            - Get information about a process
 Sys2QueryProcessList        - Get the list of running processes
-Sys2Read                    -
+Sys2Read                    - Read bytes from a file or named pipe
 Sys2ReplaceModule           - Unlock a DLL (DosReplaceModule wrapper)
+Sys2Seek                    - Set file read/write pointer (with >2GB support)
 Sys2Version                 - Get the version of this library
+Sys2Write                   - Write bytes to a file or named pipe
 
 
@@ -45 +49 @@
 
 -------------------------------------------------------------------------
+Sys2Close
+
+Close a file or stream (wrapper to DosClose).
+
+REXX ARGUMENTS:
+  1. File handle (returned by Sys2Open).  (REQUIRED)
+
+REXX RETURN VALUE:
+  1 on success, or 0 if an error occurred.
+
+
+-------------------------------------------------------------------------
 Sys2ConnectNamedPipe
 
@@ -60 +76 @@
 Sys2CreateNamedPipe
 
-Creates a named pipe with the specified name and parameters.
+Creates a named pipe with the specified name and parameters.  Only byte
+mode is supported; message mode is not.
 
 Note that the standard REXX functions such as CHARIN/OUT, which operate
 directly on file names, are not capable of using the pipe handle returned
 from this function. While the client end can use such functions after
-using STREAM to issue an OPEN WRITE or OPEN READ command, the host end
+using STREAM to issue an OPEN WRITE or OPEN READ command, the server end
 needs to use the pipe handle from this function, and must therefore use
 Sys2Read/Sys2Write in order to read and write data from the pipe.
+
+Named pipes can be created in inbound-only, outbound-only, or duplex
+(inbound/outbound) mode.  An error will result if attempting to write
+to an inbound-only pipe, or read from an outbound-only pipe.
+
+To activate a named pipe so that client processes can connect to it, use
+Sys2ConnectNamedPipe.  To check the pipe's connection status, as well as
+the amount of data currently in the pipe, use Sys2CheckNamedPipe.  To
+unlock a named pipe after a client has closed the connection, use
+Sys2DisconnectNamedPipe.  Finally, the pipe should be destroyed using
+Sys2Close when no longer needed.
 
 REXX ARGUMENTS:
@@ -232 +260 @@
 
 -------------------------------------------------------------------------
-
+Sys2Open
+
+Opens a file or other stream; files larger than 2GB are supported (this
+function is a wrapper to DosOpenL).  Direct-DASD mode is not supported by
+this function, nor is setting the initial extended attributes.
+
+REXX ARGUMENTS:
+  1. Name of file or stream to open.                           (REQUIRED)
+  2. Open action flags, must be either "O" (open if exists), "R" (replace
+     if exists), or nothing (fail if exists), optionally followed by "C"
+     (create if file does not exist).  If "C" is not specified, the
+     operation will fail if the file does not exist.  Note that a value
+     of "" alone will therefore fail automatically.        (DEFAULT: "O")
+     In summary, the possible combinations are:
+       O = Open only (if file exists, open it; if not, fail)
+       OC= Open/create (if file exists, open it; if not, create it)
+       R = Replace only (if file exists, replace it; if not, fail)
+       RC= Replace/create (if file exists, replace it; if not, create it)
+       C = Create only (if file exists, fail; if not, create it)
+       (empty) = No-op (if file exists, fail; if not, fail)
+  3. Access mode flags, one or both of:                   (DEFAULT: "RW")
+       R = Open file with read access.
+       W = Open file with write access.
+  4. Sharing mode flags, any combination of:               (DEFAULT: "W")
+       R = Deny read access to other processes
+       W = Deny write access to other processes
+  5. Deny legacy DosOpen access, one of:
+       0 = Allow DosOpen to access the file                     (DEFAULT)
+       1 = Deny access using the DosOpen API
+  6. Privacy/inheritance flag, one of:
+       0 = The file handle is inherited by child processes.     (DEFAULT)
+       1 = The file handle is private to the current process.
+  7. Initial file attributes when creating a file:          (DEFAULT: "")
+       A = Archive attribute set
+       D = Directory attribute set
+       S = System attribute set
+       H = Hidden attribute set
+       R = Read-only attribute set
+  8. Initial file size when creating or replacing a file; ignored if
+     access mode is read-only.                               (DEFAULT: 0)
+  9. I/O mode flags, any or all of:                         (DEFAULT: "")
+      T = Write-through mode (default is normal write)
+      N = No-cache mode (default is to use filesystem cache)
+      S = Sequential access
+      R = Random access
+         * S and R can combine as follows:
+             Neither: No locality known (default)
+             S only:  Mainly sequential access
+             R only:  Mainly random access
+             Both:    Random/sequential (i.e. random with some locality)
+
+REXX RETURN VALUE:
+  File handle, or "" in case of error.
+
+
+-------------------------------------------------------------------------
 Sys2PutClipboardText
 
@@ -323 +406 @@
 Sys2Read
 
-Read bytes from a previously-opened stream (wrapper to DosRead).  The
-format of file handles supported by this function is currently limited
-to those returned by Sys2CreateNamedPipe.
-
-REXX ARGUMENTS:
-  1. File handle (as returned by Sys2CreateNamedPipe).  (REQUIRED)
+Read bytes from a previously-opened stream (wrapper to DosRead).
+
+REXX ARGUMENTS:
+  1. File handle (as returned by Sys2Open or Sys2CreateNamedPipe).
+     (REQUIRED)
   2. Number of bytes to read.  (REQUIRED)
 
@@ -350 +432 @@
 
 -------------------------------------------------------------------------
+Sys2Seek
+
+Move the read/write pointer to the specified location in an open
+file/stream; files larger than 2GB are supported (this function is a
+wrapper to DosSetFilePtrL).
+
+REXX ARGUMENTS:
+  1. File handle (returned by Sys2Open).  (REQUIRED)
+  2. The signed distance in bytes to move.  (REQUIRED)
+  3. Move method, one of:
+       B = Beginning of file
+       C = Current position (DEFAULT)
+       E = End of file
+
+REXX RETURN VALUE:
+  The new file position, in bytes.
+
+
+-------------------------------------------------------------------------
 Sys2Version
 
@@ -357 +458 @@
 REXX RETURN VALUE: Current version in the form "major.minor.refresh"
 
+
+-------------------------------------------------------------------------
+Sys2Write
+
+Write bytes to a previously-opened stream (wrapper to DosWrite).
+
+REXX ARGUMENTS:
+  1. File handle (as returned by Sys2Open or Sys2CreateNamedPipe).
+     (REQUIRED)
+  2. Data to be written.  (REQUIRED)
+
+REXX RETURN VALUE:
+  The number of bytes successfully written.
+

rxutilex/trunk/TODO

@@ -2 +2 @@
 
  * Sys2ReplaceModule - A wrapper for DosReplaceModule()
+ * Named pipe management functions
+ * Open/Close/Seek/Read/Write functions with large file support
  - Sys2TokenizeString - A string tokenizer
  - Sys2FormatNumber - Format a number according to locale
  - Sys2FormatCurrency - A strfmon wrapper
  - Sys2GetResource - DosGetResource wrapper
- - Sys2PrintFile - Print a file to a port or queue
  - Sys2IsDirectory - Determine if filespec is a directory
 
 Under consideration:
- - BLDLEVEL parser
+ - Sys2PrintFile - Print a file to a port or queue
+ - Sys2StemSort - Sort the values in an array stem
  - SYSLEVEL parser
- - Functions to open/read/write Large files
- ? Named pipe creation/deletion?
+ - BLDLEVEL parser                  <-- exists in rxunlock
  ? Install a font
- ? Create a printer port
- ? Create a printer queue
- ? Install a printer "driver.device"
  ? Sys2IncFileName: find the next available filename according to a pattern
      (e.g. CONFIG.001, log_0004.txt, etc.)
+ ? Create a printer port              <-- in rxprtutil
+ ? Create a printer queue             <-- in rxprtutil
+ ? Install a printer "driver.device"  <-- in rxprtutil
  ? Access to the Win32 registry     <-- exists in sp1utils
  ? Sys2CloseWindow & Sys2ExitWindow <-- exists in pr1util

rxutilex/trunk/readme.txt

@@ +1 @@
+REXX Utility Functions - Extended (RXUTILEX.DLL)
+http://trac.netlabs.org/rexxlibs/
+
 OBJECTIVE
 
 The purpose behind the RXUTILEX library is that it should basically provide
-everything that _should_ have been in RexxUtil, but isn't.  Specifically, 
+everything that _should_ have been in RexxUtil, but isn't.  Specifically,
 useful system-related functions of a relatively general-purpose nature,
 as well as commonly-needed data formatting routines.
- 
-This includes things like 
+
+This includes things like
 (* = already at least partially implemented):
  - clipboard access *
@@ -12 +15 @@
  - system information (like installed RAM*)
  - locked-file replacement *
- - wrappers for strftime()*, mktime()*, and strfmon() 
+ - wrappers for strftime()*, mktime()*, and strfmon()
+ - named pipe creation/deletion *
+ - functions to read/write huge (>2GB) files *
  - a string tokenizer
- - named pipe creation/deletion
  - access to resources (DosGetResource)
- - functions to read/write huge (>2GB) files 
 and other things that the community decides is needed.
- 
-While it is true that many of these functions already exist in a scattering of 
-other REXX libraries, many of those other libraries are no longer maintained 
-and/or are closed-source, and cannot be updated by the community.  Others are 
+
+While it is true that many of these functions already exist in a scattering of
+other REXX libraries, many of those other libraries are no longer maintained
+and/or are closed-source, and cannot be updated by the community.  Others are
 relatively special-purpose, and only include one or two general-utility
 functions.
- 
-One of the main motivations of this project is to try and reduce "Yet Another 
-REXX Library" syndrome - where a REXX application requires a myriad of different
-REXX DLLs purely for the same of one or two useful functions in each one.  It 
-would be nice if most of the commonly-required functions were available in a 
-single library.  Moreover, that library should be open source and maintained by
-the OS/2 community, able to be updated and extended as needed.
- 
-On the other hand, it is also important to avoid overloading RXUTILEX with too
-many functions.  RXUTILEX should ideally be limited to providing functions which
-are generally useful for a wide variety of applications.  (There will always be 
-relatively specialized areas of support which SHOULD have their own dedicated 
-REXX libraries - RXLVM and RXULS are obvious examples.)
- 
- 
+
+One of the main motivations of this project is to try and reduce "Yet Another
+REXX Library" syndrome - wherein a REXX application requires a myriad of REXX
+DLLs purely for the sake of one or two useful functions in each one.  It would
+be nice if most of the commonly-required functions were available in a single
+library.  Moreover, that library should be open source and maintained by the
+OS/2 community, able to be updated and extended as needed.
+
+On the other hand, it is also desirable to avoid overloading RXUTILEX with too
+many functions.  RXUTILEX should be limited to providing functions which are
+generally useful for a wide variety of applications.  (There will always be
+relatively specialized areas of support which should continue to have their
+own dedicated REXX libraries - RXLVM, for example.)
+
+
+BUILD NOTES
+
+The included Makefile is for the IBM C/C++ compiler.  Version 3.6 or later
+is required in order to support the parsing of 64-bit integers.
+
+
 TERMS OF USE
 
-Once the logistics are worked out, the source code for RXUTILEX will become
-available via SVN under a non-restrictive open source license (which is still
-to be determined).
+  REXX Utility Functions - Extended (RXUTILEX)
+  (C) 2011, 2014 Alex Taylor.
 
-Until then, this binary-only preview release of RXUTILEX may be used freely and 
-with no restrictions.  
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are
+  met:
 
-This release of RXUTILEX has no warranty, and is not guaranteed to work as
-advertised or to be fit for any purpose whatsoever.
+  1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  3. The name of the author may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
+  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+  POSSIBILITY OF SUCH DAMAGE.
+
+The source code for RXUTILEX is available via SVN at
+http://svn.netlabs.org/repos/rexxlibs/rxutilex/
+

rxutilex/trunk/rxutilex.c

@@ -1713 +1713 @@
  * Sys2Close                                                                 *
  *                                                                           *
- * Wrapper to DosWrite: write bytes to a previously-opened stream.           *
+ * Wrapper to DosClose: close a file/stream.                                 *
  *                                                                           *
  * REXX ARGUMENTS:                                                           *
@@ -1791 +1791 @@
         strupr( argv[2].strptr );
         if ( strcspn(argv[2].strptr, "BCE") > 0 ) return ( 40 );
-        switch ( argv[1].strptr[0] ) {
+        switch ( argv[2].strptr[0] ) {
             case 'B': ulMethod = FILE_BEGIN;   break;
             case 'E': ulMethod = FILE_END;     break;
@@ -1874 +1874 @@
  *                                                                           *
  * REXX RETURN VALUE:                                                        *
- *   1 on success, or 0 if an error occurred.                                *
+ *   Number of bytes written.                                                *
  * ------------------------------------------------------------------------- */
 ULONG APIENTRY Sys2Write( PSZ pszName, ULONG argc, RXSTRING argv[], PSZ pszQueue, PRXSTRING prsResult )
@@ -1880 +1880 @@
     HFILE  hf;
     ULONG  cbActual;
+    CHAR   szActual[ US_INTEGER_MAXZ ];
     APIRET rc;
 
@@ -1894 +1895 @@
     // (Second argument can be left in standard RXSTRING form)
 
-    rc = DosWrite( hf, argv[0].strptr, argv[0].strlength, &cbActual );
+    rc = DosWrite( hf, argv[1].strptr, argv[1].strlength, &cbActual );
     if ( rc != NO_ERROR ) {
         WriteErrorCode( rc, "DosWrite");
         MAKERXSTRING( *prsResult, "0", 1 );
-    }
-    else {
-        MAKERXSTRING( *prsResult, "1", 1 );
-    }
-
+        return ( 0 );
+    }
+
+    sprintf( szActual, "%d", cbActual );
+    MAKERXSTRING( *prsResult, szActual, strlen( szActual ));
     return ( 0 );
 }
@@ -2182 +2183 @@
 
     if ( pszContext == NULL )
-        sprintf( szErrorText, "%X", ulError );
+        sprintf( szErrorText, "%u", ulError );
     else
-        sprintf( szErrorText, "%X: %s", ulError, pszContext );
+        sprintf( szErrorText, "%u: %s", ulError, pszContext );
     MAKERXSTRING( shvVar.shvname,  SZ_ERROR_NAME, strlen(SZ_ERROR_NAME) );
     MAKERXSTRING( shvVar.shvvalue, szErrorText,   strlen(szErrorText) );

rxutilex/trunk/rxutilex.def

@@ -1 +1 @@
 LIBRARY     RXUTILEX INITINSTANCE TERMINSTANCE
 DATA        MULTIPLE NONSHARED
-DESCRIPTION '@#Alex Taylor:0.0.5#@##1## 20 Sep 2014 20:12:24     REINFORCE::::::@@Extra REXX Utility Functions'
+DESCRIPTION '@#Alex Taylor:0.0.5#@##1## 21 Sep 2014 15:39:46     REINFORCE::::::@@Extra REXX Utility Functions'
 
 EXPORTS     Sys2LoadFuncs

rxutilex/trunk/testlib.cmd

@@ -35 +35 @@
 say Sys2LocateDLL('ehxdlmri')
 
-hp = Sys2CreateNamedPipe("\PIPE\RNPTEST", 0, 100 )
-if hp == "" then say SYS2ERR
-else do
-    ok = Sys2ConnectNamedPipe( hp )
-    if ok == 0 then say SYS2ERR
-    else do
-        PARSE VALUE Sys2CheckNamedPipe( hp ) WITH _cb _state
-        say _cb 'bytes waiting'
-        /*data = Sys2Read( hp, _cb )*/
-        data = charin("\PIPE\RNPTEST",, _cb)
-        say 'Data: "'c2x(data)'"'
-    end
-    ok = Sys2DisconnectNamedPipe( hp )
-    if ok == 0 then say SYS2ERR
-end
-
 call Sys2DropFuncs
 return 0