| [4] | 1 | FUNCTIONS IN RXUTILEX.DLL
|
|---|
| 2 |
|
|---|
| 3 | (See file 'TODO' for functions which are under consideration to be added.)
|
|---|
| 4 |
|
|---|
| 5 | Sys2DropFuncs - Deregister all functions
|
|---|
| 6 | Sys2FormatTime - Format calender time (strftime wrapper)
|
|---|
| 7 | Sys2GetClipboardText - Retrieve the current clipboard text
|
|---|
| 8 | Sys2GetEpochTime - Get or convert calender time (seconds from epoch)
|
|---|
| 9 | Sys2KillProcess - Kill a process by name or PID
|
|---|
| 10 | Sys2LoadFuncs - Register all functions
|
|---|
| 11 | Sys2LocateDLL - Search for a loaded/loadable DLL
|
|---|
| 12 | Sys2PutClipboardText - Copy a text string to the clipboard
|
|---|
| 13 | Sys2QueryForegroundProcess - Get the PID of the current foreground process
|
|---|
| 14 | Sys2QueryPhysicalMemory - Get the amount of installed RAM
|
|---|
| 15 | Sys2QueryProcess - Get information about a process
|
|---|
| 16 | Sys2QueryProcessList - Get the list of running processes
|
|---|
| 17 | Sys2ReplaceModule - Unlock a DLL (DosReplaceModule wrapper)
|
|---|
| 18 | Sys2Version - Get the version of this library
|
|---|
| 19 |
|
|---|
| 20 |
|
|---|
| 21 | If 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
|
|---|
| 23 | code, and description indicates the internal function call that failed. If
|
|---|
| 24 | no error occurs, SYS2ERR will be "0".
|
|---|
| 25 |
|
|---|
| 26 |
|
|---|
| 27 | -------------------------------------------------------------------------
|
|---|
| 28 | Sys2DropFuncs
|
|---|
| 29 |
|
|---|
| 30 | Deregisters all Sys2* REXX functions.
|
|---|
| 31 |
|
|---|
| 32 | REXX ARGUMENTS: None
|
|---|
| 33 | REXX RETURN VALUE: ""
|
|---|
| 34 |
|
|---|
| 35 |
|
|---|
| 36 | -------------------------------------------------------------------------
|
|---|
| 37 | Sys2FormatTime
|
|---|
| 38 |
|
|---|
| 39 | Converts a number of seconds from the epoch (1970-01-01 0:00:00 UTC) into
|
|---|
| 40 | a formatted date and time string.
|
|---|
| 41 |
|
|---|
| 42 | REXX ARGUMENTS:
|
|---|
| 43 | 1. Number of seconds (a positive integer) to be converted. (REQUIRED)
|
|---|
| 44 | This value cannot be greater than 2,147,483,647.
|
|---|
| 45 | 2. Format type, one of:
|
|---|
| 46 | D = return in the form 'yyyy-mm-dd hh:mm:ss (w)' where w
|
|---|
| 47 | represents the weekday (0-6 where 0=Sunday) (DEFAULT)
|
|---|
| 48 | I = return in ISO8601 combined form 'yyyy-mm-ddThh:mm:ss[Z]'
|
|---|
| 49 | L = return in the form 'day month year (weekday) time' where month
|
|---|
| 50 | and weekday are language-dependent abbreviations
|
|---|
| 51 | Note: With D and I, time is returned in 24-hour format; L may vary.
|
|---|
| 52 | 3. TZ conversion flag (indicates whether to convert to UTC from local
|
|---|
| 53 | time), one of:
|
|---|
| 54 | U = return UTC or unconverted time
|
|---|
| 55 | L = assume the input is in Coordinated Universal Time, and convert
|
|---|
| 56 | to local time using the current TZ (DEFAULT)
|
|---|
| 57 |
|
|---|
| 58 | REXX RETURN VALUE: The formatted time string, or "" on error.
|
|---|
| 59 |
|
|---|
| 60 |
|
|---|
| 61 | -------------------------------------------------------------------------
|
|---|
| 62 | Sys2GetClipboardText
|
|---|
| 63 |
|
|---|
| 64 | Retrieves a plain-text string from the clipboard if one is available.
|
|---|
| 65 |
|
|---|
| 66 | This function requires Presentation Manager to be active, although the
|
|---|
| 67 | REXX program itself need not be running in a PM process.
|
|---|
| 68 |
|
|---|
| 69 | REXX ARGUMENTS:
|
|---|
| 70 | None.
|
|---|
| 71 |
|
|---|
| 72 | REXX RETURN VALUE: The retrieved clipboard string
|
|---|
| 73 |
|
|---|
| 74 |
|
|---|
| 75 | -------------------------------------------------------------------------
|
|---|
| 76 | Sys2GetEpochTime
|
|---|
| 77 |
|
|---|
| 78 | Converts formatted date and time into a number of seconds (UTC) from the
|
|---|
| 79 | epoch (defined as 1970-01-01 0:00:00). The input time is assumed to
|
|---|
| 80 | refer to the current timezone as defined in the TZ environment variable.
|
|---|
| 81 |
|
|---|
| 82 | If no parameters are specified, the current system time is used. If at
|
|---|
| 83 | least one parameter is specified, then any missing parameter is assumed
|
|---|
| 84 | to be its minimum possible value (1 for day or month, 0 for all others).
|
|---|
| 85 |
|
|---|
| 86 | The time is formatted according to the C runtime's locale support, as
|
|---|
| 87 | configured via the LANG and LC_* environment variables.
|
|---|
| 88 |
|
|---|
| 89 | REXX ARGUMENTS:
|
|---|
| 90 | 1. The year (1970-2037)
|
|---|
| 91 | Years prior to 1970 or later than 2037 cannot be supported due to the
|
|---|
| 92 | limitations in how the C library calculates epoch time. Specifying
|
|---|
| 93 | 1969 or earlier will generate a REXX error. Any date later than 2037
|
|---|
| 94 | will return a value of 0 (and SYS2ERR will report an error in 'mktime').
|
|---|
| 95 | 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.
|
|---|
| 97 | e.g. '20' ==> 2020
|
|---|
| 98 | '75' ==> 1975
|
|---|
| 99 | This is subject to the limitation noted above, such that values
|
|---|
| 100 | from 38 to 69 will result in a return value of 0.
|
|---|
| 101 | 2. The month (1-12)
|
|---|
| 102 | 3. The day (1-31)
|
|---|
| 103 | 4. Hours (0-23)
|
|---|
| 104 | 5. Minutes (0-59)
|
|---|
| 105 | 6. Seconds (0-61)
|
|---|
| 106 |
|
|---|
| 107 | REXX RETURN VALUE: The number of seconds since the epoch, or 0 on error.
|
|---|
| 108 |
|
|---|
| 109 |
|
|---|
| 110 | -------------------------------------------------------------------------
|
|---|
| 111 | Sys2KillProcess
|
|---|
| 112 |
|
|---|
| 113 | Terminates the (first) running process with the specified executable name
|
|---|
| 114 | or process-ID.
|
|---|
| 115 |
|
|---|
| 116 | REXX ARGUMENTS:
|
|---|
| 117 | 1. The process identifier (program name or process ID) (REQUIRED)
|
|---|
| 118 | 2. Flag indicicating the identifier type:
|
|---|
| 119 | 'P': decimal process ID
|
|---|
| 120 | 'H': hexadecimal process ID
|
|---|
| 121 | 'N': executable program name (with or without extension) (DEFAULT)
|
|---|
| 122 |
|
|---|
| 123 | REXX RETURN VALUE: 1 on success or 0 on failure.
|
|---|
| 124 |
|
|---|
| 125 |
|
|---|
| 126 | -------------------------------------------------------------------------
|
|---|
| 127 | Sys2LoadFuncs
|
|---|
| 128 |
|
|---|
| 129 | Registers all Sys2* REXX functions (except this one, obviously).
|
|---|
| 130 |
|
|---|
| 131 | REXX ARGUMENTS: None
|
|---|
| 132 | REXX RETURN VALUE: ""
|
|---|
| 133 |
|
|---|
| 134 |
|
|---|
| 135 | -------------------------------------------------------------------------
|
|---|
| 136 | Sys2LocateDLL
|
|---|
| 137 |
|
|---|
| 138 | Searches for a DLL by name and returns its fully-qualified path.
|
|---|
| 139 |
|
|---|
| 140 | If a DLL with the given name is currently loaded, that instance of the
|
|---|
| 141 | DLL will be returned. Otherwise, standard DLL loading rules (according
|
|---|
| 142 | to 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.
|
|---|
| 151 |
|
|---|
| 152 |
|
|---|
| 153 | -------------------------------------------------------------------------
|
|---|
| 154 |
|
|---|
| 155 | Sys2PutClipboardText
|
|---|
| 156 |
|
|---|
| 157 | Writes a string to the clipboard in plain-text format. Specifying either
|
|---|
| 158 | no value or an empty string in the first argument will simply clear the
|
|---|
| 159 | clipboard of CF_TEXT data.
|
|---|
| 160 |
|
|---|
| 161 | This function requires Presentation Manager to be active, although the
|
|---|
| 162 | REXX program itself need not be running in a PM process.
|
|---|
| 163 |
|
|---|
| 164 | REXX ARGUMENTS:
|
|---|
| 165 | 1. String to be written to the clipboard (DEFAULT: "")
|
|---|
| 166 | 2. Flag indicating whether other clipboard formats should be cleared:
|
|---|
| 167 | Y = yes, call WinEmptyClipbrd() before writing text (DEFAULT)
|
|---|
| 168 | N = no, leave (non-CF_TEXT) clipboard data untouched
|
|---|
| 169 |
|
|---|
| 170 | REXX RETURN VALUE: 1 on success, 0 on failure
|
|---|
| 171 |
|
|---|
| 172 |
|
|---|
| 173 | -------------------------------------------------------------------------
|
|---|
| 174 | Sys2QueryForegroundProcess
|
|---|
| 175 |
|
|---|
| 176 | Queries the PID of the current foreground process.
|
|---|
| 177 |
|
|---|
| 178 | REXX ARGUMENTS: None
|
|---|
| 179 |
|
|---|
| 180 | REXX RETURN VALUE:
|
|---|
| 181 | Integer representing the process ID (in decimal), or 0 if an error
|
|---|
| 182 | occurred.
|
|---|
| 183 |
|
|---|
| 184 |
|
|---|
| 185 | -------------------------------------------------------------------------
|
|---|
| 186 | Sys2QueryPhysicalMemory
|
|---|
| 187 |
|
|---|
| 188 | Queries the amount of physical memory (RAM) installed in the system.
|
|---|
| 189 |
|
|---|
| 190 | REXX ARGUMENTS: None
|
|---|
| 191 |
|
|---|
| 192 | REXX RETURN VALUE:
|
|---|
| 193 | Integer representing the amount of installed memory, in KiB, or 0 if an
|
|---|
| 194 | error occurred.
|
|---|
| 195 |
|
|---|
| 196 |
|
|---|
| 197 | -------------------------------------------------------------------------
|
|---|
| 198 | Sys2QueryProcess
|
|---|
| 199 |
|
|---|
| 200 | Queries information about the specified process.
|
|---|
| 201 |
|
|---|
| 202 | REXX ARGUMENTS:
|
|---|
| 203 | 1. The process identifier (program name or process ID) (REQUIRED)
|
|---|
| 204 | 2. Flag indicicating the identifier type:
|
|---|
| 205 | 'P': decimal process ID
|
|---|
| 206 | 'H': hexadecimal process ID
|
|---|
| 207 | 'N': executable program name (with or without extension) (DEFAULT)
|
|---|
| 208 |
|
|---|
| 209 | REXX RETURN VALUE:
|
|---|
| 210 | A string of the format
|
|---|
| 211 | pid parent-pid process-type priority cpu-time executable-name
|
|---|
| 212 | "priority" is in hexadecimal notation, all other numbers are decimal.
|
|---|
| 213 | "" is returned if the process was not found or if an internal error
|
|---|
| 214 | occurred.
|
|---|
| 215 |
|
|---|
| 216 |
|
|---|
| 217 | -------------------------------------------------------------------------
|
|---|
| 218 | Sys2QueryProcessList
|
|---|
| 219 |
|
|---|
| 220 | Gets 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
|
|---|
| 222 | string of the form:
|
|---|
| 223 | pid parent-pid process-type priority cpu-time executable-name
|
|---|
| 224 | "priority" is in hexadecimal notation, all other numbers are decimal.
|
|---|
| 225 |
|
|---|
| 226 | Notes:
|
|---|
| 227 | - "process-type" will be one of:
|
|---|
| 228 | 0 Full screen protect-mode session
|
|---|
| 229 | 1 Requires real mode. Dos emulation.
|
|---|
| 230 | 2 VIO windowable protect-mode session
|
|---|
| 231 | 3 Presentation Manager protect-mode session
|
|---|
| 232 | 4 Detached protect-mode process.
|
|---|
| 233 | - If "priority" is 0 then the priority class could not be determined.
|
|---|
| 234 | - If "executable-name" is "--" then the name could not be identified.
|
|---|
| 235 |
|
|---|
| 236 | REXX ARGUMENTS:
|
|---|
| 237 | 1. The name of the stem in which to return the results (REQUIRED)
|
|---|
| 238 |
|
|---|
| 239 | REXX RETURN VALUE: Number of processes found, or "" in case of error.
|
|---|
| 240 |
|
|---|
| 241 |
|
|---|
| 242 | -------------------------------------------------------------------------
|
|---|
| 243 | Sys2ReplaceModule
|
|---|
| 244 |
|
|---|
| 245 | Unlocks and optionally replaces an in-use (locked) DLL or EXE.
|
|---|
| 246 |
|
|---|
| 247 | REXX ARGUMENTS:
|
|---|
| 248 | 1. The filespec of the module to be replaced. (REQUIRED)
|
|---|
| 249 | 2. The filespec of the new module to replace it with. (DEFAULT: none)
|
|---|
| 250 | 3. The filespec of the backup file to be created. (DEFAULT: none)
|
|---|
| 251 |
|
|---|
| 252 | REXX RETURN VALUE:
|
|---|
| 253 | 1 on success, or 0 if an error occurred.
|
|---|
| 254 |
|
|---|
| 255 |
|
|---|
| 256 | -------------------------------------------------------------------------
|
|---|
| 257 | Sys2Version
|
|---|
| 258 |
|
|---|
| 259 | Returns the current library version.
|
|---|
| 260 |
|
|---|
| 261 | REXX ARGUMENTS: None
|
|---|
| 262 | REXX RETURN VALUE: Current version in the form "major.minor.refresh"
|
|---|
| 263 |
|
|---|
