[4] | 1 | FUNCTIONS IN RXUTILEX.DLL
|
---|
| 2 |
|
---|
| 3 | (See file 'TODO' for functions which are under consideration to be added.)
|
---|
| 4 |
|
---|
[16] | 5 | Sys2CheckNamedPipe - Check the status of a named pipe
|
---|
| 6 | Sys2ConnectNamedPipe - Enable client sessions on a named pipe
|
---|
| 7 | Sys2CreateNamedPipe - Create a named pipe
|
---|
| 8 | Sys2DisconnectNamedPipe - Acknowledge that a named pipe session has ended
|
---|
[4] | 9 | Sys2DropFuncs - Deregister all functions
|
---|
| 10 | Sys2FormatTime - Format calender time (strftime wrapper)
|
---|
| 11 | Sys2GetClipboardText - Retrieve the current clipboard text
|
---|
| 12 | Sys2GetEpochTime - Get or convert calender time (seconds from epoch)
|
---|
| 13 | Sys2KillProcess - Kill a process by name or PID
|
---|
| 14 | Sys2LoadFuncs - Register all functions
|
---|
| 15 | Sys2LocateDLL - Search for a loaded/loadable DLL
|
---|
| 16 | Sys2PutClipboardText - Copy a text string to the clipboard
|
---|
| 17 | Sys2QueryForegroundProcess - Get the PID of the current foreground process
|
---|
| 18 | Sys2QueryPhysicalMemory - Get the amount of installed RAM
|
---|
| 19 | Sys2QueryProcess - Get information about a process
|
---|
| 20 | Sys2QueryProcessList - Get the list of running processes
|
---|
[16] | 21 | Sys2Read -
|
---|
[4] | 22 | Sys2ReplaceModule - Unlock a DLL (DosReplaceModule wrapper)
|
---|
| 23 | Sys2Version - Get the version of this library
|
---|
| 24 |
|
---|
| 25 |
|
---|
| 26 | If an internal error occurs in any function, the variable SYS2ERR will contain
|
---|
[16] | 27 | an error message of the form "RC: description" where RC is a non-zero error
|
---|
[4] | 28 | code, and description indicates the internal function call that failed. If
|
---|
| 29 | no error occurs, SYS2ERR will be "0".
|
---|
| 30 |
|
---|
| 31 |
|
---|
| 32 | -------------------------------------------------------------------------
|
---|
[16] | 33 | Sys2CheckNamedPipe
|
---|
| 34 |
|
---|
| 35 | Check the status of a named pipe.
|
---|
| 36 |
|
---|
| 37 | REXX ARGUMENTS:
|
---|
| 38 | 1. The pipe handle (from Sys2CreateNamedPipe or DosOpen). (REQUIRED)
|
---|
| 39 |
|
---|
| 40 | REXX RETURN VALUE:
|
---|
| 41 | String of the format "bytes status", where bytes is the number of bytes
|
---|
| 42 | currently waiting in the pipe, and status is one of: DISCONNECTED,
|
---|
| 43 | LISTENING, CONNECTED, or CLOSING.
|
---|
| 44 |
|
---|
| 45 |
|
---|
| 46 | -------------------------------------------------------------------------
|
---|
| 47 | Sys2ConnectNamedPipe
|
---|
| 48 |
|
---|
| 49 | Start 'listening' by allowing clients to connect to a previously-created
|
---|
| 50 | named pipe.
|
---|
| 51 |
|
---|
| 52 | REXX ARGUMENTS:
|
---|
| 53 | 1. The pipe handle, as returned by Sys2CreateNamedPipe. (REQUIRED)
|
---|
| 54 |
|
---|
| 55 | REXX RETURN VALUE:
|
---|
| 56 | 1 on success, or 0 if an error occurred.
|
---|
| 57 |
|
---|
| 58 |
|
---|
| 59 | -------------------------------------------------------------------------
|
---|
| 60 | Sys2CreateNamedPipe
|
---|
| 61 |
|
---|
| 62 | Creates a named pipe with the specified name and parameters.
|
---|
| 63 |
|
---|
| 64 | Note that the standard REXX functions such as CHARIN/OUT, which operate
|
---|
| 65 | directly on file names, are not capable of using the pipe handle returned
|
---|
| 66 | from this function. While the client end can use such functions after
|
---|
| 67 | using STREAM to issue an OPEN WRITE or OPEN READ command, the host end
|
---|
| 68 | needs to use the pipe handle from this function, and must therefore use
|
---|
| 69 | Sys2Read/Sys2Write in order to read and write data from the pipe.
|
---|
| 70 |
|
---|
| 71 | REXX ARGUMENTS:
|
---|
| 72 | 1. The name of the pipe, in the form "\PIPE\something". (REQUIRED)
|
---|
| 73 | 2. The size of the outbound buffer, in bytes. (REQUIRED)
|
---|
| 74 | 3. The size of the inbound buffer, in bytes. (REQUIRED)
|
---|
| 75 | 4. The pipe's timeout value, in milliseconds. (DEFAULT: 3000)
|
---|
| 76 | 5. The number of simultaneous instances of this pipe which are allowed.
|
---|
| 77 | Must be between 1 and 254, or 0 indicating no limit. (DEFAULT: 1)
|
---|
| 78 | 6. Pipe blocking mode, one of:
|
---|
| 79 | W = WAIT mode, read and write block waiting for data (DEFAULT)
|
---|
| 80 | N = NOWAIT mode, read and write return immediately
|
---|
| 81 | 7. Pipe mode, one of:
|
---|
| 82 | I = Inbound pipe (DEFAULT)
|
---|
| 83 | O = Outbound pipe
|
---|
| 84 | D = Duplex (inbound/outbound) pipe
|
---|
| 85 | 8. Privacy/inheritance flag, one of:
|
---|
| 86 | 0 = The pipe handle is inherited by child processes (DEFAULT)
|
---|
| 87 | 1 = The pipe handle is private to the current process
|
---|
| 88 | 9. Write-through flag, one of:
|
---|
| 89 | 0 = Allow delayed writes (write-behind) to remote pipes (DEFAULT)
|
---|
| 90 | 1 = Force immediate writes (write-through) to remote pipes
|
---|
| 91 |
|
---|
| 92 | REXX RETURN VALUE: A four-byte pipe handle.
|
---|
| 93 |
|
---|
| 94 |
|
---|
| 95 | -------------------------------------------------------------------------
|
---|
| 96 | Sys2DisconnectNamedPipe
|
---|
| 97 |
|
---|
| 98 | Unlocks a named pipe after a client has closed its connection.
|
---|
| 99 |
|
---|
| 100 | REXX ARGUMENTS:
|
---|
| 101 | 1. The pipe handle, as returned by Sys2CreateNamedPipe. (REQUIRED)
|
---|
| 102 |
|
---|
| 103 | REXX RETURN VALUE:
|
---|
| 104 | 1 on success, or 0 if an error occurred.
|
---|
| 105 |
|
---|
| 106 |
|
---|
| 107 | -------------------------------------------------------------------------
|
---|
[4] | 108 | Sys2DropFuncs
|
---|
| 109 |
|
---|
| 110 | Deregisters all Sys2* REXX functions.
|
---|
| 111 |
|
---|
| 112 | REXX ARGUMENTS: None
|
---|
| 113 | REXX RETURN VALUE: ""
|
---|
| 114 |
|
---|
| 115 |
|
---|
| 116 | -------------------------------------------------------------------------
|
---|
| 117 | Sys2FormatTime
|
---|
| 118 |
|
---|
| 119 | Converts a number of seconds from the epoch (1970-01-01 0:00:00 UTC) into
|
---|
| 120 | a formatted date and time string.
|
---|
| 121 |
|
---|
| 122 | REXX ARGUMENTS:
|
---|
| 123 | 1. Number of seconds (a positive integer) to be converted. (REQUIRED)
|
---|
| 124 | This value cannot be greater than 2,147,483,647.
|
---|
| 125 | 2. Format type, one of:
|
---|
| 126 | D = return in the form 'yyyy-mm-dd hh:mm:ss (w)' where w
|
---|
| 127 | represents the weekday (0-6 where 0=Sunday) (DEFAULT)
|
---|
| 128 | I = return in ISO8601 combined form 'yyyy-mm-ddThh:mm:ss[Z]'
|
---|
| 129 | L = return in the form 'day month year (weekday) time' where month
|
---|
| 130 | and weekday are language-dependent abbreviations
|
---|
| 131 | Note: With D and I, time is returned in 24-hour format; L may vary.
|
---|
| 132 | 3. TZ conversion flag (indicates whether to convert to UTC from local
|
---|
| 133 | time), one of:
|
---|
| 134 | U = return UTC or unconverted time
|
---|
| 135 | L = assume the input is in Coordinated Universal Time, and convert
|
---|
| 136 | to local time using the current TZ (DEFAULT)
|
---|
| 137 |
|
---|
| 138 | REXX RETURN VALUE: The formatted time string, or "" on error.
|
---|
| 139 |
|
---|
| 140 |
|
---|
| 141 | -------------------------------------------------------------------------
|
---|
| 142 | Sys2GetClipboardText
|
---|
| 143 |
|
---|
| 144 | Retrieves a plain-text string from the clipboard if one is available.
|
---|
| 145 |
|
---|
| 146 | This function requires Presentation Manager to be active, although the
|
---|
| 147 | REXX program itself need not be running in a PM process.
|
---|
| 148 |
|
---|
| 149 | REXX ARGUMENTS:
|
---|
| 150 | None.
|
---|
| 151 |
|
---|
| 152 | REXX RETURN VALUE: The retrieved clipboard string
|
---|
| 153 |
|
---|
| 154 |
|
---|
| 155 | -------------------------------------------------------------------------
|
---|
| 156 | Sys2GetEpochTime
|
---|
| 157 |
|
---|
| 158 | Converts formatted date and time into a number of seconds (UTC) from the
|
---|
| 159 | epoch (defined as 1970-01-01 0:00:00). The input time is assumed to
|
---|
| 160 | refer to the current timezone as defined in the TZ environment variable.
|
---|
| 161 |
|
---|
| 162 | If no parameters are specified, the current system time is used. If at
|
---|
| 163 | least one parameter is specified, then any missing parameter is assumed
|
---|
| 164 | to be its minimum possible value (1 for day or month, 0 for all others).
|
---|
| 165 |
|
---|
| 166 | The time is formatted according to the C runtime's locale support, as
|
---|
| 167 | configured via the LANG and LC_* environment variables.
|
---|
| 168 |
|
---|
| 169 | REXX ARGUMENTS:
|
---|
| 170 | 1. The year (1970-2037)
|
---|
| 171 | Years prior to 1970 or later than 2037 cannot be supported due to the
|
---|
| 172 | limitations in how the C library calculates epoch time. Specifying
|
---|
[16] | 173 | 1969 or earlier will generate a REXX error. Any date later than 2037
|
---|
[4] | 174 | will return a value of 0 (and SYS2ERR will report an error in 'mktime').
|
---|
| 175 | NOTE: A 2-digit year can be specified, in which case the number will be
|
---|
[16] | 176 | added to 1900 if it is 70 or higher, or to 2000 otherwise.
|
---|
[4] | 177 | e.g. '20' ==> 2020
|
---|
| 178 | '75' ==> 1975
|
---|
| 179 | This is subject to the limitation noted above, such that values
|
---|
| 180 | from 38 to 69 will result in a return value of 0.
|
---|
| 181 | 2. The month (1-12)
|
---|
| 182 | 3. The day (1-31)
|
---|
| 183 | 4. Hours (0-23)
|
---|
| 184 | 5. Minutes (0-59)
|
---|
| 185 | 6. Seconds (0-61)
|
---|
| 186 |
|
---|
| 187 | REXX RETURN VALUE: The number of seconds since the epoch, or 0 on error.
|
---|
| 188 |
|
---|
| 189 |
|
---|
| 190 | -------------------------------------------------------------------------
|
---|
| 191 | Sys2KillProcess
|
---|
| 192 |
|
---|
| 193 | Terminates the (first) running process with the specified executable name
|
---|
| 194 | or process-ID.
|
---|
| 195 |
|
---|
| 196 | REXX ARGUMENTS:
|
---|
| 197 | 1. The process identifier (program name or process ID) (REQUIRED)
|
---|
| 198 | 2. Flag indicicating the identifier type:
|
---|
| 199 | 'P': decimal process ID
|
---|
| 200 | 'H': hexadecimal process ID
|
---|
| 201 | 'N': executable program name (with or without extension) (DEFAULT)
|
---|
| 202 |
|
---|
| 203 | REXX RETURN VALUE: 1 on success or 0 on failure.
|
---|
| 204 |
|
---|
| 205 |
|
---|
| 206 | -------------------------------------------------------------------------
|
---|
| 207 | Sys2LoadFuncs
|
---|
| 208 |
|
---|
| 209 | Registers all Sys2* REXX functions (except this one, obviously).
|
---|
| 210 |
|
---|
| 211 | REXX ARGUMENTS: None
|
---|
| 212 | REXX RETURN VALUE: ""
|
---|
| 213 |
|
---|
| 214 |
|
---|
| 215 | -------------------------------------------------------------------------
|
---|
[16] | 216 | Sys2LocateDLL
|
---|
[4] | 217 |
|
---|
[16] | 218 | Searches for a DLL by name and returns its fully-qualified path.
|
---|
| 219 |
|
---|
[4] | 220 | If a DLL with the given name is currently loaded, that instance of the
|
---|
| 221 | DLL will be returned. Otherwise, standard DLL loading rules (according
|
---|
| 222 | to the current LIBPATH and/or extended LIBPATH configuration) are used to
|
---|
[16] | 223 | search for a DLL whose module name matches the one specified.
|
---|
[4] | 224 |
|
---|
[16] | 225 | REXX ARGUMENTS:
|
---|
| 226 | 1. The name of the DLL to search for. (REQUIRED)
|
---|
[4] | 227 |
|
---|
| 228 |
|
---|
[16] | 229 | REXX RETURN VALUE:
|
---|
| 230 | The fully-qualified path of the DLL, if found; "" otherwise.
|
---|
| 231 |
|
---|
| 232 |
|
---|
[4] | 233 | -------------------------------------------------------------------------
|
---|
| 234 |
|
---|
| 235 | Sys2PutClipboardText
|
---|
| 236 |
|
---|
| 237 | Writes a string to the clipboard in plain-text format. Specifying either
|
---|
| 238 | no value or an empty string in the first argument will simply clear the
|
---|
| 239 | clipboard of CF_TEXT data.
|
---|
| 240 |
|
---|
| 241 | This function requires Presentation Manager to be active, although the
|
---|
| 242 | REXX program itself need not be running in a PM process.
|
---|
| 243 |
|
---|
| 244 | REXX ARGUMENTS:
|
---|
| 245 | 1. String to be written to the clipboard (DEFAULT: "")
|
---|
| 246 | 2. Flag indicating whether other clipboard formats should be cleared:
|
---|
| 247 | Y = yes, call WinEmptyClipbrd() before writing text (DEFAULT)
|
---|
| 248 | N = no, leave (non-CF_TEXT) clipboard data untouched
|
---|
| 249 |
|
---|
| 250 | REXX RETURN VALUE: 1 on success, 0 on failure
|
---|
| 251 |
|
---|
| 252 |
|
---|
| 253 | -------------------------------------------------------------------------
|
---|
| 254 | Sys2QueryForegroundProcess
|
---|
| 255 |
|
---|
| 256 | Queries the PID of the current foreground process.
|
---|
| 257 |
|
---|
| 258 | REXX ARGUMENTS: None
|
---|
| 259 |
|
---|
| 260 | REXX RETURN VALUE:
|
---|
| 261 | Integer representing the process ID (in decimal), or 0 if an error
|
---|
| 262 | occurred.
|
---|
| 263 |
|
---|
| 264 |
|
---|
| 265 | -------------------------------------------------------------------------
|
---|
| 266 | Sys2QueryPhysicalMemory
|
---|
| 267 |
|
---|
| 268 | Queries the amount of physical memory (RAM) installed in the system.
|
---|
| 269 |
|
---|
| 270 | REXX ARGUMENTS: None
|
---|
| 271 |
|
---|
| 272 | REXX RETURN VALUE:
|
---|
| 273 | Integer representing the amount of installed memory, in KiB, or 0 if an
|
---|
| 274 | error occurred.
|
---|
| 275 |
|
---|
| 276 |
|
---|
| 277 | -------------------------------------------------------------------------
|
---|
| 278 | Sys2QueryProcess
|
---|
| 279 |
|
---|
| 280 | Queries information about the specified process.
|
---|
| 281 |
|
---|
| 282 | REXX ARGUMENTS:
|
---|
| 283 | 1. The process identifier (program name or process ID) (REQUIRED)
|
---|
| 284 | 2. Flag indicicating the identifier type:
|
---|
| 285 | 'P': decimal process ID
|
---|
| 286 | 'H': hexadecimal process ID
|
---|
| 287 | 'N': executable program name (with or without extension) (DEFAULT)
|
---|
| 288 |
|
---|
| 289 | REXX RETURN VALUE:
|
---|
| 290 | A string of the format
|
---|
| 291 | pid parent-pid process-type priority cpu-time executable-name
|
---|
| 292 | "priority" is in hexadecimal notation, all other numbers are decimal.
|
---|
| 293 | "" is returned if the process was not found or if an internal error
|
---|
| 294 | occurred.
|
---|
| 295 |
|
---|
| 296 |
|
---|
| 297 | -------------------------------------------------------------------------
|
---|
| 298 | Sys2QueryProcessList
|
---|
| 299 |
|
---|
| 300 | Gets a list of running processes. The results will be returned in a stem
|
---|
[16] | 301 | variable, where stem.0 contains number of items, and each stem item is a
|
---|
[4] | 302 | string of the form:
|
---|
| 303 | pid parent-pid process-type priority cpu-time executable-name
|
---|
| 304 | "priority" is in hexadecimal notation, all other numbers are decimal.
|
---|
| 305 |
|
---|
| 306 | Notes:
|
---|
| 307 | - "process-type" will be one of:
|
---|
| 308 | 0 Full screen protect-mode session
|
---|
| 309 | 1 Requires real mode. Dos emulation.
|
---|
| 310 | 2 VIO windowable protect-mode session
|
---|
| 311 | 3 Presentation Manager protect-mode session
|
---|
| 312 | 4 Detached protect-mode process.
|
---|
| 313 | - If "priority" is 0 then the priority class could not be determined.
|
---|
| 314 | - If "executable-name" is "--" then the name could not be identified.
|
---|
| 315 |
|
---|
| 316 | REXX ARGUMENTS:
|
---|
| 317 | 1. The name of the stem in which to return the results (REQUIRED)
|
---|
| 318 |
|
---|
| 319 | REXX RETURN VALUE: Number of processes found, or "" in case of error.
|
---|
| 320 |
|
---|
| 321 |
|
---|
| 322 | -------------------------------------------------------------------------
|
---|
[16] | 323 | Sys2Read
|
---|
| 324 |
|
---|
| 325 | Read bytes from a previously-opened stream (wrapper to DosRead). The
|
---|
| 326 | format of file handles supported by this function is currently limited
|
---|
| 327 | to those returned by Sys2CreateNamedPipe.
|
---|
| 328 |
|
---|
| 329 | REXX ARGUMENTS:
|
---|
| 330 | 1. File handle (as returned by Sys2CreateNamedPipe). (REQUIRED)
|
---|
| 331 | 2. Number of bytes to read. (REQUIRED)
|
---|
| 332 |
|
---|
| 333 | REXX RETURN VALUE:
|
---|
| 334 | String containing the bytes read, or "" in case of error.
|
---|
| 335 |
|
---|
| 336 |
|
---|
| 337 | -------------------------------------------------------------------------
|
---|
[4] | 338 | Sys2ReplaceModule
|
---|
| 339 |
|
---|
| 340 | Unlocks and optionally replaces an in-use (locked) DLL or EXE.
|
---|
| 341 |
|
---|
| 342 | REXX ARGUMENTS:
|
---|
| 343 | 1. The filespec of the module to be replaced. (REQUIRED)
|
---|
| 344 | 2. The filespec of the new module to replace it with. (DEFAULT: none)
|
---|
| 345 | 3. The filespec of the backup file to be created. (DEFAULT: none)
|
---|
| 346 |
|
---|
| 347 | REXX RETURN VALUE:
|
---|
| 348 | 1 on success, or 0 if an error occurred.
|
---|
| 349 |
|
---|
| 350 |
|
---|
| 351 | -------------------------------------------------------------------------
|
---|
| 352 | Sys2Version
|
---|
| 353 |
|
---|
| 354 | Returns the current library version.
|
---|
| 355 |
|
---|
| 356 | REXX ARGUMENTS: None
|
---|
| 357 | REXX RETURN VALUE: Current version in the form "major.minor.refresh"
|
---|
| 358 |
|
---|