source: rxutilex/trunk/FUNCTIONS@ 16

FUNCTIONS IN RXUTILEX.DLL

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

Sys2CheckNamedPipe          - Check the status of a 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
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
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                    -
Sys2ReplaceModule           - Unlock a DLL (DosReplaceModule wrapper)
Sys2Version                 - Get the version of this library


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

Check the status of a named pipe.

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.


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

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

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


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

REXX ARGUMENTS:
  1. The year (1970-2037)
     Years prior to 1970 or later than 2037 cannot be supported due to the
     limitations in how the C library calculates epoch time.  Specifying
     1969 or earlier will generate a REXX error.  Any date later than 2037
     will return a value of 0 (and SYS2ERR will report an error in 'mktime').
     NOTE: 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, such that values
           from 38 to 69 will result in a return value of 0.
  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.


-------------------------------------------------------------------------

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.

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.

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


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

Returns the current library version.

REXX ARGUMENTS:    None
REXX RETURN VALUE: Current version in the form "major.minor.refresh"