Changeset 17 for rxutilex/trunk/FUNCTIONS

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.

File:

• rxutilex/trunk/FUNCTIONS (modified) (9 diffs)

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.
+