Ignore:
Timestamp:
Sep 20, 2014, 1:17:51 PM (11 years ago)
Author:
Alex Taylor
Message:

Added named-pipe and I/O functions (not yet fully tested).

File:
1 edited

Legend:

Unmodified
Added
Removed

  • rxutilex/trunk/FUNCTIONS

    r4 r16  
    33(See file 'TODO' for functions which are under consideration to be added.)
    44
     5Sys2CheckNamedPipe          - Check the status of a named pipe
     6Sys2ConnectNamedPipe        - Enable client sessions on a named pipe
     7Sys2CreateNamedPipe         - Create a named pipe
     8Sys2DisconnectNamedPipe     - Acknowledge that a named pipe session has ended
    59Sys2DropFuncs               - Deregister all functions
    610Sys2FormatTime              - Format calender time (strftime wrapper)
    … …  
    1519Sys2QueryProcess            - Get information about a process
    1620Sys2QueryProcessList        - Get the list of running processes
     21Sys2Read                    -
    1722Sys2ReplaceModule           - Unlock a DLL (DosReplaceModule wrapper)
    1823Sys2Version                 - Get the version of this library
    … …  
    2025
    2126If an internal error occurs in any function, the variable SYS2ERR will contain
    22 an error message of the form "RC: description" where RC is a non-zero error 
     27an error message of the form "RC: description" where RC is a non-zero error
    2328code, and description indicates the internal function call that failed.  If
    2429no error occurs, SYS2ERR will be "0".
     30
     31
     32-------------------------------------------------------------------------
     33Sys2CheckNamedPipe
     34
     35Check the status of a named pipe.
     36
     37REXX ARGUMENTS:
     38  1. The pipe handle (from Sys2CreateNamedPipe or DosOpen).  (REQUIRED)
     39
     40REXX RETURN VALUE:
     41  String of the format "bytes status", where bytes is the number of bytes
     42  currently waiting in the pipe, and status is one of: DISCONNECTED,
     43  LISTENING, CONNECTED, or CLOSING.
     44
     45
     46-------------------------------------------------------------------------
     47Sys2ConnectNamedPipe
     48
     49Start 'listening' by allowing clients to connect to a previously-created
     50named pipe.
     51
     52REXX ARGUMENTS:
     53  1. The pipe handle, as returned by Sys2CreateNamedPipe.  (REQUIRED)
     54
     55REXX RETURN VALUE:
     56  1 on success, or 0 if an error occurred.
     57
     58
     59-------------------------------------------------------------------------
     60Sys2CreateNamedPipe
     61
     62Creates a named pipe with the specified name and parameters.
     63
     64Note that the standard REXX functions such as CHARIN/OUT, which operate
     65directly on file names, are not capable of using the pipe handle returned
     66from this function. While the client end can use such functions after
     67using STREAM to issue an OPEN WRITE or OPEN READ command, the host end
     68needs to use the pipe handle from this function, and must therefore use
     69Sys2Read/Sys2Write in order to read and write data from the pipe.
     70
     71REXX ARGUMENTS:
     72  1. The name of the pipe, in the form "\PIPE\something".  (REQUIRED)
     73  2. The size of the outbound buffer, in bytes.  (REQUIRED)
     74  3. The size of the inbound buffer, in bytes.  (REQUIRED)
     75  4. The pipe's timeout value, in milliseconds.  (DEFAULT: 3000)
     76  5. The number of simultaneous instances of this pipe which are allowed.
     77     Must be between 1 and 254, or 0 indicating no limit.  (DEFAULT: 1)
     78  6. Pipe blocking mode, one of:
     79       W = WAIT mode, read and write block waiting for data  (DEFAULT)
     80       N = NOWAIT mode, read and write return immediately
     81  7. Pipe mode, one of:
     82       I = Inbound pipe  (DEFAULT)
     83       O = Outbound pipe
     84       D = Duplex (inbound/outbound) pipe
     85  8. Privacy/inheritance flag, one of:
     86       0 = The pipe handle is inherited by child processes (DEFAULT)
     87       1 = The pipe handle is private to the current process
     88  9. Write-through flag, one of:
     89       0 = Allow delayed writes (write-behind) to remote pipes (DEFAULT)
     90       1 = Force immediate writes (write-through) to remote pipes
     91
     92REXX RETURN VALUE:  A four-byte pipe handle.
     93
     94
     95-------------------------------------------------------------------------
     96Sys2DisconnectNamedPipe
     97
     98Unlocks a named pipe after a client has closed its connection.
     99
     100REXX ARGUMENTS:
     101  1. The pipe handle, as returned by Sys2CreateNamedPipe.      (REQUIRED)
     102
     103REXX RETURN VALUE:
     104  1 on success, or 0 if an error occurred.
    25105
    26106
    … …  
    91171     Years prior to 1970 or later than 2037 cannot be supported due to the
    92172     limitations in how the C library calculates epoch time.  Specifying
    93      1969 or earlier will generate a REXX error.  Any date later than 2037 
     173     1969 or earlier will generate a REXX error.  Any date later than 2037
    94174     will return a value of 0 (and SYS2ERR will report an error in 'mktime').
    95175     NOTE: A 2-digit year can be specified, in which case the number will be
    96            added to 1900 if it is 70 or higher, or to 2000 otherwise. 
     176           added to 1900 if it is 70 or higher, or to 2000 otherwise.
    97177           e.g. '20' ==> 2020
    98178                '75' ==> 1975
    … …  
    134214
    135215-------------------------------------------------------------------------
    136 Sys2LocateDLL                                                         
    137                                                                      
    138 Searches for a DLL by name and returns its fully-qualified path. 
     216Sys2LocateDLL
     217
     218Searches for a DLL by name and returns its fully-qualified path.
    139219
    140220If a DLL with the given name is currently loaded, that instance of the
    141221DLL will be returned.  Otherwise, standard DLL loading rules (according
    142222to the current LIBPATH and/or extended LIBPATH configuration) are used to
    143 search for a DLL whose module name matches the one specified. 
    144                                                                      
    145 REXX ARGUMENTS:                                                       
    146   1. The name of the DLL to search for.  (REQUIRED)                   
    147 
    148                                                                      
    149 REXX RETURN VALUE:                                                   
    150   The fully-qualified path of the DLL, if found; "" otherwise. 
     223search for a DLL whose module name matches the one specified.
     224
     225REXX ARGUMENTS:
     226  1. The name of the DLL to search for.  (REQUIRED)
     227
     228
     229REXX RETURN VALUE:
     230  The fully-qualified path of the DLL, if found; "" otherwise.
    151231
    152232
    … …  
    219299
    220300Gets a list of running processes.  The results will be returned in a stem
    221 variable, where stem.0 contains number of items, and each stem item is a 
     301variable, where stem.0 contains number of items, and each stem item is a
    222302string of the form:
    223303    pid parent-pid process-type priority cpu-time executable-name
    … …  
    241321
    242322-------------------------------------------------------------------------
     323Sys2Read
     324
     325Read bytes from a previously-opened stream (wrapper to DosRead).  The
     326format of file handles supported by this function is currently limited
     327to those returned by Sys2CreateNamedPipe.
     328
     329REXX ARGUMENTS:
     330  1. File handle (as returned by Sys2CreateNamedPipe).  (REQUIRED)
     331  2. Number of bytes to read.  (REQUIRED)
     332
     333REXX RETURN VALUE:
     334  String containing the bytes read, or "" in case of error.
     335
     336
     337-------------------------------------------------------------------------
    243338Sys2ReplaceModule
    244339
Note: See TracChangeset for help on using the changeset viewer.