source: rxutilex/trunk/FUNCTIONS@ 25

FUNCTIONS IN RXUTILEX.DLL

(See file 'TODO' for functions which are under consideration to be added.)

Sys2CheckNamedPipe          - Check the status of a named pipe (server side)
Sys2Close                   - Close a file or named pipe
Sys2ConnectNamedPipe        - Enable client sessions on a named pipe
Sys2CreateNamedPipe         - Create a named pipe
Sys2DisconnectNamedPipe     - Acknowledge that a named pipe session has ended
Sys2DropFuncs               - Deregister all functions
Sys2FormatNumber            - Format a number with thousands-grouping characters
Sys2FormatTime              - Format calender time (strftime wrapper)
Sys2GetClipboardText        - Retrieve the current clipboard text
Sys2GetEpochTime            - Get or convert calender time (seconds from epoch)
Sys2KillProcess             - Kill a process by name or PID
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
Sys2QueryPhysicalMemory     - Get the amount of installed RAM
Sys2QueryProcess            - Get information about a process
Sys2QueryProcessList        - Get the list of running processes
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


If an internal error occurs in any function, the variable SYS2ERR will contain
an error message of the form "RC: description" where RC is a non-zero error
code, and description indicates the internal function call that failed.  If
no error occurs, SYS2ERR will be "0".


-------------------------------------------------------------------------
Sys2CheckNamedPipe

Checks the status of a named pipe that was previously created using
Sys2CreateNamedPipe.  

This function is designed for use by the process that created the pipe 
(i.e. the server side).  Clients which are accessing a named pipe should 
use the standard REXX STREAM and/or CHARS functions to determine the 
pipe's status.

REXX ARGUMENTS:
  1. The pipe handle (from Sys2CreateNamedPipe or DosOpen).  (REQUIRED)

REXX RETURN VALUE:
  String of the format "bytes status", where bytes is the number of bytes
  currently waiting in the pipe, and status is one of: DISCONNECTED,
  LISTENING, CONNECTED, or CLOSING.


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

Start 'listening' by allowing clients to connect to a previously-created
named pipe.

