source: rxutilex/trunk/FUNCTIONS@ 16

Last change on this file since 16 was 16, checked in by Alex Taylor, 11 years ago

Added named-pipe and I/O functions (not yet fully tested).

File size: 12.9 KB
RevLine 
[4]1FUNCTIONS IN RXUTILEX.DLL
2
3(See file 'TODO' for functions which are under consideration to be added.)
4
[16]5Sys2CheckNamedPipe - Check the status of a named pipe
6Sys2ConnectNamedPipe - Enable client sessions on a named pipe
7Sys2CreateNamedPipe - Create a named pipe
8Sys2DisconnectNamedPipe - Acknowledge that a named pipe session has ended
[4]9Sys2DropFuncs - Deregister all functions
10Sys2FormatTime - Format calender time (strftime wrapper)
11Sys2GetClipboardText - Retrieve the current clipboard text
12Sys2GetEpochTime - Get or convert calender time (seconds from epoch)
13Sys2KillProcess - Kill a process by name or PID
14Sys2LoadFuncs - Register all functions
15Sys2LocateDLL - Search for a loaded/loadable DLL
16Sys2PutClipboardText - Copy a text string to the clipboard
17Sys2QueryForegroundProcess - Get the PID of the current foreground process
18Sys2QueryPhysicalMemory - Get the amount of installed RAM
19Sys2QueryProcess - Get information about a process
20Sys2QueryProcessList - Get the list of running processes
[16]21Sys2Read -
[4]22Sys2ReplaceModule - Unlock a DLL (DosReplaceModule wrapper)
23Sys2Version - Get the version of this library
24
25
26If an internal error occurs in any function, the variable SYS2ERR will contain
[16]27an error message of the form "RC: description" where RC is a non-zero error
[4]28code, and description indicates the internal function call that failed. If
29no error occurs, SYS2ERR will be "0".
30
31
32-------------------------------------------------------------------------
[16]33Sys2CheckNamedPipe
34
35Check the status of a named pipe.
36
37REXX ARGUMENTS:
38 1. The pipe handle (from Sys2CreateNamedPipe or DosOpen). (REQUIRED)
39
40REXX 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-------------------------------------------------------------------------
47Sys2ConnectNamedPipe
48
49Start 'listening' by allowing clients to connect to a previously-created
50named pipe.
51
52REXX ARGUMENTS:
53 1. The pipe handle, as returned by Sys2CreateNamedPipe. (REQUIRED)
54
55REXX RETURN VALUE:
56 1 on success, or 0 if an error occurred.
57
58
59-------------------------------------------------------------------------
60Sys2CreateNamedPipe
61
62Creates a named pipe with the specified name and parameters.
63
64Note that the standard REXX functions such as CHARIN/OUT, which operate
65directly on file names, are not capable of using the pipe handle returned
66from this function. While the client end can use such functions after
67using STREAM to issue an OPEN WRITE or OPEN READ command, the host end
68needs to use the pipe handle from this function, and must therefore use
69Sys2Read/Sys2Write in order to read and write data from the pipe.
70
71REXX 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
92REXX RETURN VALUE: A four-byte pipe handle.
93
94
95-------------------------------------------------------------------------
96Sys2DisconnectNamedPipe
97
98Unlocks a named pipe after a client has closed its connection.
99
100REXX ARGUMENTS:
101 1. The pipe handle, as returned by Sys2CreateNamedPipe. (REQUIRED)
102
103REXX RETURN VALUE:
104 1 on success, or 0 if an error occurred.
105
106
107-------------------------------------------------------------------------
[4]108Sys2DropFuncs
109
110Deregisters all Sys2* REXX functions.
111
112REXX ARGUMENTS: None
113REXX RETURN VALUE: ""
114
115
116-------------------------------------------------------------------------
117Sys2FormatTime
118
119Converts a number of seconds from the epoch (1970-01-01 0:00:00 UTC) into
120a formatted date and time string.
121
122REXX 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
138REXX RETURN VALUE: The formatted time string, or "" on error.
139
140
141-------------------------------------------------------------------------
142Sys2GetClipboardText
143
144Retrieves a plain-text string from the clipboard if one is available.
145
146This function requires Presentation Manager to be active, although the
147REXX program itself need not be running in a PM process.
148
149REXX ARGUMENTS:
150 None.
151
152REXX RETURN VALUE: The retrieved clipboard string
153
154
155-------------------------------------------------------------------------
156Sys2GetEpochTime
157
158Converts formatted date and time into a number of seconds (UTC) from the
159epoch (defined as 1970-01-01 0:00:00). The input time is assumed to
160refer to the current timezone as defined in the TZ environment variable.
161
162If no parameters are specified, the current system time is used. If at
163least one parameter is specified, then any missing parameter is assumed
164to be its minimum possible value (1 for day or month, 0 for all others).
165
166The time is formatted according to the C runtime's locale support, as
167configured via the LANG and LC_* environment variables.
168
169REXX 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
187REXX RETURN VALUE: The number of seconds since the epoch, or 0 on error.
188
189
190-------------------------------------------------------------------------
191Sys2KillProcess
192
193Terminates the (first) running process with the specified executable name
194or process-ID.
195
196REXX 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
203REXX RETURN VALUE: 1 on success or 0 on failure.
204
205
206-------------------------------------------------------------------------
207Sys2LoadFuncs
208
209Registers all Sys2* REXX functions (except this one, obviously).
210
211REXX ARGUMENTS: None
212REXX RETURN VALUE: ""
213
214
215-------------------------------------------------------------------------
[16]216Sys2LocateDLL
[4]217
[16]218Searches for a DLL by name and returns its fully-qualified path.
219
[4]220If a DLL with the given name is currently loaded, that instance of the
221DLL will be returned. Otherwise, standard DLL loading rules (according
222to the current LIBPATH and/or extended LIBPATH configuration) are used to
[16]223search for a DLL whose module name matches the one specified.
[4]224
[16]225REXX ARGUMENTS:
226 1. The name of the DLL to search for. (REQUIRED)
[4]227
228
[16]229REXX RETURN VALUE:
230 The fully-qualified path of the DLL, if found; "" otherwise.
231
232
[4]233-------------------------------------------------------------------------
234
235Sys2PutClipboardText
236
237Writes a string to the clipboard in plain-text format. Specifying either
238no value or an empty string in the first argument will simply clear the
239clipboard of CF_TEXT data.
240
241This function requires Presentation Manager to be active, although the
242REXX program itself need not be running in a PM process.
243
244REXX 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
250REXX RETURN VALUE: 1 on success, 0 on failure
251
252
253-------------------------------------------------------------------------
254Sys2QueryForegroundProcess
255
256Queries the PID of the current foreground process.
257
258REXX ARGUMENTS: None
259
260REXX RETURN VALUE:
261 Integer representing the process ID (in decimal), or 0 if an error
262 occurred.
263
264
265-------------------------------------------------------------------------
266Sys2QueryPhysicalMemory
267
268Queries the amount of physical memory (RAM) installed in the system.
269
270REXX ARGUMENTS: None
271
272REXX RETURN VALUE:
273 Integer representing the amount of installed memory, in KiB, or 0 if an
274 error occurred.
275
276
277-------------------------------------------------------------------------
278Sys2QueryProcess
279
280Queries information about the specified process.
281
282REXX 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
289REXX 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-------------------------------------------------------------------------
298Sys2QueryProcessList
299
300Gets a list of running processes. The results will be returned in a stem
[16]301variable, where stem.0 contains number of items, and each stem item is a
[4]302string 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
306Notes:
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
316REXX ARGUMENTS:
317 1. The name of the stem in which to return the results (REQUIRED)
318
319REXX RETURN VALUE: Number of processes found, or "" in case of error.
320
321
322-------------------------------------------------------------------------
[16]323Sys2Read
324
325Read bytes from a previously-opened stream (wrapper to DosRead). The
326format of file handles supported by this function is currently limited
327to those returned by Sys2CreateNamedPipe.
328
329REXX ARGUMENTS:
330 1. File handle (as returned by Sys2CreateNamedPipe). (REQUIRED)
331 2. Number of bytes to read. (REQUIRED)
332
333REXX RETURN VALUE:
334 String containing the bytes read, or "" in case of error.
335
336
337-------------------------------------------------------------------------
[4]338Sys2ReplaceModule
339
340Unlocks and optionally replaces an in-use (locked) DLL or EXE.
341
342REXX 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
347REXX RETURN VALUE:
348 1 on success, or 0 if an error occurred.
349
350
351-------------------------------------------------------------------------
352Sys2Version
353
354Returns the current library version.
355
356REXX ARGUMENTS: None
357REXX RETURN VALUE: Current version in the form "major.minor.refresh"
358
Note: See TracBrowser for help on using the repository browser.