OS/2 Shareware BBS: 18 REXX/18-REXX.zip/rexxlb.zip/RLDEMO.INF

OS/2 Help File | 1995-08-09 | 118KB | 4,407 lines

ΓòÉΓòÉΓòÉ 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: [phone]
   Fax:  [phone]
   BBS:  [phone]

   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: [e-mail]


ΓòÉΓòÉΓòÉ 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: [phone]

 2. Fax: [phone]

 3. Quercus Systems Bulletin Board: [phone] (Send a message to "SYSOP".)

 4. CompuServe: send mail to 75300,2450

 5. Internet: send mail to [e-mail]

 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: <yyyymmdd>. For instance,
      19930131 is January 31, 1993. The date must be on or after
      January 1, 1980.

      The new time is specified as <hhmmss> (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