REXX ARGUMENTS:
  1. The pipe handle, as returned by Sys2CreateNamedPipe.  (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


-------------------------------------------------------------------------
Sys2CreateNamedPipe

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 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 can be destroyed using
Sys2Close.

REXX ARGUMENTS:
  1. The name of the pipe, in the form "\PIPE\something".  (REQUIRED)
  2. The size of the outbound buffer, in bytes.  (REQUIRED)
  3. The size of the inbound buffer, in bytes.  (REQUIRED)
  4. The pipe's timeout value, in milliseconds.  (DEFAULT: 3000)
  5. The number of simultaneous instances of this pipe which are allowed.
     Must be between 1 and 254, or 0 indicating no limit.  (DEFAULT: 1)
  6. Pipe blocking mode, one of:
       W = WAIT mode, read and write block waiting for data  (DEFAULT)
       N = NOWAIT mode, read and write return immediately
  7. Pipe mode, one of:
       I = Inbound pipe  (DEFAULT)
       O = Outbound pipe
       D = Duplex (inbound/outbound) pipe
  8. Privacy/inheritance flag, one of:
       0 = The pipe handle is inherited by child processes (DEFAULT)
       1 = The pipe handle is private to the current process
  9. Write-through flag, one of:
       0 = Allow delayed writes (write-behind) to remote pipes (DEFAULT)
       1 = Force immediate writes (write-through) to remote pipes

REXX RETURN VALUE:  A four-byte pipe handle.


-------------------------------------------------------------------------
Sys2DisconnectNamedPipe

Unlocks a named pipe after a client has closed its connection.

REXX ARGUMENTS:
  1. The pipe handle, as returned by Sys2CreateNamedPipe.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


-------------------------------------------------------------------------
Sys2DropFuncs

Deregisters all Sys2* REXX functions.

REXX ARGUMENTS:    None
REXX RETURN VALUE: ""


-------------------------------------------------------------------------
Sys2FormatNumber                                                         
                                                                         
Formats a number to use thousands-grouping characters.  The system values
for the current locale are used for the thousands-grouping character and
the decimal place, if any.  Note that the IBM C runtime's locale 
definitions are used; these may not correspond precisely to the system 
locales as defined in the OS/2 Locale object.

The input number may be a positive or negative integer or floating point
value.  It must be a simple, non-localized number value; in other words,
it must not contain any thousands-grouping characters, and any decimal 
point which it contains must be a period (rather than any localized 
decimal symbol).
                                                                         
REXX ARGUMENTS:                                                          
  1. Number to be formatted.                                  (REQUIRED) 
  2. Number of decimal places to use for floating point values.  
     Ignored for integer values.                            (DEFAULT: 2)
                                                                         
REXX RETURN VALUE: The formatted number, or '' on error.                 


-------------------------------------------------------------------------
Sys2FormatTime

Converts a number of seconds from the epoch (1970-01-01 0:00:00 UTC) into
a formatted date and time string. 

REXX ARGUMENTS:
  1. Number of seconds (a positive integer) to be converted.  (REQUIRED)
     This value cannot be greater than 2,147,483,647.
  2. Format type, one of:
       D = return in the form 'yyyy-mm-dd hh:mm:ss (w)' where w
           represents the weekday (0-6 where 0=Sunday) (DEFAULT)
       I = return in ISO8601 combined form 'yyyy-mm-ddThh:mm:ss[Z]'
       L = return in the form 'day month year (weekday) time' where month
           and weekday are language-dependent abbreviations
     Note: With D and I, time is returned in 24-hour format; L may vary.
  3. TZ conversion flag (indicates whether to convert to UTC from local
     time), one of:
       U = return UTC or unconverted time
       L = assume the input is in Coordinated Universal Time, and convert
           to local time using the current TZ (DEFAULT)

REXX RETURN VALUE: The formatted time string, or "" on error.


-------------------------------------------------------------------------
Sys2GetClipboardText

Retrieves a plain-text string from the clipboard if one is available.

This function requires Presentation Manager to be active, although the
REXX program itself need not be running in a PM process.

REXX ARGUMENTS:
  None.

REXX RETURN VALUE: The retrieved clipboard string


-------------------------------------------------------------------------
Sys2GetEpochTime

Converts formatted date and time into a number of seconds (UTC) from the
epoch (defined as 1970-01-01 0:00:00).  The input time is assumed to
refer to the current timezone as defined in the TZ environment variable.

If no parameters are specified, the current system time is used.  If at
least one parameter is specified, then any missing parameter is assumed
to be its minimum possible value (1 for day or month, 0 for all others).

The time is formatted according to the C runtime's locale support, as
configured via the LANG and LC_* environment variables.

NOTE: Any date prior to 1 January 1970, or later than 19 January 2038,
      cannot be supported due to the limitations in how the C library
      calculates epoch time.  Specifying any date before 1970 will generate
      a REXX error.  Any time/date later than 12:14:07 on 19 January 2038
      will return the latter value.

REXX ARGUMENTS:
  1. The year (1970-2037)
     A 2-digit year can be specified, in which case the number will be
     added to 1900 if it is 70 or higher, or to 2000 otherwise.
     e.g. '20' ==> 2020
          '75' ==> 1975
     (This is subject to the limitation noted above.)
  2. The month (1-12)
  3. The day (1-31)
  4. Hours (0-23)
  5. Minutes (0-59)
  6. Seconds (0-61)

REXX RETURN VALUE: The number of seconds since the epoch, or 0 on error.


-------------------------------------------------------------------------
Sys2KillProcess

Terminates the (first) running process with the specified executable name
or process-ID.

REXX ARGUMENTS:
  1. The process identifier (program name or process ID) (REQUIRED)
  2. Flag indicicating the identifier type:
       'P': decimal process ID
       'H': hexadecimal process ID
       'N': executable program name (with or without extension) (DEFAULT)

REXX RETURN VALUE: 1 on success or 0 on failure.


-------------------------------------------------------------------------
Sys2LoadFuncs

Registers all Sys2* REXX functions (except this one, obviously).

REXX ARGUMENTS:    None
REXX RETURN VALUE: ""


-------------------------------------------------------------------------
Sys2LocateDLL

Searches for a DLL by name and returns its fully-qualified path.

If a DLL with the given name is currently loaded, that instance of the
DLL will be returned.  Otherwise, standard DLL loading rules (according
to the current LIBPATH and/or extended LIBPATH configuration) are used to
search for a DLL whose module name matches the one specified.

REXX ARGUMENTS:
  1. The name of the DLL to search for.  (REQUIRED)


REXX RETURN VALUE:
  The fully-qualified path of the DLL, if found; "" otherwise.


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

Writes a string to the clipboard in plain-text format.  Specifying either
no value or an empty string in the first argument will simply clear the
clipboard of CF_TEXT data.

This function requires Presentation Manager to be active, although the
REXX program itself need not be running in a PM process.

REXX ARGUMENTS:
  1. String to be written to the clipboard  (DEFAULT: "")
  2. Flag indicating whether other clipboard formats should be cleared:
       Y = yes, call WinEmptyClipbrd() before writing text  (DEFAULT)
       N = no, leave (non-CF_TEXT) clipboard data untouched

REXX RETURN VALUE:  1 on success, 0 on failure


-------------------------------------------------------------------------
Sys2QueryForegroundProcess

Queries the PID of the current foreground process. (Note that this is not
necessarily the same as the process which is calling this function, which 
could, for example, be running in the background and/or as a child of the
foreground process.)

REXX ARGUMENTS: None

REXX RETURN VALUE:
  Integer representing the process ID (in decimal), or 0 if an error
  occurred.


-------------------------------------------------------------------------
Sys2QueryPhysicalMemory

Queries the amount of physical memory (RAM) installed in the system.

REXX ARGUMENTS: None

REXX RETURN VALUE:
  Integer representing the amount of installed memory, in KiB, or 0 if an
  error occurred.


-------------------------------------------------------------------------
Sys2QueryProcess

Queries information about the specified process.

Specifying a process ID of 0 will return the information for the 
current process (that is, the process calling this function); note that
this requires the second parameter to specify that the identifier is in
fact a process ID ('P' or 'H') rather than an executable name.

REXX ARGUMENTS:
  1. The process identifier (program name or process ID) (REQUIRED)
  2. Flag indicicating the identifier type:
       'P': decimal process ID
       'H': hexadecimal process ID
       'N': executable program name (with or without extension) (DEFAULT)

REXX RETURN VALUE:
  A string of the format
      pid parent-pid process-type priority cpu-time executable-name
  "priority" is in hexadecimal notation, all other numbers are decimal.
  "" is returned if the process was not found or if an internal error
  occurred.


-------------------------------------------------------------------------
Sys2QueryProcessList

Gets a list of running processes.  The results will be returned in a stem
variable, where stem.0 contains number of items, and each stem item is a
string of the form:
    pid parent-pid process-type priority cpu-time executable-name
"priority" is in hexadecimal notation, all other numbers are decimal.

Notes:
 - "process-type" will be one of:
     0 Full screen protect-mode session
     1 Requires real mode. Dos emulation.
     2 VIO windowable protect-mode session
     3 Presentation Manager protect-mode session
     4 Detached protect-mode process.
 - If "priority" is 0 then the priority class could not be determined.
 - If "executable-name" is "--" then the name could not be identified.

REXX ARGUMENTS:
  1. The name of the stem in which to return the results  (REQUIRED)

REXX RETURN VALUE: Number of processes found, or "" in case of error.


-------------------------------------------------------------------------
Sys2Read

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)

REXX RETURN VALUE:
  String containing the bytes read, or "" in case of error.


-------------------------------------------------------------------------
Sys2ReplaceModule

Unlocks and optionally replaces an in-use (locked) DLL or EXE.

REXX ARGUMENTS:
  1. The filespec of the module to be replaced.  (REQUIRED)
  2. The filespec of the new module to replace it with.  (DEFAULT: none)
  3. The filespec of the backup file to be created.  (DEFAULT: none)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


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


-------------------------------------------------------------------------
Sys2SyncBuffer                                                           

Used to synchronize buffer read/write transactions (wrapper to 
DosResetBuffer)  For external files, writes the buffer to disk. 
For named pipes, blocks until the remote client end of the pipe has read 
the contents.
                                                                         
REXX ARGUMENTS:                                                          
  1. File handle (as returned by Sys2Open or Sys2CreateNamedPipe).
     (REQUIRED)
                                                                         
REXX RETURN VALUE:  1 on success, 0 on failure

-------------------------------------------------------------------------
Sys2Version

Returns the current library version.

REXX ARGUMENTS:    None
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.