═══ 1. General information ═══ REXXLIB is a large collection of functions designed to extend the REXX language in OS/2. This file contains full descriptions of all REXXLIB functions except those that are part of the RXWINDOW package. For complete information on REXXLIB, including installation, general calling conventions, and specialized information on such topics as regular expressions and interprocess communication facilities, please refer to the REXXLIB User's Guide. REXXLIB software and documentation is Copyright (c) 1993-5 by Quercus Systems. All rights reserved. REXXLIB is commercial software, not Shareware. Except when included with the REXXLIB demo package, every copy must be appropriately licensed from Quercus Systems. Please do not copy without a license. THE CODE IN THIS DEMONSTRATION PACKAGE MAY BE USED FOR A TOTAL OF 30 DAYS. THE TIME NEED NOT BE CONSECUTIVE - YOU MAY CONTINUE USING IT UNTIL IT HAS BEEN USED 30 DIFFERENT DAYS. AT THAT TIME THE CODE WILL CEASE TO FUNCTION, AND YOU MUST GET A REGISTERED COPY IN ORDER TO CONTINUE USING REXXLIB. Permission is granted to distribute the executable portions (only) of REXXLIB together with application software upon payment of a registration fee, and subject to certain conditions of our redistribution policy. For more information contact: Quercus Systems P. O. Box 2157 Saratoga, CA 95070 Phone: (408) 867-7399, (800) 440-5944 Fax: (408) 867-7489 BBS: (408) 867-7488 For up-to-date information on the latest releases of REXXLIB and our other products, check our Web page, http://www.quercus-sys.com/ Online support is available on CompuServe (GO QUERCUS) Internet: 75300.2450@compuserve.com ═══ 2. Read me! ═══ ═══ 2.1. About this package... ═══ REXXLIB is a collection of over 150 functions designed to extend the capabilities of REXX in OS/2. It covers five principal areas: compound variable handling, interprocess communication, mathematical functions, OS/2 system services, and text-mode user interfacing. Here is a sample of what you can do with REXXLIB functions: o convert between different REXX date formats and do date arithmetic o copy, sort, or merge REXX "arrays" and compound variable collections, and read or write them from/to disk o make a list of all "tails" of a given compound variable o do "regular expression" searches in strings, files, and compound variable values o compute CRC values for files o change a file date/time stamp o add commonly-used REXX routines to "macro spaces" for shared use by other REXX programs and protection from end-user tampering o create and access local or remote OS/2 named pipes o evaluate standard transcendental math functions REXXLIB is commercial software, and continued use or inclusion with any other product for redistribution requires registration with Quercus Systems. The files in this package are distributed for demonstration only. However, all code is fully functional. THE CODE IN THIS DEMONSTRATION PACKAGE MAY BE USED FOR A TOTAL OF 30 DAYS. THE TIME NEED NOT BE CONSECUTIVE - YOU MAY CONTINUE USING IT UNTIL IT HAS BEEN USED 30 DIFFERENT DAYS. AT THAT TIME THE CODE WILL CEASE TO FUNCTION, AND YOU MUST GET A REGISTERED COPY IN ORDER TO CONTINUE USING REXXLIB. Registration of REXXLIB entitles you to a printed manual and support. The basic level of support is available electronically through CompuServe and the Quercus Systems BBS. Hotline telephone support is also available for an extra charge. See below for information on how to register REXXLIB. ═══ 2.2. Installing REXXLIB ═══ To install REXXLIB you need only copy the .DLL files (REXXLIB.DLL and RXWIN30.DLL) to a directory named in your system LIBPATH. Alternatively, you can copy all files on the distribution disk to a new directory on your hard disk, and add that directory to your LIBPATH. There are also online documentation files (.INF) that you can read with the VIEW command, and a number of sample programs. We recommend that you keep all of these online for easy reference while you are learning to use REXXLIB. Before you can run any REXX programs that use REXXLIB, you must register the functions with the operating system. The following statements placed in a REXX program will do this: call rxfuncadd 'rexxlibregister', 'rexxlib', 'rexxlibregister' call rexxlibregister call rxfuncadd 'w_register', 'rxwin30', 'rxwindow' call w_register NOTE!!! The third argument of RXFUNCADD is case sensitive. You must enter it in lower case exactly as shown. Instead of placing these statements in every program that uses REXXLIB, we recommend that you execute these from a REXX program that is run only once when the system is loaded. The easiest way to do this is with a STARTUP.CMD file. If you do not already have one, simply place the above lines in a file called STARTUP.CMD. Provide a REXX comment (/* ... */) as the first line of the file. And place the file in the root directory of your system boot drive. STARTUP.CMD will then run every time the system is loaded, and all of the REXXLIB functions will be registered. ═══ 2.3. Online documentation ═══ Online documentation for REXXLIB consists of two .INF files. These can be read with the VIEW command, like most other online OS/2 documentation. RLDEMO.INF contains complete descriptions of all REXXLIB functions except for RXWINDOW functions. RXWINDOW.INF contains the documentation for RXWINDOW functions. We have an 87-page printed manual that contains the same descriptive information on REXXLIB functions as the online document. It also contains an overview of each of the different function groups, as well as more detailed information on certain topics, such as semaphores, named pipes, common function calling conventions, and regular expressions. You need to register REXXLIB, as described below, in order to get the printed manual. If you would like a hardcopy reference summary of all REXXLIB functions, we highly recommend the REXX Reference Summary Handbook written by Dick Goran of CFS Nevada. This is a summary only, and is not a substitute for the REXXLIB manual, but it does cover all REXX language statements, functions, and REXX-related WorkPlace Shell usage information. The Handbook may be ordered directly from Quercus Systems. ═══ 2.4. Sample programs ═══ The SAMPLES directory contains a number of sample programs that illustrate REXXLIB usage. Read the file SAMPLES.DOC in the SAMPLES directory for an overview of the purpose of each file. One of the sample programs, called FL.CMD, is a text mode file manager program. It is fairly lengthy and provides a very good illustration of the use of RXWINDOW functions. Note that the sample programs assume that REXXLIB functions have already been registered. The samples will not run unless you have called the REXXLIBREGISTER function as discussed above. If you would like to contribute any programs that illustrate useful REXXLIB techniques, please feel welcome to upload them to our bulletin board or CompuServe. ═══ 2.5. Other Quercus Systems products ═══ Our primary emphasis is the development of REXX-related software and tools. In addition to REXXLIB, we have Personal REXX, which is a full implementation of the REXX language for DOS, OS/2, and Windows. Personal REXX for OS/2 includes all of the functions in REXXLIB, and a number of additional utilities and enhancements, such as global variables and better support for external data queues. It comes with complete printed documentation, and for many applications is significantly faster than IBM's REXX. We also have REXXTERM, which is a full-featured asynchronous communication package for DOS and OS/2. REXXTERM scripts can be written in REXX. REXXTERM provides a set of commands and functions that can be used to develop communications applications in REXX. Please contact us by any of the means listed below if you would like a copy of our newsletter or information on any of these products. You may also obtain further information by visiting our Web pages: http://www.quercus-sys.com ═══ 2.6. Disclaimers ═══ Quercus Systems excludes any and all implied warranties, including warranties of merchantability and fitness for a particular purpose, and limits your remedies to return of the software and manual to the location of original retail sale for replacement or refund. Quercus Systems specifically excludes any warranty coverage for incidental and consequential damages. We have provided this demonstration version of REXXLIB so that you can test the product thoroughly before any personal or commercial use. It is entirely your responsibility to ensure, when REXXLIB is used in conjunction with software you supply, that the combined product functions acceptably and does not cause undesirable side effects such as loss of data. In no case will Quercus Systems be responsible for damages alleged to be caused by your software in conjunction with REXXLIB. ═══ 2.7. Registering REXXLIB ═══ Two types of single-user registration are available: 1. Basic registration: includes an 87-page printed manual and electronic technical support through CompuServe and our bulletin board. The price is $20. 2. Full registration: includes hotline telephone and fax support, and priority service electronically, as well as the printed manual. This also includes the rights to redistribute REXXLIB as part of an application. The price is $50. A $3 shipping and handling fee (for U. S. customers) and any applicable sales taxes will be added to all orders. For special handling or customers outside the U. S., please contact us for the exact fee. A basic registration can be upgraded at any time to a full registration by payment of the difference in price current at the time of upgrade. Multiple copy discounts and site licensing terms are available by arrangement with Quercus Systems. You may place orders by credit card (Master Card, VISA, or Amex) using any of the following: 1. Telephone: (408) 867-7399 2. Fax: (408) 867-7489 3. Quercus Systems Bulletin Board: (408) 867-7488 (Send a message to "SYSOP".) 4. CompuServe: send mail to 75300,2450 5. Internet: send mail to 75300.2450@compuserve.com 6. MCI Mail: send mail to 394-6200 Please include your phone number, credit card number, and expiration date with any credit card order. For company POs please contact Quercus Systems for approval. Orders with payment by credit card or check (U. S. funds only, drawn on a U. S. bank) may also be sent to: Quercus Systems P. O. Box 2157 Saratoga, CA 95070 ═══ 2.8. Redistribution policy ═══ This REXXLIB demo package may be freely redistributed as long as all files are included and nothing is modified in any way. You may not include the demo package as a whole as part of another product, except for products, such as CD-ROMs, which consist entirely of demonstration software, shareware, or the like. If you distribute the demo package by itself you may not charge more than a reasonable amount as a copying fee. For a disk containing only REXXLIB, this would be at most $5. Please contact Quercus Systems for permission in other cases, such as inclusion with books. The executable portions (only) of REXXLIB may be included with commercial, "shareware", or "freeware" application software or applications distributed "in house" as long as you pay for one full registration and agree to the following terms and conditions: 1. Only executable .EXE and .DLL files may be included. No other copyrighted files of Quercus Systems (including all or any portion of the online documentation) may be included with the product. 2. Included files must not be modified in any way. In particular, embedded copyright notices must be left intact. 3. Your documentation should explicitly state that REXXLIB is copyrighted software belonging to Quercus Systems and is included with your software by permission of Quercus Systems. 4. Users of your product are not permitted to use REXXLIB except in conjunction with your product. Any further use by an end user (except for evaluation) requires purchase of at least a basic registration. 5. No part of REXXLIB may be included with other collections of tools or libraries intended primarily for use by programmers. ═══ 3. Alphabetical list of functions ═══ ═══ 3.1. ACOS ═══ ACOS(x) Summary: ACOS computes the arc cosine function. Arguments: x: A real number in the range -1<=x<1 Returns: The arc cosine of x, expressed in radians, in the range 0 to pi. For illegal values of x it returns "NAN". See also: ASIN, ATAN, ATAN2, COS, SIN, TAN ═══ 3.2. ARRAYCOPY ═══ ARRAYCOPY(fromstem,tostem,[from],[to],[count]) Summary: ARRAYCOPY copies all or part of a REXX "array", overlaying elements in a target array. Arguments: fromstem: The stem of the array that is the source of the copy. tostem: The stem of the array that is the target of the copy. from: The position in the first array at which the copy begins. The default is 1. to: The position in the second array at which the copy begins. The default is 1. count: The number of items to copy. The default is all elements to the end of the array. Returns: 1 if the operation is successful, otherwise 0 (for instance, if the source or target of the copy is not a valid "array"). Notes: For the purposes of this function a valid array is an integrally-indexed REXX compound variable whose first index is 1 and whose total length is held in the item with subscript 0. This function overlays existing values in the target array with values from the source array. Any elements in the source array which are uninitialized will also be uninitialized at the corresponding place in the target array. It is possible to use ARRAYCOPY to set all elements of a portion of an array to the same value. For instance, to set all elements of X. to 0, first set X.0 to 1 and X.1 to 0. Then call ARRAYCOPY with "X" as both the source stem and the target stem, the from value as 1, the to value as 2, and the count value as one less than the total number of values that are to be set to 0. See also: ARRAYDELETE, ARRAYINSERT, CVCOPY ═══ 3.3. ARRAYDELETE ═══ ARRAYDELETE(stem,from,[count]) Summary: ARRAYDELETE deletes one or more elements of a REXX "array" and shifts remaining elements down. Arguments: stem: The stem name of the array from which elements are to be deleted. from: The position in the array at which deletion begins. count: The number of elements to be deleted. The default is 1. Returns: 1 if the operation is successful, otherwise 0 (for instance, if the stem is not a valid "array"). Notes: For the purposes of this function a valid array is an integrally-indexed REXX compound variable whose first index is 1 and whose total length is held in the item with subscript 0. Any elements in the array which are uninitialized will also be uninitialized after being shifted to their new position. See also: ARRAYCOPY, ARRAYINSERT ═══ 3.4. ARRAYINSERT ═══ ARRAYINSERT(fromstem,tostem,[from],[to],[count]) Summary: ARRAYINSERT copies all or part of a REXX "array", inserting the elements into a target array. Arguments: fromstem: The stem of the array that is the source of the copy. tostem: The stem of the array that is the target of the copy. from: The position in the first array at which the copy begins. The default is 1. to: The position in the second array before which the copied values are inserted. The default is the end of the second array (after the last item). count: The number of items to copy. The default is all elements to the end of the array. + Returns: 1 if the operation is successful, otherwise 0 (for instance, if the source or target of the copy is not a valid "array"). Notes: For the purposes of this function a valid array is an integrally-indexed REXX compound variable whose first index is 1 and whose total length is held in the item with subscript 0. This function shifts existing values in the target array up by the number of new values inserted. Any elements in the source or target array which are uninitialized will also be uninitialized after being copied to their new position. See also: ARRAYCOPY, ARRAYDELETE ═══ 3.5. ARRAYSEARCH ═══ ARRAYSEARCH(searchstem,resultstem,pattern,[options],[from],[count]) Summary: ARRAYSEARCH places the indexes of a REXX array into a new array for each index where the corresponding variable value matches a pattern. Arguments: searchstem: Stem name of a REXX array to search. resultstem: A stem name that identifies the output array. pattern: A regular expression that is used to select tails. options: Changes the type of search performed from the default, which is a case-insesitive search using a regular expression pattern. The value can be a string consisting of one or more of the following: 'A' - avoid: select only items that do not satisfy the search conditions 'C' - search should be case sensitive 'F' - exact match required between pattern and first substring of target, except possibly for case, no regular expressions 'S' - simple search that does not use regular expressions 'X' - exact match required between pattern and target, except possibly for case, no regular expressions from: The position in the first array at which the search begins. The default is 1. count: The number of items to search. The default is all items to the end of the array. Returns: The number of tails found. Notes: Element 0 of the output array is set to the number of tails found. The input and output compound variables must be different. ARRAYSEARCH is usually faster than CVSEARCH when the compound variable to be searched has only positive integral "subscripts", as is the case, for instance, with the result of FILEREAD. You should avoid using a regular expression search by specifying 'S' in the options string if the pattern may contain any of the characters that have special meaning in regular expressions ("\", "^", "$", ".", ":", "*", "+", "?", "[", and "]"), unless the characters are escaped by being preceded with "\". This is especially likely to be a problem if the pattern is entered as user input at run time or consists of a file name. See also: CVSEARCH, CVTAILS ═══ 3.6. ARRAYSORT ═══ ARRAYSORT(stem,[first],[n],[start],[length],[order],[type],...) Summary: ARRAYSORT sorts an integrally-indexed REXX compound variable based on one or more fields in the array values. Arguments: stem: The stem of the compound variable to be sorted. first: The index of the first array element to be sorted (default is 1). n: The number of array elements to be sorted. (The default is to the end of the array.) start: The position in the value of the beginning of a sort field (default is 1). length: The length of a sort field. The default is 100. order: 'A' for ascending sort (default), 'D' for descending sort. type: 'C' for case-sensitive character sort (default), 'I' for case-insensitive character sort, 'N' for numeric sort. Returns: 1 if no error occurred, or 0 if some error occurred, such as insufficient memory or a non-numeric value was encountered during a numeric sort. Notes: Up to 10 separate fields can be specified, by repeating the start, length, order, and type arguments. The first specified field is the primary sort field. Secondary fields are considered only if all preceding fields compare equal. A character sort is defined by the standard ASCII collating sequence. Normally this is case-sensitive. The 'I' sort type can be used to request a case-insensitive sort. A numeric sort is defined by standard REXX comparison of numeric values. The order of elements in the original compound variable is changed based on the sort specification. As with any array, the number of elements in the array is expected to be found in the item with subscript 0. If the number of elements to be sorted is not specified, this count is used to identify the end of the array. ═══ 3.7. ASIN ═══ ASIN(x) Summary: ASIN computes the arc sine function. Arguments: x: A real number in the range -1<=x<1 Returns: The arc sine of x, expressed in radians, in the range -pi/2 to pi/2. For illegal values of x it returns "NAN". See also: ACOS, ATAN, ATAN2, COS, SIN, TAN ═══ 3.8. ATAN ═══ ATAN(x) Summary: ATAN computes the arc tangent function. Arguments: x: A real number. Returns: The arc tangent of x, expressed in radians, in the range -pi/2 to pi/2. For illegal values of x it returns "NAN". See also: ACOS, ASIN, ATAN2, COS, SIN, TAN ═══ 3.9. ATAN2 ═══ ATAN2(x,y) Summary: ATAN2 computes the arc tangent function. Arguments: x: A real number. y: A real number. Returns: The arc cosine of x/y, expressed in radians, in the range -pi/2 to pi/2. If both x and y are 0 it returns "NAN". See also: ACOS, ASIN, ATAN, COS, SIN, TAN ═══ 3.10. CHARSIZE ═══ CHARSIZE() Summary: CHARSIZE returns the height of the text mode character box. Returns: The height of the text mode character box in scan lines for the current screen mode. Notes: CHARSIZE can be used to provide appropriate values for the CURSORTYPE function. See also: CURSORTYPE ═══ 3.11. COS ═══ COS(x) Summary: COS computes the cosine function. Arguments: x: A real number (radians). Returns: The cosine of x. See also: ACOS, ASIN, ATAN, ATAN2, SIN, TAN ═══ 3.12. COSH ═══ COSH(x) Summary: COSH computes the hyperbolic cosine function. Arguments: x: A real number. Returns: The hyperbolic cosine of x. See also: SINH, TANH ═══ 3.13. CURSOR ═══ CURSOR([row],[col]) Summary: CURSOR moves the cursor to a specified position. Arguments: row: Row number on which to position the cursor. col: Column number on which to position the cursor. Returns: Two numbers, separated by a blank, which give the cursor location before any move. Notes: Row numbers start with 1 at the top of the screen or window. Column numbers start with 1 at the left hand side. If either the row or column number is omitted, the default is the current row or column. See also: CURSORTYPE ═══ 3.14. CURSORTYPE ═══ CURSORTYPE([start],[end],[visible]) Summary: CURSORTYPE returns the current cursor type, and possibly sets new values for the cursor type. Arguments: start: The line of the character box representing the top of the cursor. end: The line of the character box representing the bottom of the cursor. visible: A flag which is 1 if the cursor is visible and 0 if not. Returns: Three numbers, separated by blanks, which give the initial top and bottom lines of the cursor, and the visibility flag. Notes: The top line of the character cell is line 0. The CHARSIZE function can be used to get the height of the character box for the current video mode. If the visible argument is not specified, the visibility status of the cursor is not changed. See also: CHARSIZE, CURSOR ═══ 3.15. CVCOPY ═══ CVCOPY([fromstem],tostem) Summary: CVCOPY copies all values of a given REXX compound variable from one stem to another. Arguments: fromstem: A stem name for a REXX compound variable whose values are to be copied. tostem: A stem name for a REXX compound variable that is the target of the copy. Returns: 1 if the operation is successful, otherwise 0. Notes: The source and target of the copy can be arbitrary REXX compound variables. They do not need to be integrally subscripted arrays. Any existing values in the target compound variable are dropped before the operation begins, so that the source and target contain identical values at the end. If the source variable is not specified, any existing values in the target are simply dropped. See also: ARRAYCOPY, CVREAD, CVWRITE ═══ 3.16. CVREAD ═══ CVREAD(filename,tostem) Summary: CVREAD reads all values of a given REXX compound variable that have been saved in a disk file. Arguments: filename: The fully qualified name of a file that contains compound variable values which have been written by the CVWRITE function. tostem: A stem name for a REXX compound variable that receives the values read. Returns: 1 if the operation is successful, otherwise 0. Notes: The variable into which values are read can be an arbitrary REXX compound variable. It does not need to be an integrally subscripted array. Only a file which has been created with CVWRITE can be read with this function, since it must be in a special format. Any existing values in the target compound variable are dropped before the operation begins, so that the target variable contains at the end exactly the same values as the variable which was originally written to the file with CVWRITE. See also: CVCOPY, CVWRITE, VARREAD ═══ 3.17. CVSEARCH ═══ CVSEARCH(stem,tailstem,pattern,[options]) Summary: CVSEARCH places the "tails" of a compound variable into a REXX array for all tails where the corresponding variable value matches a pattern. Arguments: stem: Stem name of a compound variable to search. tailstem: A stem name that identifies the output array. pattern: A regular expression that is used to select tails. options: Changes the type of search performed from the default, which is a case-insesitive search using a regular expression pattern. The value can be a string consisting of one or more of the following: 'A' - avoid: select only items that do not satisfy the search conditions 'C' - search should be case sensitive 'F' - exact match required between pattern and first substring of target, except possibly for case, no regular expressions 'S' - simple search that does not use regular expressions 'X' - exact match required between pattern and target, except possibly for case, no regular expressions Returns: The number of tails found. Notes: Element 0 of the output array is set to the number of tails found. The input and output compound variables must be different. You should avoid using a regular expression search by specifying 'S' in the options string if the pattern may contain any of the characters that have special meaning in regular expressions ("\", "^", "$", ".", ":", "*", "+", "?", "[", and "]"), unless the characters are escaped by being preceded with "\". This is especially likely to be a problem if the pattern is entered as user input at run time or consists of a file name. See also: ARRAYSEARCH, CVTAILS ═══ 3.18. CVTAILS ═══ CVTAILS(stem,tailstem,[pattern],[options]) Summary: CVTAILS places the "tails" of one compound variable into a REXX array, optionally using a pattern to select tails. Arguments: stem: A stem name whose tails are to be found. tailstem: A stem name that identifies the output array. pattern: A regular expression that is used to select tails. options: Changes the type of search performed from the default, which is a case-insesitive search using a regular expression pattern. The value can be a string consisting of one or more of the following: 'A' - avoid: select only items that do not satisfy the search conditions 'C' - search should be case sensitive 'F' - exact match required between pattern and first substring of target, except possibly for case, no regular expressions 'S' - simple search that does not use regular expressions 'X' - exact match required between pattern and target, except possibly for case, no regular expressions Returns: The number of tails found. Notes: The tail of a compound variable is the character string following the first "." in the fully resolved variable name. Such character strings can contain any arbitrary combination of characters, including blanks, and can even be a null string. The TAILS function finds all such tails associated with a given stem and assigns them to successive elements of another compound variable so that one can easily iterate through the list. If a pattern is used to select tails, only the tail part of the compound variable (following the first period) is considered for matching. Element 0 of the output array is set to the number of tails found. The input and output compound variables must be different. You should avoid using a regular expression search by specifying 'S' in the options string if the pattern may contain any of the characters that have special meaning in regular expressions ("\", "^", "$", ".", ":", "*", "+", "?", "[", and "]"), unless the characters are escaped by being preceded with "\". This is especially likely to be a problem if the pattern is entered as user input at run time or consists of a file name. See also: CVSEARCH ═══ 3.19. CVWRITE ═══ CVWRITE(filename,fromstem) Summary: CVWRITE writes all values of a given REXX compound variable to a disk file. Arguments: filename: The fully qualified name of a file into which compound variable values are to be written. fromstem: A stem name for a REXX compound variable that contains the values to be written. Returns: 1 if the operation is successful, otherwise 0. Notes: The variable from which values are taken can be an arbitrary REXX compound variable. It does not need to be an integrally subscripted array. Only the tails of the source variable are saved in the file. The stem name is not saved, since a new name will be supplied when the file is read with CVREAD. If the file to be written already exists it is set to 0 length before the operation begins, so that its original contents are lost. See also: CVCOPY, CVREAD, VARWRITE ═══ 3.20. DATECONV ═══ DATECONV(date,input,[output]) Summary: DATECONV converts a date string from one format to another. Arguments: date: A string representing a valid date. input: 'B', 'C', 'D', 'E', 'J', 'N', 'O', 'S', or 'U'. output: 'B', 'C', 'D', 'E', 'J', 'M', 'N', 'O', 'S', 'U', or 'W'. Returns: The date represented in the specified output format. A null string is returned if the date is not in the format specified by the input argument. Notes: The input and output formats are the same as those used for the DATE built-in function. The default output format is 'N'. If you need to do arithmetic on dates (e. g. to find the date 60 days from now), the best way is to first convert to the "base date" format ('B'), do the arithmetic, then convert back. ═══ 3.21. DELAY ═══ DELAY(duration) Summary: DELAY suspends program execution for a specified duration. Arguments: duration: Length of time in seconds to suspend execution. Returns: Always returns 1. Notes: The delay period can be specified as a fractional number. DELAY is accurate to within about a tenth of a second. ═══ 3.22. DETAB ═══ DETAB(string,[spaces]) Summary: DETAB removes tab characters from a string and replaces them with an appropriate number of spaces. Arguments: string: The string from which tabs are to be removed. spaces: The number of spaces between each tab stop. The default is 8. Returns: The input string with tab characters removed. Notes: A tab character is ASCII '09'x. Tab characters are often inserted in ASCII data files by text editors and are also common in files transferred from Unix systems. Unlike Unix, however, OS/2 does not ordinarily equate tabs to spaces, so it may be necessary to remove them with DETAB. See also: ENTAB ═══ 3.23. DOSAPPTYPE ═══ DOSAPPTYPE(filename) Summary: DOSAPPTYPE indicates whether a given executable file is an OS/2 fullscreen, windowable, or PM application, and whether or not it is a 32-bit program. Arguments: filename: The name of an executable file. Returns: Three numbers, separated by blanks. The first number is interpreted as follows: 0 - application type not specified in file 1 - program is OS/2 full-screen only 2 - program can execute in PM text-mode window 3 - application is a PM program 16 - program is a DLL 32 - program is DOS-only The second number is 1 if the program has been "bound" so that it can execute in DOS mode, otherwise 0. The third number is 1 if the application is a 32-bit program, otherwise 0. Notes: "0 0 0" will be returned for a non-executable file. ═══ 3.24. DOSBOOTDRIVE ═══ DOSBOOTDRIVE() Summary: DOSBOOTDRIVE returns the disk letter of the system boot drive. Arguments: none Returns: The disk letter in upper case of the system boot drive (without trailing ':'). ═══ 3.25. DOSCD ═══ DOSCD([drive]) Summary: DOSCD returns the current directory on a specified drive. Arguments: drive: Letter that designates the drive of interest. (Default is the current drive.) Returns: The name of the current directory on the specified (or current) drive. Notes: DOSCD returns a null string if the specified drive is invalid or not ready. This is one way to test whether a floppy drive has a disk in it. See also: DOSCHDIR, DOSVOLUME ═══ 3.26. DOSCHDIR ═══ DOSCHDIR(pathname) Summary: DOSCHDIR sets the current directory on a particular drive. Arguments: pathname: The name of a directory path to be made the current directory. Returns: 1 if the operation was successful, otherwise 0. Notes: If a drive letter followed by a colon is included in the path name, the current directory on the designated drive is changed. Otherwise, the change applies to the current drive. See also: DOSCD, DOSDRIVE ═══ 3.27. DOSCHMOD ═══ DOSCHMOD(filename,[turnon],[turnoff]) Summary: DOSCHMOD changes a file's attribute bits. Arguments: filename: The fully qualified name of a file whose attributes are to be changed. turnon: One or more of 'H', 'S', 'R', or 'A', indicating attributes to be added. turnoff: One or more of 'H', 'S', 'R', or 'A', indicating attributes to be removed. Returns: 1 of the operation was successful, otherwise 0. Notes: The attributes affected by DOSCHMOD are Hidden ('H'), System ('S'), Read-only ('R'), and Archive ('A'). The file name cannot contain wildcard characters. ═══ 3.28. DOSCOMMANDFIND ═══ DOSCOMMANDFIND(commandname) Summary: DOSCOMMANDFIND searches the current directory and the system path to locate a particular command. Arguments: commandname: A command name. Returns: The fully qualified name of the command file if it is found, otherwise a null string. Notes: If a disk letter or directory is included in the command name, only the specified disk and directory will be searched. Otherwise the current directory is searched, followed by each directory listed in the path. If a specific extension is included in the command name, only that extension will be searched for. Otherwise DOSCOMMANDFIND searches for files with an extension of COM, EXE, or CMD. The search stops as soon as a directory is found that contains a matching file. If no extension was specified, and the directory contains more than one file with an appropriate extension, the name is determined by the order in which the system handles commands, where COM has highest priority, followed by EXE, followed by CMD. Wildcard characters cannot be specified in the command name. The command name cannot contain a period unless it is used to indicate the presence of an extension. See also: DOSPATHFIND ═══ 3.29. DOSCOPY ═══ DOSCOPY(sourcename,[targetname],[mode],[options]) Summary: DOSCOPY copies a file. Arguments: sourcename: The name of the file to be copied. targetname: The name of the target of the copy operation. mode: A letter ('R', 'A', or 'N') which indicates whether the target file (if it already exists) should be replaced, appended, or left unchanged. options: A string consisting of one or more of the following: 'V' - Verify the data after copying and indicate an error if the copied data does not match. Returns: 0 if the operation is successful, otherwise an error code. Possible error codes include: 2 - source file not found 3 - source or target path not found 5 - target file exists but 'A' or 'R' mode not specified 32 - sharing violation for source or target file 108 - source or target drive locked 112 - disk full 206 - invalid source or target file name 267 - source name is a directory 282 - extended attributes not supported for target Notes: If the target of the copy operation is not specified, it is a file in the current directory having the same name as the source of the copy. Wildcard characters ('*' and '?') are not allowed in the source or target names. By default, a copy fails if the target already exists. This is a mode of 'N'. If the mode is 'A', and the target exists, the data from the source is appended to the target. If the mode is 'R' and the target exists, it is replaced. If the target is read-only, the copy fails regardless of mode. Attributes of the source (last modification date, etc.) are copied to the target unless the target already exists and is being appended. Extended attributes are copied from the source to the target unless the target already exists and is being appended. If the volume that holds the target does not support extended attributes data will be copied without extended attributes. It may be faster to use the DOSCOPY function instead of the system COPY command if the default execution environment is not CMD.EXE, since the need to start a new process can be avoided. It is also safer, since unlike the COPY command, DOSCOPY does not replace an existing target unless explicitly requested to do so. If an error occurs during copying, the target file is deleted, unless it was being appended, in which case it is restored to its original size. ═══ 3.30. DOSCREAT ═══ DOSCREAT(filename) Summary: DOSCREAT creates a new file or sets an existing file to 0 length. Arguments: filename: The fully qualified name of a file to be created. Returns: 1 if the operation was successful, otherwise 0. Notes: If the specified file does not exist, it is created as an empty file (0 bytes in length). If it already exists, it is truncated to 0 bytes in length, and its existing contents are lost. See also: DOSDEL, DOSFSIZE ═══ 3.31. DOSDEL ═══ DOSDEL(filename) Summary: DOSDEL deletes a file. Arguments: filename: The fully qualified name of a file to be deleted. Returns: 1 if the operation was successful, otherwise 0. Notes: The file name cannot contain wildcard characters. See also: DOSCREAT ═══ 3.32. DOSDIR ═══ DOSDIR([filespec],[output],[search],[mask],[position]) Summary: DOSDIR returns directory information. Arguments: filespec: A file specification, which may contain a drive letter and path information and wildcard characters in the file name. output: A string consisting of one or more of 'N', 'S', 'D', 'T', and 'A'. search: A string consisting of one or more of 'H', 'S', and 'D'. mask: A string consisting of one or more of 'H', 'S', 'D', 'R', and 'A'. position: Directory position information returned by DOSDIRPOS. Returns: A string that contains requested directory information about a file. If no file can be found that matches the filespec, a null string is returned. Notes: If the filespec contains drive or path information, the specified drive or directory is searched. Otherwise, the current directory of the current drive is searched. The filespec may contain wildcard characters in the name or extension, in which case the first matching file is located. If the filespec is omitted, it is assumed that a previous call was made to DOSDIR specifying a filespec with wildcard characters, and the next matching file is located. The output argument is used to specify the contents and order of the directory information returned, as follows: 'N' - the name and extension of the file, in the form name.ext 'S' - the size of the file in bytes 'D' - the date of the last update of the file, in the form mm/dd/yy 'T' - the time of the last update of the file, in the form hh:mm:ss 'A' - a string of characters indicating the file's attributes: 'R' for a read-only file 'H' for a hidden file 'S' for a system file 'D' if the file is a directory 'A' if the file's archive bit is set '-' if the file has none of the above attributes If the output argument is omitted or is null, all of the above information is returned by DOSDIR, in the above order. Otherwise, the order in which the characters appear determines the order in which the information is returned. If the search argument is omitted or is null, DOSDIR searches only for "normal" files: hidden files, system files, and directory files are ignored. If specified, the search argument is a string of characters that can be used to extend the search to special files: 'H' - hidden files 'S' - system files 'D' - directory files If a filespec is not supplied and DOSDIR is searching for the next match of a previously-specified pattern, the search argument is ignored. If specified, the mask argument is a set of characters that can be used to restrict the search to files with particular attribute bits set: 'R' - read-only files 'H' - hidden files 'S' - system files 'D' - directory files 'A' - files with the archive bit set If a filespec is not supplied, DOSDIR searches for the next file matching the pattern that was last used. The position argument can be used to cause a search for the next file matching a previously used pattern, allowing intervening calls to DOSDIR using other patterns. The position argument is a string returned by the DOSDIRPOS function that represents the current position in a directory search. See also: DOSDIRCLOSE, DOSDIRPOS, DOSFILEINFO ═══ 3.33. DOSDIRCLOSE ═══ DOSDIRCLOSE(position) Summary: DOSDIRCLOSE is used to tell the system that a DOSDIR search for files is completed. Arguments: position: Directory position information returned by DOSDIRPOS. Returns: 0 if the operation was successful, otherwise 1. Notes: Directory searches under OS/2 require the use of a directory handle, which must be allocated when a directory search begins and freed when a directory search has finished. DOSDIR will normally obtain and free directory handles as necessary, but in one special case it cannot be determined that you are finished with a directory handle, so you must use DOSDIRCLOSE to tell the system to free up the handle. This happens when your program uses DOSDIRPOS to save the handle of a directory search. If you do not later reuse the handle to continue the search to completion (that is until DOSDIR indicates that there are no more matching files), you should use DOSDIRCLOSE to tell the system that you are finished with the directory handle and that it can be freed. See also: DOSDIR, DOSDIRPOS ═══ 3.34. DOSDIRPOS ═══ DOSDIRPOS() Summary: DOSDIRPOS returns a string representing the current DOSDIR directory position status. Returns: A string that represents the current position in a DOSDIR search. Notes: DOSDIRPOS is provided to allow "nested" directory searches using DOSDIR. That is, if you want to use a new file spec with DOSDIR during a search but later resume the original search, you can save your position by calling DOSDIRPOS and later passing the returned position as an argument to DOSDIR when you want to resume the search. If you use DOSDIRPOS and subsequently do not call DOSDIR until it returns a null string (which indicates no more files were found), you should call DOSDIRCLOSE to indicate to the system that the search is completed. See also: DOSDIR, DOSDIRCLOSE ═══ 3.35. DOSDISK ═══ DOSDISK(option,[drive]) Summary: DOSDISK returns information about the specified disk. Arguments: option: One of 'A', 'B', 'C', 'F', 'S', 'T', or 'U'. drive: Letter that designates the drive of interest. (Default is the current drive.) Returns: Depends on the selected option: A - the number of available clusters on the disk. B - the number of bytes per disk sector. C - the number of clusters on the disk. F - the number of free (unused) bytes on the disk. S - the number of sectors per disk cluster. T - the total number of bytes on the disk. U - the total number of bytes in use on the disk. -1 is returned if the drive is invalid or not ready. See also: PCDISK ═══ 3.36. DOSDRIVE ═══ DOSDRIVE([newdrive]) Summary: DOSDRIVE returns the current drive letter and optionally changes the current drive. Arguments: newdrive: Letter that identifies the new default drive. Returns: The letter of the current default drive. Notes: If a new drive is not specified, DOSDRIVE simply returns the current drive letter. See also: DOSCHDIR ═══ 3.37. DOSEALIST ═══ DOSEALIST(filename,[namestem],[valuestem],[flagstem]) Summary: DOSEALIST places information about the extended attributes of a file into one or more compound variables. Arguments: filename: The fully qualified name of a file. namestem: A stem name for the compound variable that receives the name of an extended attribute. valuestem: A stem name for the compound variable that receives the value of an extended attribute. flagstem: A stem name for the compound variable that receives an extended attribute flag. Returns: The number of extended attributes that exist for the specified file. -1 will be returned if the file does not exist or a problem occurs retrieving the extended attributes. Notes: Element 0 of each compound variable array is set to the number of elements in the array. The extended attribute flag is a 1-byte value defined by the operating system. See also: DOSEASIZE ═══ 3.38. DOSEASIZE ═══ DOSEASIZE(filename) Summary: DOSEASIZE returns the total size of a file's extended attributes. Arguments: filename: The fully qualified name of a file. Returns: The total size of a file's extended attributes. -1 will be returned if the file does not exist or a problem occurs retrieving the extended attributes. Notes: DOSEASIZE returns the same number that is reported by the /n option of the DIR command. See also: DOSEALIST ═══ 3.39. DOSEDITNAME ═══ DOSEDITNAME(source,pattern) Summary: DOSEDITNAME is used primarily to construct new file names based on an input file name and a pattern. Arguments: source: A character string. pattern: A character string in which "*", "?", and "." play special roles. Returns: A new character string based on the source string and the pattern. Notes: Characters are copied one at a time from the pattern to the result. Every time a character (other than "*", "?", or ".") is copied from the pattern, a pointer advances in the source string. The operation stops when the end of the pattern is reached. If "?" is found in the pattern, the character in the source string indicated by the pointer is copied to the result, and the pointer is advanced. However, if a period or the end of the source string is reached, nothing is copied. If "*" is found in the pattern, characters of the source string are copied to the result until the character following "*" (if any) in the pattern is found in the source (irrespective of case). If "." is found in the pattern, the pointer in the source string is advanced to the character after the next ".". Examples: DOSEDITNAME("foo.bar", "*.bak") -> foo.bak DOSEDITNAME("abcd.efg", "A*D.xyz") -> AbcD.xyz DOSEDITNAME("abcd.efg", "123.*") -> 123.efg DOSEDITNAME("abcd.efg", "1*2.*") -> 1bcd.efg2. See also: DOSTEMPNAME ═══ 3.40. DOSENV ═══ DOSENV(string) Summary: DOSENV returns the value of the specified environment variable. Arguments: string: Name of the environment variable of interest. Returns: The value of the specified environment variable. See also: DOSENVLIST, DOSENVSIZE ═══ 3.41. DOSENVLIST ═══ DOSENVLIST(liststem) Summary: DOSENVLIST places the list of current environment variable names in a specified REXX compound variable. Arguments: liststem: A stem name for the compound variable that receives the list of system environment variables. Returns: The number of environment variables found. Notes: Element 0 of the compound variable array is set to the number of elements in the array. Either the DOSENV function or the VALUE function can be used to retrieve the value of any environment variable. See also: DOSENV ═══ 3.42. DOSENVSIZE ═══ DOSENVSIZE() Summary: DOSENVSIZE returns the total size of the current environment area and the amount of free space remaining. Returns: Two numbers, separated by blanks. The first number is the current size of the environment area and the second is the amount of free space. Both values are in bytes. Notes: Unless no more system memory is available, the environment area will usually grow if new variables are added. See also: DOSENV, DOSENVLIST ═══ 3.43. DOSFDATE ═══ DOSFDATE(filename,[newdate],[newtime]) Summary: DOSFDATE changes the date and time recorded as the date/time of the last modification to a file. Arguments: filename: The fully qualified name of a file whose last modification date is to be changed. newdate: The new date. newtime: The new time. Returns: 1 if the operation was successful, otherwise 0. Notes: The new date is specified in the "standard" date format as returned by the DATE function: . For instance, 19930131 is January 31, 1993. The date must be on or after January 1, 1980. The new time is specified as (24-hour format, but no punctuation). The appropriate number of digits must be specified for each field. For instance, 1:01AM is 010100. If neither a newdate nor a newtime is specified, the current date and time are used. This implies that DOSFDATE should not be used simply to determine the time stamp of a file, since it will be changed. Use DOSDIR or DOSFILEINFO to get the time stamp without changing it. See also: DOSDIR, DOSFILEINFO ═══ 3.44. DOSFILEHANDLES ═══ DOSFILEHANDLES([handles]) Summary: DOSFILEHANDLES reports the maximum number of system file handles that may be opened in a given process and optionally changes the number. Arguments: handles: The new maximum number of open file handles. Returns: The current maximum number of open file handles. Notes: File handles are used every time a file is accessed with REXX I/O functions such as CHARIN/CHAROUT, LINEIN/LINEOUT, CHARS, LINES, and STREAM. Other services invoked indirectly from REXX may also create open file handles. At least 3 handles are usually in use for the the standard input stream, standard output stream, and standard error stream. Many difficult to diagnose program errors can occur if the maximum number of file handles is too low. DOSFILEHANDLES may be used to protect against such problems. A value like 50 or 100 is not unreasonable. However, many problems can be solved simply by closing REXX files as soon as a program is done with them. ═══ 3.45. DOSFILEINFO ═══ DOSFILEINFO(filename,option) Summary: DOSFILEINFO returns certain information about a specified file. Arguments: filename: The fully qualified name of a file. option: 'A', 'C', 'S', or 'W' Returns: Depends on the selected option: 'A' - The date and time the file was last accessed. 'C' - The date and time the file was created. 'S' - The allocated size of the file. 'W' - The date and time the file was last written. Notes: The date and time the file was created or last accessed is available only for files on HPFS disks. The information is returned in the form "mm/dd/yy hh:mm:ss". The date and time the file was last written is the same value as returned by DOSFDATE. The allocated size of the file reflects the total number of complete file allocation units, so will generally be larger that the current file size as reported by the DIR command or the DOSDIR function. See also: DOSDIR, DOSFDATE ═══ 3.46. DOSFILESYS ═══ DOSFILESYS([drive]) Summary: DOSFILESYS returns the type of file system on a specified drive. Arguments: drive: A valid disk drive letter. The default is the current drive. Returns: The name of the file system as reported by the installable file system driver. Notes: Possible names include "FAT", "HPFS", "CDFS", and "HPOFS". This call can be used, for example, to identify a CD-ROM drive ("CDFS") if a disk is loaded in the drive. See also: DOSVOLINFO ═══ 3.47. DOSFNAME ═══ DOSFNAME(filename) Summary: DOSFNAME returns the fully qualified name of the specified file, including a drive specifier, path specification, name, and extension. Arguments: filename: A partially qualified file name. Returns: The fully qualified name of the file, or a null string if there is a syntax error in the name. Notes: DOSFNAME is useful because it fills in any missing drive or path information, and it converts relative paths to absolute paths that start at the root directory. Neither the specified file name nor any path components need actually exist, but a null string is returned if there is a syntax error in the name. For example, if the current drive is the C: drive and the current directory is %PROGRAMS, DOSFNAME('abc.def') -> c:%programs%abc.def DOSFNAME('c:object%xyz.obj') -> c:%programs%object%xyz.obj DOSFNAME('..%autoexec.bat') -> c:%autoexec.bat See also: PARSEFN, VALIDNAME ═══ 3.48. DOSFSIZE ═══ DOSFSIZE(filename,[newsize]) Summary: DOSFSIZE returns the actual size of a file and may optionally change the size. Arguments: filename: The fully qualified name of a file. newsize: New size of the file. Returns: Original size of the file, or 0 if the file did not exist but was created, or -1 if there was an error obtaining the original size. Notes: If the file does not exist but a new size is specified, the file is created. No error indication is provided if additional space for the file cannot be allocated. You can check for successful reallocation by calling DOSFSIZE again. See also: DOSDIR, DOSFILEINFO ═══ 3.49. DOSISDEV ═══ DOSISDEV(filename) Summary: DOSISDEV indicates whether the specified name represents a device. Arguments: filename: A fully qualified file system identifier. Returns: 1 if the specified name is a device, such as CON, PRN, LPT1, NUL, etc., otherwise 0. Notes: DOSISDEV is useful for validating file names supplied to programs. DOSISDEV returns 1 for names such as "\XYZ\PRN", which is considered to refer to the PRN device rather than a file. See also: DOSISFILE, DOSISPIPE ═══ 3.50. DOSISDIR ═══ DOSISDIR(filename) Summary: DOSISDIR indicates whether the specified name is a directory. Arguments: filename: A fully qualified file system identifier. Returns: 1 if the specified name is a directory, otherwise 0. Notes: The file name should not include a trailing "%". ═══ 3.51. DOSISFILE ═══ DOSISFILE(filename) Summary: DOSISFILE indicates whether the specified name represents a disk file. Arguments: filename: A fully qualified file system identifier. Returns: 1 if the identifier represents an existing file or 0 if the file does not exist, is a device, or is a named pipe. See also: DOSISDEV, DOSISPIPE ═══ 3.52. DOSISPIPE ═══ DOSISPIPE(filename) Summary: DOSISPIPE indicates whether the specified name represents a named pipe. Arguments: filename: A fully qualified file system identifier. Returns: 1 if the identifier represents a named pipe, or 0 otherwise. See also: DOSISDEV, DOSISFILE ═══ 3.53. DOSKILLPROCESS ═══ DOSKILLPROCESS(pid,[option]) Summary: DOSKILLPROCESS issues a termination request for a specified process. Arguments: pid: The numeric process identifier of the process to be terminated (in decimal). option: 'P' or 'T' Returns: 1 if the system successfully flagged the process for termination, otherwise 0. Notes: The 'P' option, which is the default, means there is no restriction on the process to be terminated. However, only the indicated process is terminated, and not any of its descendants. The 'T' option means the process must be the current process or one of its descendants. All descendants of the indicated process are terminated. Even if the return code is 1 the process may not actually be terminated by the system. Any process can intercept the termination request and refuse to terminate, or the system may be unable to terminate it for other reasons. DOSKILLPROCESS can be used to stop sessions using the PID that is returned by DOSSWITCHLIST. However, child processes are not terminated when a parent is. (Unless the 'T' option was selected.) For example, a program executing from an OS/2 windowed command session is not terminated when the command session (usually CMD.EXE) itself is. See also: DOSPID, DOSPIDLIST, DOSPROCINFO, DOSSWITCHLIST ═══ 3.54. DOSMAKEDIR ═══ DOSMAKEDIR(pathname) Summary: DOSMAKEDIR creates one or more new directories. Arguments: pathname: The fully qualified name of the directory to create. Returns: 1 if the operation is successful, otherwise 0. Notes: Unlike DOSMKDIR, DOSMAKEDIR will create any intermediate subdirectories which are required. DOSMAKEDIR will return 1 as long as the requested directory structure exists at the end, even if it already existed. See also: DOSMKDIR, DOSRMDIR ═══ 3.55. DOSMAXPATH ═══ DOSMAXPATH() Summary: DOSMAXPATH returns the maximum acceptable length of a fully qualified path name. Arguments: none Returns: The maximum acceptable length of a fully qualified path name. Notes: The value returned is a system-wide constant. An actual file system (e. g. FAT) may have a lower limit. ═══ 3.56. DOSMKDIR ═══ DOSMKDIR(pathname) Summary: DOSMKDIR creates a new directory. Arguments: pathname: The fully qualified name of the directory to create. Returns: 1 if the operation was successful, otherwise 0. Notes: Unlike DOSMAKEDIR, DOSMKDIR will fail if any intermediate component of the directory path does not exist. DOSMKDIR will return 0 if the requested directory structure already exists. See also: DOSMAKEDIR, DOSRMDIR ═══ 3.57. DOSPATHFIND ═══ DOSPATHFIND(filename,[envvar]) Summary: DOSPATHFIND searches a list of directories for a specified file. Arguments: filename: The name of a file to search for. envvar: The name of an environment variable containing a list of directories. The default is 'PATH'. Returns: The fully qualified name of the file, if found, otherwise a null string. Notes: The search process is similar to the process carried out when searching for an executable file. If the fileid contains a drive or path specification, DOSPATHFIND looks only there. Otherwise, DOSPATHFIND looks for the file in the current directory and then in each of the directories specified in the list. The envvar argument lets you specify the name of another environment variable, other than the default of PATH, to use to determine the list of directories to search. See also: DOSCOMMANDFIND ═══ 3.58. DOSPID ═══ DOSPID() Summary: DOSPID returns the process id (PID). Returns: The process id (PID) of the current process. This is a number which uniquely identifies the process within the system. See also: DOSPIDLIST, DOSPROCINFO ═══ 3.59. DOSPIDLIST ═══ DOSPIDLIST(pidstem,[namestem],[parentstem],[sesssionstem]) Summary: DOSPIDLIST places information about currently active processes into one or more compound variables. Arguments: pidstem: A stem name for the compound variable that receives the list of process identifiers. namestem: A stem name for the compound variable that receives the list of process names. parentstem: A stem name for the compound variable that receives the list of parent process identifiers. sessionstem: A stem name for the compound variable that receives the list of session identifiers. Returns: The number of processes found. Notes: A process identifier is a decimal number which uniquely represents each process in the system. The parent process is the process which created a given process. The session identifier is a decimal number which represents a group of related processes. (A session usually consists of the family of processes created by an instance of CMD.EXE.) The process name is the fully qualified name of the program associated with the process. Element 0 of each compound variable array is set to the number of elements in the array. See also: DOSKILLPROCESS, DOSPID, DOSPROCINFO, DOSSWITCHLIST ═══ 3.60. DOSPRIORITY ═══ DOSPRIORITY([delta],[class],[pid]) Summary: DOSPRIORITY returns the current priority level and priority class of a specified process. Arguments: delta: A signed number from -31 to +31 that indicates a requested change to the priority level (default 0). class: A number from 0 to 4 that indicates the requested priority class (default 0). pid: The numeric identifier of the process for which priority is to be returned or changed. Returns: Two numbers indicating the priority level and priority class of thread 1 of the specified process before any change is applied. Notes: A priority level has a minimum value of 0 and a maximum of 31. In order of increasing priority, the valid priority classes are: 1 - "idle-time" 2 - "regular" 3 - "time critical" 4 - "server" Specifying a class of 0 indicates no change. The target process must be a descendant of the requesting process if a change is made, but the priority of any process can be queried. See also: DOSPID, DOSPIDLIST, DOSPROCINFO ═══ 3.61. DOSPROCINFO ═══ DOSPROCINFO(option,[pid]) Summary: DOSPROCINFO returns information about a specified process. Arguments: option: 'N', 'P', or 'S' pid: The numeric identifier of the process for which information is requested in decimal (default is the current process). Returns: Depends on the selected option: 'N' - The fully qualified name of the program associated with the process. 'P' - The process identifier of the parent of the process. 'S' - The session identifier of the process. Notes: A process identifier is a decimal number which uniquely represents each process in the system. The parent process is the process which created a given process. The session identifier is a decimal number which represents a group of related processes. (A session usually consists of the family of processes created by an instance of CMD.EXE.) The process name is the fully qualified name of the program associated with the process. See also: DOSPID, DOSPIDLIST ═══ 3.62. DOSRENAME ═══ DOSRENAME(filename1,filename2) Summary: DOSRENAME renames a file or directory. Arguments: filename1: The name of the file or directory to rename. filename2: The new name of the file or directory. Returns: 1 if the operation was successful, otherwise 0. Notes: The names should contain any necessary drive and path information, but should not contain wildcard characters. DOSRENAME allows a file to be "moved" from one directory to another on the same drive. ═══ 3.63. DOSRMDIR ═══ DOSRMDIR(directory) Summary: DOSRMDIR deletes the specified directory. Arguments: directory: The name of the directory to be removed. Returns: 1 if the operation was successful, otherwise 0. Notes: The specified directory cannot be removed unless it contains no files or subdirectories. It must also not be the current directory of any process in the system. See also: DOSMKDIR ═══ 3.64. DOSSESSIONTYPE ═══ DOSSESSIONTYPE() Summary: DOSSESSIONTYPE returns the type of the current session. Arguments: none. Returns: A number indicating type of session, which can be: 0 - full-screen 2 - VIO window 3 - PM session 4 - detached session ═══ 3.65. DOSSWITCHLIST ═══ DOSSWITCHLIST(titlestem,[pidstem],[sessionstem],[handlestem],[typestem], [visibilitystem]) Summary: DOSSWITCHLIST places information about sessions in the system "switch list" into one or more compound variables. Arguments: titlestem: A stem name for the compound variable that receives the title of the session. pidstem: A stem name for the compound variable that receives the list of process identifiers. session stem: A stem name for the compound variable that receives the list of session identifiers. handle stem: A stem name for the compound variable that receives the list of window handles. typestem: A stem name for the compound variable that receives the list of program types. visibilitystem: A stem name for the compound variable that receives the list of visibility flags. Returns: The number of switch list entries found. Notes: Not all processes listed by DOSPIDLIST will be returned by DOSSWITCHLIST. Only those processes which are included in the switch list are returned. Conversely, not all processes listed by DOSSWITCHLIST will be returned by DOSPIDLIST. For instance, processes corresponding to DOS or Windows sessions are not shown by DOSPIDLIST. The session title is the string that occurs in the title bar of the session's window and in the switch list. All "white space" characters between words in the title are removed, except for a single blank. Element 0 of each compound variable array is set to the number of elements in the array. The program type is a number which indicates the type of the session. It may be: 0 - OS/2 full screen 2 - OS/2 window 3 - PM application 4 - DOS or Windows full screen 7 - DOS or Windows window The visibility flag is a number that indicates whether the item is actually visible in the switch list. It may be: 1 - invisible 2 - grayed 4 - fully visible See also: DOSKILLPROCESS, DOSPIDLIST ═══ 3.66. DOSTEMPNAME ═══ DOSTEMPNAME(namepattern) Summary: DOSTEMPNAME constructs a temporary file name for a new file from a given pattern. Arguments: namepattern: A character string consisting of valid file name characters and "?". Returns: A valid file name that is guaranteed not to exist on the default or specified drive. Notes: Temporary names are constructed by replacing all "?" characters in the name pattern with the digits of a number that starts at 1 and is incremented by 1 until a name is created that does not correspond to an existing file on the default or specified drive. The replacement process is performed from right to left on both the number and the pattern. For instance, if namepattern is "this??.tmp", the first name to be tried is "this01.tmp", followed by "this02.tmp", and so on. If no unused name can be found, the function returns a null string. See also: DOSEDITNAME ═══ 3.67. DOSTID ═══ DOSTID() Summary: DOSTID returns the thread id (TID). Returns: The thread id (TID) of the current thread. This is a number which uniquely identifies the thread within the current process. See also: DOSPID ═══ 3.68. DOSVOLINFO ═══ DOSVOLINFO([disk],[option]) Summary: DOSVOLINFO returns information about a specified disk volume. Arguments: disk: The letter that identifies the disk for which information is requested. Default is the current disk. option: A letter that indicates the type of information, which can be: 'F' - File system type (e. g. FAT, HPFS, CDFS) 'L' - The volume label 'S' - The volume serial number (default) Returns: The requested information. Notes: The volume serial number is a unique identifier created when the volume is formatted. It is returned in the form xxxx-xxxx, where x is a hex digit. The volume label is the user-specified identifier associated with the volume by the FORMAT or LABEL command. This is the same information returned by DOSVOLUME. The file system type is the same information returned by DOSFILESYS. See also: DOSDISK, DOSFILESYS, DOSVOLUME ═══ 3.69. DOSVOLUME ═══ DOSVOLUME([drive]) Summary: DOSVOLUME returns the volume label of a specified drive. Arguments: drive: Letter that designates the drive of interest. (Default is the current drive.) Returns: The volume label of the specified drive, or a null string if the label cannot be located (for example, the disk has no label, the drive is not ready). See also: DOSCD, DOSVOLINFO ═══ 3.70. ENTAB ═══ ENTAB(string,[spaces]) Summary: ENTAB replaces consecutive blanks in a string with tab characters. Arguments: string: The string into which tabs are to be inserted. spaces: The number of spaces between each tab stop. The default is 8. Returns: The input string with tab characters inserted. Notes: Replacing blanks with tabs can make some strings considerably shorter. This may be significant when creating large ASCII TEXT files. Any tabs that are present in the string to begin with are first replaced by the appropriate number of spaces. The string is then rescanned to replace consecutive blanks with tabs where possible. See also: DETAB ═══ 3.71. ERF ═══ ERF(x) Summary: ERF computes the error function (2pi^{-1/2}\int_0^x e^{-t^2}\, dt). Arguments: x: A real number. Returns: The value of the error function. See also: ERFC ═══ 3.72. ERFC ═══ ERFC(x) Summary: ERFC computes the complement of the error function. Arguments: x: A real number. Returns: The value of the complement of the error function (1 - erf(x)). See also: ERF ═══ 3.73. EVENTSEM_CLOSE ═══ EVENTSEM_CLOSE(name) Summary: EVENTSEM_CLOSE closes an event semaphore. Arguments: name: The name of an event semaphore. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist Notes: EVENTSEM_CLOSE should be used when you are done with an event semaphore to release associated system resources. See also: EVENTSEM_CREATE, EVENTSEM_POST, EVENTSEM_QUERY, EVENTSEM_RESET, EVENTSEM_WAIT ═══ 3.74. EVENTSEM_CREATE ═══ EVENTSEM_CREATE(name,[options]) Summary: EVENTSEM_CREATE creates an event semaphore. Arguments: name: The name of an event semaphore. options: 'P' if the semaphore should be created in a "posted" state. The default is unposted. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 285 - named semaphore already exists Notes: EVENTSEM_CREATE must be done once and only once to define the event semaphore to the system. When an event semaphore is in the posted state, the event it represents is considered to have occurred, and EVENTSEM_WAIT will not wait. See also: EVENTSEM_CLOSE, EVENTSEM_POST, EVENTSEM_QUERY, EVENTSEM_RESET, EVENTSEM_WAIT ═══ 3.75. EVENTSEM_POST ═══ EVENTSEM_POST(name) Summary: EVENTSEM_POST posts an event semaphore. Arguments: name: The name of an event semaphore. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist 298 - too many posts 299 - semaphore already posted Notes: When an event semaphore is in the posted state, the event it represents is considered to have occurred, and EVENTSEM_WAIT will not wait. See also: EVENTSEM_CLOSE, EVENTSEM_CREATE, EVENTSEM_QUERY, EVENTSEM_RESET, EVENTSEM_WAIT ═══ 3.76. EVENTSEM_QUERY ═══ EVENTSEM_QUERY(name) Summary: EVENTSEM_QUERY returns information about an event semaphore. Arguments: name: The name of an event semaphore. Returns: The number of times the event semaphore has been posted since it was last reset. If an error occurs, a negative number is returned that identifies the type of error. Possible error codes include: -123 - name is invalid (must begin with "\sem32\") -187 - semaphore does not exist See also: EVENTSEM_CREATE, EVENTSEM_CLOSE, EVENTSEM_POST, EVENTSEM_RESET, EVENTSEM_WAIT ═══ 3.77. EVENTSEM_RESET ═══ EVENTSEM_RESET(name) Summary: EVENTSEM_RESET resets an event semaphore. Arguments: name: The name of an event semaphore. Returns: The number of times the semaphore has been posted since it was last reset if the operation was successful, otherwise a negative number is returned that identifies the type of error. Possible error codes include: -123 - name is invalid (must begin with "\sem32\") -187 - semaphore does not exist -300 - semaphore already reset Notes: When an event semaphore is reset the event it represents is considered not to have occurred, and EVENTSEM_WAIT will wait. See also: EVENTSEM_CLOSE, EVENTSEM_CREATE, EVENTSEM_POST, EVENTSEM_QUERY, EVENTSEM_WAIT ═══ 3.78. EVENTSEM_WAIT ═══ EVENTSEM_WAIT(name,[timeout]) Summary: EVENTSEM_WAIT waits for an event semaphore to be posted. Arguments: name: The name of an event semaphore. timeout: The maximum length of time to wait, in milliseconds. The default is -1, which means an indefinite wait. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 95 - interrupt occured 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist 640 - timeout occurred Notes: A call to EVENTSEM_WAIT waits until the semaphore has been posted at least once since the last time it was reset. See also: EVENTSEM_CLOSE, EVENTSEM_CREATE, EVENTSEM_POST, EVENTSEM_QUERY, EVENTSEM_RESET ═══ 3.79. EXP ═══ EXP(x) Summary: EXP computes the exponential function. Arguments: x: A real number. Returns: The value of e**x (e=2.718281828...) See also: LOG, LOG10 ═══ 3.80. FILECRC ═══ FILECRC(filename) Summary: FILECRC computes the 32-bit CRC of a file. Arguments: filename: The fully qualified name of the file whose CRC is to be computed. Returns: The 32-bit CRC of the file as an 8-digit hexadecimal number. A null string is returned if there is an error reading the file. Notes: A CRC (Cyclic Redundancy Check) is a number computed by performing a calculation involving every byte of a file. The calculation is designed to minimize the probability that two files which differ by even one byte can have the same CRC. This means a CRC can be used as a quick test to determine whether two versions of a file are identical. If the CRC values are different, the files are certainly different. If the values are the same, there is a very small probability that the files are different. An exact file comparison must be done if it is necessary to know with certainty that the files are the same. CRC values can be used for file version control and file integrity testing. Since FILECRC reads the whole file, it is a good way to check that a given file is readable. See also: STRINGCRC ═══ 3.81. FILEREAD ═══ FILEREAD(filename,stem,[count],[options],[lineend],[startpos],[rba]) Summary: FILEREAD reads an ASCII text file into a REXX array. Arguments: filename: The fully qualified name of the file to read. stem: The stem of the array to read into. count: The number of lines to read. The default is the whole file. options: A string consisting of one or more of the following: 'E' - Stop reading the file when an end-of-file character ('1A'x) is found. The default is to ignore end-of-file characters. lineend: One of the following strings, which determine what sequences are used to identify the end of a line: 'LFONLY' - Only linefeeds and carriage return- linefeed pairs (default). 'CRONLY' - Only carriage returns and carriage return-linefeed pairs. 'CRORLF' - Linefeeds, carriage returns, or carriage return-linefeed pairs. 'CRANDLF' - Only carriage return-linefeed pairs. startpos: The relative position in the file at which to begin reading. (The first byte of the file is 1.) rba: The stem of an array which will be loaded with the relative byte addresses of the start of each line read. (The first byte is 1.) Returns: The number of lines read. Notes: Element 0 of the compound variable array is set to the number of lines read. There is no particular limit on the length of any line which may be read. A negative return code indicates an error reading the file (e. g. invalid name, file not found). See also: FILESEARCH, FILEWRITE ═══ 3.82. FILESEARCH ═══ FILESEARCH(filename,pattern,stem,[options],[zone1],[zone2],[count], [lineend],[startpos],[rba]) Summary: FILESEARCH searches an ASCII text file for a pattern and places selected lines into a REXX array. Arguments: filename: The fully qualified name of the file to read. pattern: A regular expression pattern that describes the string to be searched for. stem: The stem of the array to store selected lines. options: A string consisting of one or more of the following: 'A' - avoid: select only items that do not satisfy the search conditions 'C' - case sensitive matching. The default is to ignore case sensitivity. 'E' - stop reading the file when an end-of-file character ('1A'x) is found. The default is to ignore end-of-file characters. 'F' - exact match required between pattern and first substring of target, except possibly for case, no regular expressions 'N' - precede each line with its relative line number. 'S' - simple search that does not use regular expressions 'X' - exact match required between pattern and target, except possibly for case, no regular expressions zone1: Starting column of each line which is to be considered in the search. The default is 1. zone2: Ending column of each line which is to be considered in the search. The default is the end of the line. count: The number of lines to search. The default is the whole file. lineend: One of the following strings, which determine what sequences are used to identify the end of a line: 'LFONLY' - Only linefeeds and carriage return- linefeed pairs (default). 'CRONLY' - Only carriage returns and carriage return-linefeed pairs. 'CRORLF' - Linefeeds, carriage returns, or carriage return-linefeed pairs. 'CRANDLF' - Only carriage return-linefeed pairs. startpos: The relative position in the file at which to begin reading. (The first byte of the file is 1.) rba: The stem of an array which will be loaded with the relative byte addresses of the start of each line found (The first byte is 1.) Returns: The number of lines selected, or 0 if none met the criteria. Notes: Element 0 of the compound variable array is set to the number of lines selected. A negative return code indicates an error reading the file (e. g. invalid name, file not found). You should avoid using a regular expression search by specifying 'S' in the options string if the pattern may contain any of the characters that have special meaning in regular expressions ("\", "^", "$", ".", ":", "*", "+", "?", "[", and "]"), unless the characters are escaped by being preceded with "\". This is especially likely to be a problem if the pattern is entered as user input at run time or consists of a file name. See also: FILEREAD, FILEWRITE ═══ 3.83. FILEWRITE ═══ FILEWRITE(filename,stem,[option],[count],[start]) Summary: FILEWRITE writes an ASCII text file from a REXX array. Arguments: filename: The fully qualified name of the file to write. stem: The stem of the array to write from. option: One of the following: 'A' - append the file if it exists. 'R' - replace the file if it exists. This is the default. 'N' - do nothing if the file exists. count: The number of lines to write. The default is the number of elements in the array from the starting one to the end. start: The starting element number of the array. Returns: 1 if the operation was successful, otherwise 0. Notes: The file is closed after each call. See also: FILEREAD, FILESEARCH ═══ 3.84. GAMMA ═══ GAMMA(x) Summary: GAMMA computes the gamma function. Arguments: x: A positive real number. Returns: The value of the gamma function for x>0, or a null string for x<=0. ═══ 3.85. GREP ═══ GREP(pattern,string,[options]) Summary: GREP attempts to match a regular expression pattern in a given string. Arguments: pattern: A regular expression pattern. string: The string to be searched. options: Changes the type of search performed from the default, which is a case-insesitive search using a regular expression pattern. The value can be a string consisting of one or more of the following: 'C' - search should be case sensitive 'F' - exact match required between pattern and first substring of target, except possibly for case, no regular expressions 'S' - simple search that does not use regular expressions 'X' - exact match required between pattern and target, except possibly for case, no regular expressions Returns: A string consisting of two numbers separated by a blank. The first is the position in the string at which the pattern matched. The second is the length of the substring matched by the pattern. "0 0" is returned if the match fails. Notes: You should avoid using a regular expression search by specifying 'S' in the options string if the pattern may contain any of the characters that have special meaning in regular expressions ("\", "^", "$", ".", ":", "*", "+", "?", "[", and "]"), unless the characters are escaped by being preceded with "\". This is especially likely to be a problem if the pattern is entered as user input at run time or consists of a file name. See also: CVSEARCH, CVTAILS, FILESEARCH ═══ 3.86. INKEY ═══ INKEY([wait-option],[keyboard-option]) Summary: INKEY reads in a character directly from the keyboard (without echoing it to the display). Arguments: wait-option: 'W' or 'N'. keyboard-option: 'E' or 'F'. Returns: An encoded string that represents the key which was pressed. For "ordinary" keys such as letters, digits, and punctuation, the string is just the ASCII encoding of the corresponding character. For "special" keys such as function keys and cursor keys, the string is the 2-byte "scan code" of the key. Notes: Keyboard scan codes are documented in many places, such as the IBM BIOS Technical Reference. The unshifted function keys F1 through F10, for example, have scan codes in the range '003B'x through '0044'x. The wait-option argument specifies whether or not INKEY should wait for a key to be pressed. 'W' means wait (the default) and 'N' means no wait. If 'N' is selected and no character is available, INKEY returns a null string immediately. The keyboard-option argument specifies whether or not the representations of certain keys which occur more than once in the keyboard should be "folded". If this option is 'F', the default, analogous keys on the numeric and dedicated keypads, such as the cursor keys, have the same representation. If this option is 'E', all keys are assigned distinguishable representations. ═══ 3.87. LOG ═══ LOG(x) Summary: LOG computes the natural logarithm function. Arguments: x: A positive real number. Returns: The natural logarithm of x for x>0, "INFINITY" if x=0, and "NAN" if x<0. See also: EXP, LOG10 ═══ 3.88. LOG10 ═══ LOG10(x) Summary: LOG10 computes the logarithm (base 10) function. Arguments: x: A positive real number. Returns: The logarithm (base 10) of x for x>0, "INFINITY" if x=0, and "NAN" if x<0. See also: EXP, LOG ═══ 3.89. LOWER ═══ LOWER(string) Summary: LOWER lowercases the specified string. Arguments: string: A string to be converted to lower case. Returns: The input string with all upper case characters converted to lower case. See also: UPPER ═══ 3.90. MACROADD ═══ MACROADD(function,filename,[position]) Summary: MACROADD loads a REXX procedure into the macrospace. Arguments: function: The name of the function to be added to the macrospace. filename: The fully qualified name of the REXX program file. position: 'B' if the function is to be found before searching external function packages or disk files, or 'A' if it is to be found afterwards. Returns: 1 if the operation is successful, otherwise 0. Notes: If a function of the same name already exists in the macrospace, it is replaced. If a function's position is 'B', REXX will find it in the process of searching before it looks in the list of registered functions or functions on disk. If its position is 'A', REXX will find it only after looking in the list of registered functions and functions on disk. REXX use of the function name is not case sensitive. See also: MACROCLEAR, MACRODROP, MACROLOAD, MACROQUERY, MACROREORDER, MACROSAVE ═══ 3.91. MACROCLEAR ═══ MACROCLEAR() Summary: MACROCLEAR removes all loaded REXX procedures from the macrospace. Returns: 1 if the operation is successful, otherwise 0. See also: MACROADD, MACRODROP, MACROLOAD, MACROQUERY, MACROREORDER, MACROSAVE ═══ 3.92. MACRODROP ═══ MACRODROP(function) Summary: MACRODROP removes a REXX procedure from the macrospace. Arguments: function: The name of the function to be removed from the macrospace. Returns: 1 if the operation is successful, otherwise 0. See also: MACROADD, MACROCLEAR, MACROLOAD, MACROQUERY, MACROREORDER, MACROSAVE ═══ 3.93. MACROLOAD ═══ MACROLOAD(filename,[namestem]) Summary: MACROLOAD loads some or all of the REXX procedures from a saved macrospace file. Arguments: filename: The name of the saved macrospace file. namestem: A stem name for the compound variable that contains a list of function names to be loaded. Returns: 1 if the operation is successful, otherwise 0. Notes: The list of functions to be loaded is passed in a REXX array. Element 0 of the array must be set to the number of names in the array. If a list of functions to be loaded is not supplied, all functions in the file will be loaded into the macrospace. If any of the functions to be loaded has a name that duplicates that of a function already in the macrospace, nothing is loaded from the file. See also: MACROADD, MACROCLEAR, MACRODROP, MACROQUERY, MACROREORDER, MACROSAVE ═══ 3.94. MACROQUERY ═══ MACROQUERY(function) Summary: MACROQUERY returns the position of a REXX procedure in the macrospace. Arguments: function: The name of the function whose position is to be queried. Returns: 'B' if the function search position in the macrospace is before external functions or 'A' if its search position is after external functions. A null string is returned if the function is not found in the macrospace. Notes: If a function's position is 'B', REXX will find it in the process of searching before it looks in the list of registered functions or functions on disk. If its position is 'A', REXX will find it only after looking in the list of registered functions and functions on disk. See also: MACROADD, MACROCLEAR, MACRODROP, MACROLOAD, MACROREORDER, MACROSAVE ═══ 3.95. MACROREORDER ═══ MACROREORDER(function,position) Summary: MACROREORDER changes the search order position of a REXX procedure in the macrospace. Arguments: function: The name of the function whose position is to be changed. position: 'B' if the function is to be found before searching external function packages or disk files, or 'A' if it is to be found afterwards. Returns: 1 if the operation is successful, otherwise 0. Notes: If a function's position is 'B', REXX will find it in the process of searching before it looks in the list of registered functions or functions on disk. If its position is 'A', REXX will find it only after looking in the list of registered functions and functions on disk. See also: MACROADD, MACROCLEAR, MACRODROP, MACROLOAD, MACROQUERY, MACROSAVE ═══ 3.96. MACROSAVE ═══ MACROSAVE(filename,[namestem]) Summary: MACROSAVE saves some or all of the REXX procedures in the macrospace to a file. Arguments: filename: The name of the saved macrospace file. namestem: A stem name for the compound variable that contains a list of function names to be saved. Returns: 1 if the operation is successful, otherwise 0. Notes: The list of functions to be saved is passed in a REXX array. Element 0 of the array must be set to the number of names in the array. If a list of functions to be saved is not supplied, all functions in the macrospace will be saved in the file. If the file already exists it will be replaced. See also: MACROADD, MACROCLEAR, MACRODROP, MACROLOAD, MACROQUERY, MACROREORDER ═══ 3.97. MUTEXSEM_CLOSE ═══ MUTEXSEM_CLOSE(name) Summary: MUTEXSEM_CLOSE closes a mutual exclusion semaphore. Arguments: name: The name of a mutual exclusion semaphore. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist Notes: MUTEXSEM_CLOSE should be used when you are done with a mutual exclusion semaphore to release associated system resources. See also: MUTEXSEM_CREATE, MUTEXSEM_QUERY, MUTEXSEM_RELEASE, MUTEXSEM_REQUEST ═══ 3.98. MUTEXSEM_CREATE ═══ MUTEXSEM_CREATE(name,[options]) Summary: MUTEXSEM_CREATE creates a mutual exclusion semaphore. Arguments: name: The name of a mutual exclusion semaphore. options: 'O' if the semaphore should be created in an owned state. The default is an unowned state. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 285 - named semaphore already exists Notes: MUTEXSEM_CREATE must be done once and only once to define the mutual exclusion semaphore to the system. When a mutual exclusion semaphore is in the owned state, the resource it represents is considered busy, and other threads that call MUTEXSEM_REQUEST will wait. See also: MUTEXSEM_CLOSE, MUTEXSEM_QUERY, MUTEXSEM_RELEASE, MUTEXSEM_REQUEST ═══ 3.99. MUTEXSEM_QUERY ═══ MUTEXSEM_QUERY(name) Summary: MUTEXSEM_QUERY returns information about a mutual exclusion semaphore. Arguments: name: The name of a mutual exclusion semaphore. Returns: If the operation is successful a string of three numbers is returned. The first is the number of times the semaphore has been requested by its owner minus the number of times it has been released. The second is the process id of the owner. The third is the thread id of the thread that owns the semaphore. If an error occurs, a negative number is returned that identifies the type of error. Possible error codes include: -105 - semaphore owner died -123 - name is invalid (must begin with "\sem32\") -187 - semaphore does not exist Notes: If the semaphore is not currently owned, all three numbers returned will be 0. See also: MUTEXSEM_CLOSE, MUTEXSEM_CREATE, MUTEXSEM_RELEASE, MUTEXSEM_REQUEST ═══ 3.100. MUTEXSEM_RELEASE ═══ MUTEXSEM_RELEASE(name) Summary: MUTEXSEM_RELEASE releases ownership of a mutual exclusion semaphore. Arguments: name: The name of a mutual exclusion semaphore. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist 288 - semaphore not owned by requester Notes: When the event semaphore has been released by its owner as many times as it has been requested, the resource it represents is not considered to be in use, and MUTEXSEM_REQUEST will not wait. See also: MUTEXSEM_CLOSE, MUTEXSEM_CREATE, MUTEXSEM_QUERY, MUTEXSEM_REQUEST ═══ 3.101. MUTEXSEM_REQUEST ═══ MUTEXSEM_REQUEST(name,[timeout]) Summary: MUTEXSEM_REQUEST requests ownership of a mutual exclusion semaphore. Arguments: name: The name of a mutual exclusion semaphore. timeout: The maximum length of time to wait, in milliseconds. The default is -1, which means an indefinite wait. Returns: 0 if the operation was successful, otherwise a return code that identifies the type of error. Possible error codes include: 95 - interrupt occurred 103 - too many semaphore requests outstanding 105 - semaphore owner died 123 - name is invalid (must begin with "\sem32\") 187 - semaphore does not exist 640 - timeout occurred Notes: When a mutual exclusion semaphore has been successfully requested, the resource it represents is considered to be in use, and other threads that call MUTEXSEM_REQUEST will wait. See also: MUTEXSEM_CLOSE, MUTEXSEM_CREATE, MUTEXSEM_QUERY, MUTEXSEM_RELEASE ═══ 3.102. NMPIPE_CALL ═══ NMPIPE_CALL(name,message,[max],[timeout]) Summary: NMPIPE_CALL is used by a client to perform a complete named pipe transaction without needing an explicit pipe open. Arguments: name: The pipe name. message: Data to be sent to initiate a transaction. max: Maximum length of reply expected. The default is 4096 bytes. timeout: Length of time in milliseconds to wait for a pipe to become available. Returns: Data sent by the server in reply to the message. A null string is returned if there is an error. Notes: NMPIPE_CALL is intended for simple message/response transactions. See also: NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.103. NMPIPE_CLOSE ═══ NMPIPE_CLOSE(name) Summary: NMPIPE_CLOSE closes a named pipe. Arguments: name: The pipe name. Returns: 0 if successful, otherwise an error code. Possible error codes include: 2 - pipe not found Notes: NMPIPE_CLOSE is used by the server to destroy a named pipe. See also: NMPIPE_CALL, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.104. NMPIPE_CONNECT ═══ NMPIPE_CONNECT(name) Summary: NMPIPE_CONNECT is used by a server to establish a communication session. Arguments: name: The pipe name. Returns: 0 if successful, otherwise an error code. Possible error codes include: 2 - pipe not found 95 - interrupt occurred 109 - pipe broken 230 - invalid pipe 233 - pipe not connected Notes: NMPIPE_CONNECT must be called by the server before a pipe is available for use by a client. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.105. NMPIPE_CREATE ═══ NMPIPE_CREATE(name,[type],[mode],[wait],[out],[in]) Summary: NMPIPE_CREATE is used by a server to create a named pipe. Arguments: name: The pipe name. type: 'B' for a byte stream pipe (the default), 'M' for a message pipe. readmode: If pipe is a message pipe, 'B' if the read mode is byte (the default), or 'M' if the read mode is message. wait: 'W' if reads should block waiting for data (the default), or 'N' if reads should not block. out: Size in bytes of the output buffer. in: Size in bytes of the input buffer. Returns: A positive number (the pipe handle) if successful. A negative number is an error code. Possible error codes include: -3 - invalid name -4 - too many open handles -231 - pipe busy Notes: NMPIPE_CREATE specifies various default characteristics of a named pipe. Different readmode and wait options can be chosen by a client if NMPIPE_OPEN is used. NMPIPE_CREATE can fail if there are too many files and/or pipes already open. Use the DOSFILEHANDLES function to increase the number of handles allowed. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.106. NMPIPE_DISCONNECT ═══ NMPIPE_DISCONNECT(name) Summary: NMPIPE_DISCONNECT is used by a server to terminate a communication session. Arguments: name: The pipe name. Returns: 0 if successful, otherwise an error code. Possible error codes include: 2 - pipe not found 109 - pipe broken 233 - pipe not connected Notes: NMPIPE_DISCONNECT must be called by the server to acknowledge that a client has terminated a session. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.107. NMPIPE_OPEN ═══ NMPIPE_OPEN(name,[readmode],[wait],[in]) Summary: NMPIPE_OPEN is used by a client to begin a communication session with a server. Arguments: name: The pipe name. readmode: If pipe is a message pipe, 'B' if the read mode is byte (the default), or 'M' if the read mode is message. wait: 'W' if reads should block waiting for data (the default), or 'N' if reads should not block. in: Default size in bytes of the input buffer. 4096 bytes if not specified. Returns: 0 if successful, otherwise an error code. Possible error codes include: 2 - pipe not found 4 - too many open handles Notes: NMPIPE_OPEN must be called by a client before using any of the REXXLIB named pipe client functions except NMPIPE_CALL. It is not required when using ordinary I/O functions such as CHARIN and CHAROUT. NMPIPE_OPEN can fail if there are too many files and/or pipes already open. Use the DOSFILEHANDLES function to increase the number of handles allowed. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_READ, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.108. NMPIPE_READ ═══ NMPIPE_READ(name,[count],[retcode]) Summary: NMPIPE_READ reads data from a named pipe. Arguments: name: The pipe name. count: Number of bytes to read. The default is the pipe input buffer size. retcode: Return code from system call to read the pipe. See the description of NMPIPE_CONNECT for a list of possible return codes. Returns: Data read from the pipe. A null string is returned if an error occurs. Notes: NMPIPE_READ can be used by either the server or the client. A client may alternatively use CHARIN or LINEIN functions. A client must call NMPIPE_OPEN before calling NMPIPE_READ. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_TRANSACT, NMPIPE_WRITE ═══ 3.109. NMPIPE_TRANSACT ═══ NMPIPE_TRANSACT(name,message,[max],[retcode]) Summary: NMPIPE_TRANSACT is used by a client to perform a complete named pipe transaction. Arguments: name: The pipe name. message: Data to be sent to initiate a transaction. max: Maximum length of reply expected. The default is 4096 bytes. retcode: Return code from system call to read the pipe. See the description of NMPIPE_CONNECT for a list of possible return codes. Returns: Data sent by the server in reply to the message. A null string is returned if an error occurs. Notes: NMPIPE_TRANSACT is intended for use in a series of simple message/response transactions. The client must explicitly open and close the pipe. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_WRITE ═══ 3.110. NMPIPE_WRITE ═══ NMPIPE_WRITE(name,data) Summary: NMPIPE_WRITE writes data to a named pipe. Arguments: name: The pipe name. data: Data to be written. Returns: Number of characters not written. A negative number is an error code. Possible error codes include: 2 - pipe not found Notes: NMPIPE_WRITE can be used by either the server or the client. A client may alternatively use CHAROUT or LINEOUT functions. A client must call NMPIPE_OPEN before calling NMPIPE_WRITE. See also: NMPIPE_CALL, NMPIPE_CLOSE, NMPIPE_CONNECT, NMPIPE_CREATE, NMPIPE_DISCONNECT, NMPIPE_OPEN, NMPIPE_READ, NMPIPE_TRANSACT ═══ 3.111. PARSEFN ═══ PARSEFN(filename) Summary: PARSEFN parses a filename into drive, path, file name, and file extension components. Arguments: filename: The file name to be parsed. Returns: A string consisting of four upper case words: drive specifier (without a colon) path specifier file name file extension Notes: Components not present in the file name are returned as a dash ("-"). A null string is returned if the file name is not syntactically valid, for example if it contains invalid characters or invalid components The checking is purely syntactic, so that the file name may refer to a file, drive, or directory that does not exist. See also: DOSFNAME, VALIDNAME ═══ 3.112. PCCOPROCESSOR ═══ PCCOPROCESSOR() Summary: PCCOPROCESSOR indicates whether a hardware math coprocessor is installed. Arguments: none. Returns: 1 if a hardware math coprocessor is installed, otherwise 0. ═══ 3.113. PCDISK ═══ PCDISK(option,[drive]) Summary: PCDISK returns information about the installed fixed and floppy disks. Arguments: option: 'N', 'H', 'C', or 'S' drive: Letter that designates the drive of interest. (Default is the current drive.) Returns: Depends on the selected option: 'N' - Total number of fixed and floppy disks. 'H' - Number of read-write heads (surfaces) on the specified drive (that is, the number of tracks per cylinder). 'C' - Number of disk cylinders. 'S' - Number of sectors per track. Notes: A drive letter can be specified only for the 'H', 'C', and 'S' subfunctions. The 'H', 'C', and 'S' subfunctions apply only to hard disks, See also: DOSDISK ═══ 3.114. PCFLOPPY ═══ PCFLOPPY() Summary: PCFLOPPY returns the number of floppy disks installed. Returns: The number of floppy disks installed. ═══ 3.115. PCMODEL ═══ PCMODEL() Summary: PCMODEL returns the system-defined model number. Arguments: none. Returns: The system (BIOS) defined model number. See also: PCSUBMODEL, PCTYPE ═══ 3.116. PCPARALLEL ═══ PCPARALLEL() Summary: PCPARALLEL returns the number of parallel ports installed. Returns: The number of parallel ports installed. ═══ 3.117. PCRAM ═══ PCRAM() Summary: PCRAM returns the amount of system memory installed in units of 1024 bytes. Returns: The amount of system memory installed in units of 1024 bytes. ═══ 3.118. PCSERIAL ═══ PCSERIAL() Summary: PCSERIAL returns the number of serial ports installed. Returns: The number of serial ports installed. ═══ 3.119. PCSUBMODEL ═══ PCSUBMODEL() Summary: PCMODEL returns the system-defined submodel number. Arguments: none. Returns: The system (BIOS) defined submodel number. See also: PCMODEL, PCTYPE ═══ 3.120. PCVIDEOMODE ═══ PCVIDEOMODE() Summary: PCVIDEOMODE returns information about the current screen mode. Arguments: none. Returns: Four numbers, separated by blanks The first number is -1 if there is an error, otherwise it is 1. The second number is the number of bits of color information which can be displayed for each pixel. For instance, this value is 4 if 16 distinct colors can be displayed. The third and fourth numbers are the horizontal and vertical resolutions of the display in pixels. ═══ 3.121. PMPRINTF ═══ PMPRINTF(string) Summary: PMPRINTF uses the external PMPRINTF program to display debugging and diagnostic output in a separate window. Arguments: string: A string of text to be displayed. Returns: Always returns 1. Notes: You must have the PMPRINTF program to use this function. The PMPRINTF program is IBM EWS (Employee Written Software) that is available from many OS/2 Bulletin Boards and information services. The program is started in a separate window just like any other OS/2 application. Data strings written by the PMPRINTF function appear in the PMPRINTF program window. No substitution is performed on contents of the string, and an ending linefeed is not required. PMPRINTF is one of the easiest ways of producing diagnostic output from a REXX program, especially one that has its own graphical user interface, since the output appears in a completely separate window. ═══ 3.122. POW ═══ POW(x,y) Summary: POW computes the power function (x**y). Arguments: x: A real number. y: A real number. Returns: The value of x**y if x is non-negative or if y is an integer, otherwise "NAN". See also: EXP, LOG, LOG10 ═══ 3.123. REXXLIBDEREGISTER ═══ REXXLIBDEREGISTER() Summary: REXXLIBDEREGISTER removes the definitions of all REXXLIB functions from the operating system. Arguments: none. Returns: Always returns 1. See also: REXXLIBREGISTER ═══ 3.124. REXXLIBREGISTER ═══ REXXLIBREGISTER() Summary: REXXLIBREGISTER defines all REXXLIB functions to the operating system. Arguments: none. Returns: Always returns 1. See also: REXXLIBDEREGISTER ═══ 3.125. REXXLIBVER ═══ REXXLIBVER() Summary: REXXLIBVER returns the current REXXLIB version number. Arguments: none. Returns: The current REXXLIB version number. ═══ 3.126. REXXRUN ═══ REXXRUN(type,source,[result],[arg-1],...,[arg-n]) Summary: REXXRUN runs an external REXX program from a file, the REXX macro space, a source code string, or a tokenized source code string. Arguments: type: The type of source code, which can be: 'F' - Source code is in a file. 'S' - Source code is in a string. 'T' - Source code is in a tokenized string. 'M' - Source code is in the macro space. source: Depends on the value of type: the name of a file (type 'F'), the actual program code (type 'S'), tokenized source code (type 'T'), or the name of a function in the macro space (type 'M'). result: The name of a REXX variable to receive the value returned (if any) by the program. arg-i: Arguments to be passed to the program. Returns: The return code from the REXX interpreter. This will be 0 if the program ran to completion. A positive number indicates a problem starting the interpreter. A negative number is a program execution error (the negative of the REXX error code). Notes: Source code may be supplied in a REXX string (type 'S'). This should be in a form just as if the program were read from a file, with lines separated by carriage returns and linefeeds, and statements on the same line separated by semicolons. Tokenized code is created as the ouput of the TOKENIZEFILE or TOKENIZESTRING functions. Programs are loaded into the macro space with the MACROADD or MACROLOAD functions. A variable name may be specified to receive the value returned by the external program. If no value is returned, the variable will be dropped. Avoid using a variable named RESULT, since this variable is set by REXX itself after a CALL statement. There are several other ways to invoke external REXX programs, but all have disadvantages that are avoided by using REXXRUN. One way is to use the system CALL command. This has the disadvantage that it requires the system command handler (CMD.EXE), which means the new program must run in a separate process if the calling program wasn't started by CMD.EXE. There is an additional disadvantage that only one argument string can be passed this way. Another way is to use the REXX CALL statement. This has the disadvantage that it cannot take a variable file name (without using INTERPRET). In addition, if the called program fails because of a REXX error, a SYNTAX condition will be raised in the calling program. A final way is to use the REXX macro space. One possible disadvantage of this is that the macro space is global to the system, raising possibilities of name conflicts. See also: MACROADD, MACROLOAD, REXXTHREAD, TOKENIZEFILE, TOKENIZESTRING ═══ 3.127. REXXTHREAD ═══ REXXTHREAD(type,source,[arg-1],...,[arg-n]) Summary: REXXTHREAD starts a new thread and runs an external REXX program from a file, the REXX macro space, a source code string, or a tokenized source code string. Arguments: type: The type of source code, which can be: 'F' - Source code is in a file. 'S' - Source code is in a string. 'T' - Source code is in a tokenized string. 'M' - Source code is in the macro space. source: Depends on the value of type: the name of a file (type 'F'), the actual program code (type 'S'), tokenized source code (type 'T'), or the name of a function in the macro space (type 'M'). arg-i: Arguments to be passed to the program. Returns: The thread id of the newly created thread, or 0 if the thread could not be started. Notes: Source code may be supplied in a REXX string (type 'S'). This should be in a form just as if the program were read from a file, with lines separated by carriage returns and linefeeds, and statements on the same line separated by semicolons. Tokenized code is created as the ouput of the TOKENIZEFILE or TOKENIZESTRING functions. Programs are loaded into the macro space with the MACROADD or MACROLOAD functions. Because the new program is run on a different thread, there is no direct way to access a value returned by the program. Any exchange of data between threads must use some form of interprogram communication such as REXX external data queues or named pipes. See also: MACROADD, MACROLOAD, REXXRUN, TOKENIZEFILE, TOKENIZESTRING ═══ 3.128. SCRBLINK ═══ SCRBLINK([state]) Summary: SCRBLINK returns the current state of video attribute handling and optionally changes it. Arguments: state: A value of 1 or 0 that indicates whether certain text-mode video attributes produce blinking characters or bright background colors. Returns: The value of the "blink" flag before any changes. Notes: Video attributes are listed in connection with the SCRWRITE function. Attribute values of 128 and above can alternatively be used to product blinking characters or high-intensity background colors, depending on the setting of the blink flag. SCRBLINK does not work in a PM text window and always returns 0 in that case. ═══ 3.129. SCRBORDER ═══ SCRBORDER([color]) Summary: SCRBORDER sets the screen border attributes. Arguments: color: The color attribute number for the screen border. The number must be in the range 0 to 255. Returns: The original color attribute number. Notes: Attribute numbers 0 through 7 are usually as follows: 0 - black 1 - blue 2 - green 3 - cyan 4 - red 5 - magenta 6 - brown 7 - white The meaning of other values is dependent on the display hardware and the current setting of the display palette registers. If SCRBORDER is used in a PM window it will return -1 and have no effect on the screen. ═══ 3.130. SCRCLEAR ═══ SCRCLEAR([attr],[char],[row],[col],[height],[width]) Summary: SCRCLEAR clears the screen, or any rectangular region of the screen. Arguments: attr: The display attribute to use in the cleared area. The default is 7. char: The character to use to fill the cleared area. The default is a blank. row: The top row of the area to be cleared. The default is 1. col: The leftmost column of the area to be cleared. The default is 1. height: The number of rows in the rectangle to be cleared. The default is to the bottom of the screen. width: The number of columns in the rectangle to be cleared. The default is to the right edge of the screen. Returns: Always returns 0. Notes: Calling SCRCLEAR with no arguments will clear the screen by filling it with blanks using the default attribute of 7 (white on black). Row numbers start with 1 at the top of the screen or window. Column numbers start with 1 at the left hand side. Video attributes are listed in connection with the SCRWRITE function. See also: SCRPUT, SCRWRITE ═══ 3.131. SCROLLDOWN ═══ SCROLLDOWN(n,[pad],[attr],[top],[left],[bottom],[right]) Summary: SCROLLDOWN scrolls text down in a rectangular region of the screen. Arguments: n: Number of lines to scroll down. pad: Character to be inserted into lines at the top of the rectangular region after scrolling (default is blank). attr: Attribute to be used for displaying the pad character (default is white on black). top: Top line of the rectangular region (default is top line of the screen). left: Left edge of the rectangular region (default is left edge of the screen). bottom: Bottom line of the rectangular region (default is bottom line of the screen). right: Right edge of the rectangular region (default is right edge of the screen). Returns: Always returns 1. Notes: An attribute value is the sum of a number in the range 0 to 15 indicating the foreground color and 16 times another number from 0 to 15 indicating the foreground color. Numbers above 127 may indicate either high intensity foreground or blinking depending on the status of the "blink bit". See the description of SCRWRITE for a complete table of values. If the limits of the rectangle are outside the boundaries of the screen, the rectangle will be clipped to the screen limits. See also: SCRBLINK, SCRWRITE ═══ 3.132. SCROLLLEFT ═══ SCROLLLEFT(n,[pad],[attr],[top],[left],[bottom],[right]) Summary: SCROLLLEFT scrolls text left in a rectangular region of the screen. Arguments: n: Number of columns to scroll left. pad: Character to be inserted into columns at the right of the rectangular region after scrolling (default is blank). attr: Attribute to be used for displaying the pad character (default is white on black). top: Top line of the rectangular region (default is top line of the screen). left: Left edge of the rectangular region (default is left edge of the screen). bottom: Bottom line of the rectangular region (default is bottom line of the screen). right: Right edge of the rectangular region (default is right edge of the screen). Returns: Always returns 1. Notes: An attribute value is the sum of a number in the range 0 to 15 indicating the foreground color and 16 times another number from 0 to 15 indicating the foreground color. Numbers above 127 may indicate either high intensity foreground or blinking depending on the status of the "blink bit". See the description of SCRWRITE for a complete table of values. If the limits of the rectangle are outside the boundaries of the screen, the rectangle will be clipped to the screen limits. See also: SCRBLINK, SCRWRITE ═══ 3.133. SCROLLRIGHT ═══ SCROLLRIGHT(n,[pad],[attr],[top],[left],[bottom],[right]) Summary: SCROLLRIGHT scrolls text right in a rectangular region of the screen. Arguments: n: Number of columns to scroll right. pad: Character to be inserted into columns at the left of the rectangular region after scrolling (default is blank). attr: Attribute to be used for displaying the pad character (default is white on black). top: Top line of the rectangular region (default is top line of the screen). left: Left edge of the rectangular region (default is left edge of the screen). bottom: Bottom line of the rectangular region (default is bottom line of the screen). right: Right edge of the rectangular region (default is right edge of the screen). Returns: Always returns 1. Notes: An attribute value is the sum of a number in the range 0 to 15 indicating the foreground color and 16 times another number from 0 to 15 indicating the foreground color. Numbers above 127 may indicate either high intensity foreground or blinking depending on the status of the "blink bit". See the description of SCRWRITE for a complete table of values. If the limits of the rectangle are outside the boundaries of the screen, the rectangle will be clipped to the screen limits. See also: SCRBLINK, SCRWRITE ═══ 3.134. SCROLLUP ═══ SCROLLUP(n,[pad],[attr],[top],[left],[bottom],[right]) Summary: SCROLLUP scrolls text up in a rectangular region of the screen. Arguments: n: Number of lines to scroll up. pad: Character to be inserted into lines at the bottom of the rectangular region after scrolling (default is blank). attr: Attribute to be used for displaying the pad character (default is 7, white on black). top: Top line of the rectangular region (default is top line of the screen). left: Left edge of the rectangular region (default is left edge of the screen). bottom: Bottom line of the rectangular region (default is bottom line of the screen). right: Right edge of the rectangular region (default is right edge of the screen). Returns: Always returns 1. Notes: An attribute value is the sum of a number in the range 0 to 15 indicating the foreground color and 16 times another number from 0 to 15 indicating the foreground color. Numbers above 127 may indicate either high intensity foreground or blinking depending on the status of the "blink bit". See the description of SCRWRITE for a complete table of values. If the limits of the rectangle are outside the boundaries of the screen, the rectangle will be clipped to the screen limits. See also: SCRBLINK, SCRWRITE ═══ 3.135. SCRPUT ═══ SCRPUT(row,col,string,[option]) Summary: SCRPUT writes a string to the screen at a specified position. Arguments: row: The row at which to begin writing. col: The column at which to begin writing. string: The string to be displayed. option: 'T', 'A', or 'B'. Returns: Always returns a null string. Notes: The option argument specifies the contents of the string. 'T', the default, means that the string consists only of text characters to be written. Existing attributes on the screen are not changed. 'A' means that the string consists only of attribute bytes. Existing text on the screen is not changed. 'B' means that the string consists of character-attribute pairs (with chars preceding their corresponding attribute). In this case, the length of the string must be even, and LENGTH(string)/2 screen position are written. Row numbers start with 1 at the top of the screen or window. Column numbers start with 1 at the left hand side. Video attributes are listed in connection with the SCRWRITE function. See also: SCRCLEAR, SCRWRITE ═══ 3.136. SCRREAD ═══ SCRREAD(row,col,length,[option]) Summary: SCRREAD reads a string from the screen at a specified position. Arguments: row: The row at which to begin reading. col: The column at which to begin reading. length: The number of character positions to read. option: 'T', 'A', or 'B'. Returns: A string read from the screen consisting of text ('T'), attributes ('A'), or both ('B') Notes: The option argument specifies the contents of the string. 'T', the default, means that the string consists only of text characters read from the screen. 'A' means that the string consists only of attribute bytes. 'B' means that the string consists of character-attribute pairs (with chars preceding their corresponding attribute). In this case, the length of the string will be twice the number of character positions read. Row numbers start with 1 at the top of the screen or window. Column numbers start with 1 at the left hand side. Video attributes are listed in connection with the SCRWRITE function. See also: SCRPUT ═══ 3.137. SCRSIZE ═══ SCRSIZE() Summary: SCRSIZE returns the number of rows and columns on the screen. Returns: Two numbers, separated by a blank. The first is the number of rows on the screen (or window), and the second is the number of columns. ═══ 3.138. SCRWRITE ═══ SCRWRITE([row],[col],[string],[length],[pad],[attr]) Summary: SCRWRITE writes a string with specified attributes to the screen at a specified position. Arguments: row: The row at which to begin writing. The default is the current cursor position. col: The column at which to begin writing. The default is the current cursor position. string: The string to be displayed. The default is a null string. length: The number of character positions to be written. The default is the length of the string. pad: A pad character. The default is a blank. attr: Display attribute to be used. The default is 7. Returns: Always returns 0. Notes: SCRWRITE does not affect the current cursor position, Attribute values are computed by adding the number that represents a foreground color to the number that represents a background color: Foreground Colors: 0 - black 1 - blue 2 - green 3 - cyan 4 - red 5 - magenta 6 - brown 7 - white 8 - gray 9 - light blue 10 - light green 11 - light cyan 12 - light red 13 - light magenta 14 - yellow 15 - high intensity white Background Colors: 0 - black 16 - blue 32 - green 48 - cyan 64 - red 80 - magenta 96 - brown 112 - white If blinking attributes are enabled, as they are by default, adding 128 will produce blinking text. If blinking attributes are disabled with the SCRBLINK function, adding 128 will produce text with bright background colors. See also: SCRBLINK, SCRPUT ═══ 3.139. SHIFTSTATE ═══ SHIFTSTATE(key,[state]) Summary: SHIFTSTATE returns the current shift state of the NumLock, CapsLock, and ScrollLock keys. Arguments: key: 'C' (for CapsLock), 'N' (for NumLock), or 'S' (for ScrollLock). state: 0 to for unshifted, 1 for shifted. Returns: The shift state of the specified key before changes. Notes: SHIFTSTATE cannot be used to change the state of shift keys in a PM window session, but it does correctly return the current shift state of the key. ═══ 3.140. SIN ═══ SIN(x) Summary: SIN computes the sine function. Arguments: x: A real number (radians). Returns: The sine of x. See also: ACOS, ASIN, ATAN, ATAN2, COS, TAN ═══ 3.141. SINH ═══ SINH(x) Summary: SINH computes the hyperbolic sine function. Arguments: x: A real number. Returns: The hyperbolic sine of x. See also: COSH, TANH ═══ 3.142. SOUND ═══ SOUND([freq],[duration]) Summary: SOUND sounds the PC's speaker. Arguments: freq: A frequency in cycles per second. Default is 880. duration: Length of time in seconds. Default is .2. Returns: Always returns 1. Notes: The duration can be specified as a fractional number and is accurate to within about a tenth of a second. ═══ 3.143. SQRT ═══ SQRT(x) Summary: SQRT computes the square root function. Arguments: x: A non-negative real number. Returns: The square root of x if x>=0, otherwise "NAN". See also: POWER ═══ 3.144. STRINGCRC ═══ STRINGCRC(string) Summary: STRINGCRC computes the 32-bit CRC of a string. Arguments: string: The string whose CRC is to be computed. Returns: The 32-bit CRC of the string as an 8-digit hexadecimal number. Notes: A CRC (Cyclic Redundancy Check) is a number computed by performing a calculation involving every byte of a string. The calculation is designed to minimize the probability that two strings which differ by even one byte can have the same CRC. See also: FILECRC ═══ 3.145. STRINGIN ═══ STRINGIN([row],[column],[string],[length],[pad],[attr]) Summary: STRINGIN reads in a string from the keyboard with cursor key controls. Arguments: row: Screen row number of the input field (default is row containing cursor). column: Screen column number of the start of the input field (default is column containing cursor). string: String used as initial contents of input field (default is blanks). length: Length of string (default is to the right edge of the screen). pad: Character that fills out the input field beyond the end of data entered (default is blank). attr: Attribute to be used for displaying characters entered in the field (default is 7, white on black). Returns: The string entered in the input field, up to but not including the first pad character. Notes: Various keys may be used to perform editing operations: Backspace - delete character to left of cursor Del - delete character under cursor Right - move cursor right 1 column Left - move cursor left 1 column Ctrl-right - move cursor right one word Ctrl-left - move cursor left one word Insert - toggle insert/overtype mode Home - move cursor to start of field End - move cursor to end of data entered Ctrl-home - clear input field and position cursor at start Ctrl-end - clear input field from cursor position to end Tab - move cursor right 4 columns Shift-tab - move cursor left 4 columns The input operation is ended by pressing the Enter key. It can also be ended by pressing the Esc key, in which case the function returns a null string. An attribute value is the sum of a number in the range 0 to 15 indicating the foreground color and 16 times another number from 0 to 7 indicating the background color. Numbers above 127 may indicate either high intensity foreground or blinking depending on the status of the "blink bit". See the description of SCRWRITE for a complete table of values. See also: SCRBLINK, SCRWRITE ═══ 3.146. TAN ═══ TAN(x) Summary: TAN computes the tangent function. Arguments: x: A real number (radians). Returns: The tangent of x. See also: ACOS, ASIN, ATAN, ATAN2, COS, SIN ═══ 3.147. TANH ═══ TANH(x) Summary: TANH computes the hyperbolic tangent function. Arguments: x: A real number. Returns: The hyperbolic tangent of x. See also: COSH, SINH ═══ 3.148. TOKENIZEFILE ═══ TOKENIZEFILE(filename,output) Summary: TOKENIZEFILE uses the REXX language processor to produce a tokenized program string. Arguments: filename: The name of the REXX program file. output: The name of a REXX variable that receives the tokenized result. Returns: 1 if the function is successful, otherwise 0. Notes: A tokenized program string can be used by the REXXRUN and REXXTHREAD functions to execute a program without the overhead of processing the source code for each call. Tokenized code is language processor dependent. Code tokenized by Personal REXX cannot be used by IBM REXX and vice versa. See also: REXXRUN, REXXTHREAD, TOKENIZESTRING ═══ 3.149. TOKENIZESTRING ═══ TOKENIZESTRING(source,output) Summary: TOKENIZESTRING uses the REXX language processor to produce a tokenized program string. Arguments: source: A REXX string containing program source code. output: The name of a REXX variable that receives the tokenized result. Returns: 1 if the function is successful, otherwise 0. Notes: A tokenized program string can be used by the REXXRUN and REXXTHREAD functions to execute a program without the overhead of processing the source code for each call. Tokenized code is language processor dependent. Code tokenized by Personal REXX cannot be used by IBM REXX and vice versa. The source string should be in a form just as if the program were read from a file, with lines separated by carriage returns and linefeeds, and statements on the same line separated by semicolons. See also: REXXRUN, REXXTHREAD, TOKENIZEFILE ═══ 3.150. TYPEMATIC ═══ TYPEMATIC(rate,delay) Summary: TYPEMATIC sets the keyboard typematic repeat rate and initial delay. Arguments: rate: The rate in characters per second at which a key which is held down should repeat. delay: The length of time in milliseconds after a key is first pressed that it begins to repeat. Returns: 1 if the function is successful, otherwise 0. Notes: The values of rate and delay that can actually be set are limited by the operating system. Typically, rate will not be greater than 30 and delay will not be greater than 1000. If TYPEMATIC is used in a PM window it will return 0 and have no effect on the keyboard typematic rate. However, if the typematic rate is set in a full-screen session, it applies to all active sessions, including the PM session. ═══ 3.151. UPPER ═══ UPPER(string) Summary: UPPER uppercases the specified string. Arguments: string: A string to be converted to lower case. Returns: The input string with all lower case characters converted to upper case. Notes: UPPER(string) is equivalent to TRANSLATE(string), but easier to type and remember. See also: LOWER ═══ 3.152. VALIDNAME ═══ VALIDNAME(filename,[wildcard]) Summary: VALIDNAME indicates whether a name is a syntactically valid file name. Arguments: filename: The name to be tested for validity. wildcard: 1 or 0 to indicate whether or no wildcard characters are to be allowed as valid in a name. Returns: 1 if the name is a valid file name, otherwise 0. Notes: If the file name includes a drive letter, it must be a valid drive, and the name syntax is checked according to the rules of the file system on the specified drive. Otherwise the syntax is checked according to the rules of the file system on the current drive. Names are tested to verify that all parts of the name do not exceed allowed lengths and that characters not allowed in names are not present. Directory names included in the fileid do not need to exist. If the wildcard flag is 1 then "?" and "*" are allowed in file names (but not paths). If it is 0 (the default) then "?" and "*" cannot be used anywhere. See also: DOSFNAME, PARSEFN ═══ 3.153. VARDUMP ═══ VARDUMP([filename],[include],[var1],...) Summary: VARDUMP writes the names and values of selected variables to a specified file. Arguments: filename: The fully qualified name of a file to which variable names and values are to be written. The default is the standard output stream. include: The letter 'I' if the following list of variables specifies names which are to be included, or the letter 'E' if the list specifies names which are to be excluded. 'I' is the default. var1: The name of a variable or a stem which is to be included or excluded from the names and values to be dumped. As many additional names as required may be specified in subsequent arguments. If a stem (ending in '.') is specified, all variables with that stem will be dumped. Returns: 1 if the operation is successful, otherwise 0. Notes: When the include option is in effect and no variable or stem names are specified, all currently visible variables and stems in the program are dumped. The format of the information written to the file is: Name=..., Value=... which is intended to be used primarily for program debugging. If the specified file exists, new data is appended to the end of it. The maximum length of a value which will be dumped is 1000 characters. Values in excess of this will be truncated. The order in which variable values are dumped is not predictable. See also: VARREAD, VARWRITE ═══ 3.154. VARREAD ═══ VARREAD(filename,[include],[var1],...) Summary: VARREAD reads the names and values of selected variables from a specified file. Arguments: filename: The fully qualified name of a file from which variable names and values are to be read. include: The letter 'I' if the following list of variables specifies names which are to be included, or the letter 'E' if the list specifies names which are to be excluded. 'I' is the default. var1: The name of a variable or a stem which is to be included or excluded from the names and values to be read. As many additional names as required may be specified in subsequent arguments. If a stem (ending in '.') is specified, all variables with that stem will be read (if they are contained in the file). Returns: 1 if the operation is successful, otherwise 0. Notes: When the include option is in effect and no variable or stem names are specified, all variables contained in the file will be read. The specified file must have been created by VARWRITE. The file contains the full name of each variable, and existing variables in the program will be updated with values read from the file. For a compound variable whose stem is included, only values corresponding to tails which have been stored in the file will be updated. Any other values will be unaffected. VARREAD is intended to be used with VARWRITE as a general way for a program to save current state information. The file can be used like an "INI" file to save program configuration data. It can also be used to treat a collection of REXX variables as a general-purpose database. See also: VARDUMP, VARWRITE ═══ 3.155. VARWRITE ═══ VARWRITE(filename,[include],[var1],...) Summary: VARWRITE writes the names and values of selected variables to a specified file. Arguments: filename: The fully qualified name of a file to which variable names and values are to be written. include: The letter 'I' if the following list of variables specifies names which are to be included, or the letter 'E' if the list specifies names which are to be excluded. 'I' is the default. var1: The name of a variable or a stem which is to be included or excluded from the names and values to be written. As many additional names as required may be specified in subsequent arguments. If a stem (ending in '.') is specified, all variables with that stem will be written. Returns: 1 if the operation is successful, otherwise 0. Notes: When the include option is in effect and no variable or stem names are specified, all currently visible variables and stems in the program are written. The file written by VARWRITE is intended to be used later by VARREAD, so its exact format should not be depended on. The full name of each variable, including the stem if appropriate, is written to the file. If the specified file exists, it must have been created by VARWRITE, and new data is appended to the end of it. VARWRITE is intended to be used with VARREAD as a general way for a program to save current state information. The file can be used like an "INI" file to save program configuration data. It can also be used to treat a collection of REXX variables as a general-purpose database. See also: VARDUMP, VARREAD