REXXLibs (REXX Libraries)

REXX Utility Functions - Extended (RXUTILEX.DLL) http://trac.netlabs.org/rexxlibs/ This library requires OS/2 4.5x, as it makes use of large file support functions (e.g. DosOpenL). OBJECTIVE The purpose behind the RXUTILEX library is that it should basically provide 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 (* = already at least partially implemented): - clipboard access * - process management * - system information (like installed RAM*) - locked-file replacement * - wrappers for strftime()*, mktime()*, and strfmon() - named pipe creation/deletion * - functions to read/write huge (>2GB) files * - a string tokenizer - access to resources (DosGetResource) 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 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 - 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.65 is required in order to support the parsing of 64-bit integers. TERMS OF USE REXX Utility Functions - Extended (RXUTILEX) (C) 2011, 2017 Alex Taylor. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 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/ FUNCTIONS IN RXUTILEX.DLL Sys2BytesRemaining - Get the number of bytes remaining in a file 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 Sys2QueryDriveInfo - Get non-filesystem-dependent info about a drive 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 Sys2ReadLine - Read a line of text from a file or named pipe Sys2ReplaceModule - Unlock a DLL (DosReplaceModule wrapper) Sys2Seek - Set file read/write pointer (with >2GB support) Sys2SyncBuffer - synchronize read/write (DosResetBuffer wrapper) 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". ------------------------------------------------------------------------- Sys2BytesRemaining Return the number bytes that remain in a stream following the current read/write position. REXX ARGUMENTS: 1. File handle (returned by Sys2Open or Sys2CreateNamedPipe) (REQUIRED) REXX RETURN VALUE: The number of bytes remaining. In case of error, 0 will be returned and SYS2ERR will be set. ------------------------------------------------------------------------- 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 Sys2Open). (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, unless 'L' is specified in the second parameter, standard DLL loading rules (which will be governed by the current LIBPATH and/or extended LIBPATH configuration) are used to search for a loadable DLL whose module name matches the one specified. (A loadable DLL is one whose runtime dependencies are also loadable, and whose initialization routine can be executed successfully.) REXX ARGUMENTS: 1. The name of the DLL to search for. (REQUIRED) 2. Flag to limit search context, must be one of: A : 'All', search for both loaded and loadable DLLs (DEFAULT) L : 'Loaded', search only for currently-loaded DLLs 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 (or "") of: (DEFAULT: "") R = Deny read access to other processes W = Deny write access to other processes Specifying "" will permit both read and write access. 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 ------------------------------------------------------------------------- Sys2QueryDriveInfo Get non-filesystem-dependent information about a logical drive (volume). REXX ARGUMENTS: 1. Drive/volume letter to query, trailing colon optional. (REQUIRED) REXX RETURN VALUE: On success, returns a string in the format <drive> <size> <type> <flag> where <drive> is the uppercase drive letter followed by a colon, <size> is the total size of the drive/volume in binary kilobytes, <type> is one of: FLOPPY_5L - 48 TPI low-density diskette drive FLOPPY_5H - 96 TPI high-density diskette drive FLOPPY_3L - 3.5-inch 720KB drive FLOPPY_3H - 3.5-inch high-density 1.44MB diskette drive FLOPPY_3X - 3.5-inch ext-density 2.88MB diskette drive FLOPPY_8L - 8-inch single-density diskette drive FLOPPY_8H - 8-inch double-density diskette drive OTHER - other (including CD drive with no media) HDD - hard disk drive (including PRM) TAPE - tape drive OPTICAL - read/write optical drive and <flag> is 1 for non-partitionable removable media (e.g. floppies) or 0 otherwise (including both fixed and PRM disks) On error, returns "". ------------------------------------------------------------------------- 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. ------------------------------------------------------------------------- Sys2ReadLine Read a line (up to the next line feed) from a previously-opened stream. Only ASCII LF (0x0A) bytes are treated as line-end characters; they will be stripped from the result string. CR bytes (0x0D) will be skipped over but otherwise ignored. REXX ARGUMENTS: 1. File handle (returned by Sys2Open or Sys2CreateNamedPipe) (REQUIRED) REXX RETURN VALUE: String containing the text read. In the case of error, this will be "" and SYS2ERR will be set. ------------------------------------------------------------------------- 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.