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 Sys2Exec - Execute an external program (DosExecPgm wrapper) 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 Sys2QuerySysValue - Query the given PM system value 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: "" ------------------------------------------------------------------------- Sys2Exec Executes an external program and returns the process ID or termination code. Wrapper to DosExecPgm. Note that there are limitations on the type of program which can be started, depending on the calling program's type. In particular, text mode (VIO) programs which expect input must not be started from a graphical (PM) program. If it is necessary to start a VIO program from a PM program using this function, it should be run detached ('D' mode). VIO programs requiring input can be started from other VIO programs, but it generally advisable to use start them in wait ('W') mode. REXX ARGUMENTS: 1. Name of executable program to run. (REQUIRED) 2. Argument string to pass to the called program. 3. Execution mode flag, one of: 'W' or 'S': Run the program in wait (synchronous) mode (EXEC_SYNC). 'N' or 'A': Run the program in no-wait (asynchronous) mode (EXEC_ASYNC). 'D' or 'B': Run the program detached (EXEC_BACKGROUND). REXX RETURN VALUE: If EXEC_SYNC mode was requested, returns the termination status (this is _not_ the same as the return code) from the started program. Otherwise, returns the process ID of the started program. ------------------------------------------------------------------------- Sys2FormatNumber Formats a number with locale-specific thousands-grouping characters, decimal point, and/or negative sign, as applicable. The current locale conventions will be used (as defined by the environment values %LC_ALL%, %LC_NUMERIC%, or %LANG%, in that order of precedence). 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). The range limits for the specified number are those of a 64-bit signed integer (ñ9,223,372,036,854,775,807), or an 80-bit floating point value. 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 where is the uppercase drive letter followed by a colon, is the total size of the drive/volume in binary kilobytes, 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 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. ------------------------------------------------------------------------- Sys2QuerySysValue Query the given system value. REXX ARGUMENTS: 1. The system value identifier (REQUIRED) Valid identifiers are (see the Presentation Manager Programming Reference description of WinQuerySysValue for descriptions): ALARM ALTMNEMONIC ANIMATIONSPEED ANIMATION BEGINDRAG BEGINDRAGKB BEGINSELECT BEGINSELECTKB CHORDTIME CICONTEXTLINES CMOUSEBUTTONS CONTEXTHELPKB CONTEXTHELP CONTEXTMENU CONTEXTMENUKB CPOINTERBUTTONS CTIMERS CURSORLEVEL CURSORRATE CXALIGN CXBORDER CXBYTEALIGN CXCHORD CXDBLCLK CXDLGFRAME CXFULLSCREEN CXHSCROLLARROW CXHSLIDER CXICONTEXTWIDTH CXICON CXMINMAXBUTTON CXMOTIONSTART CXPOINTER CXSCREEN CXSIZEBORDER CXVSCROLL CYALIGN CYBORDER CYBYTEALIGN CYCHORD CYDBLCLK CYDLGFRAME CYFULLSCREEN CYHSCROLL CYICON CYMENU CYMINMAXBUTTON CYMOTIONSTART CYPOINTER CYSCREEN CYSIZEBORDER CYTITLEBAR CYVSCROLLARROW CYVSLIDER DBLCLKTIME DEBUG ENDDRAG ENDDRAGKB ENDSELECTKB ENDSELECT ERRORDURATION ERRORFREQ FIRSTSCROLLRATE INSERTMODE KBDALTERED LOCKSTARTINPUT MENUROLLDOWNDELAY MENUROLLUPDELAY MONOICONS MOUSEPRESENT NOTEDURATION NOTEFREQ NUMBEREDLISTS OPEN OPENKB POINTERLEVEL PRINTSCREEN SCROLLRATE SELECTKB SETLIGHTS SINGLESELECT SWAPBUTTON TASKLISTMOUSEACCESS TEXTEDIT TEXTEDITKB TRACKRECTLEVEL WARNINGDURATION WARNINGFREQ REXX RETURN VALUE: String containing the requested system value, 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. ------------------------------------------------------------------------- Sys2SetSize Set the size of a file to a specific number of bytes; files larger than 2GB are supported (this function is a wrapper to DosSetFileSizeL). REXX ARGUMENTS: 1. File handle (returned by Sys2Open). (REQUIRED) 2. The new file size, in bytes. (REQUIRED) REXX RETURN VALUE: 1 on success, or 0 if an error occurred. ------------------------------------------------------------------------- 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.