

                                REXX FUNCTIONS
                                --------------

 Ŀ
                                                                         
  >>SysQueryExtLIBPATH(flag)>< 
                                                                         
 

 This function returns the current path to be searched before or after the
 system LIBPATH when locating DLLs.

 Parameters

  flag
      The flag controlling which extended LIBPATH should be returned:

        'B'            Return the BEGINLIBPATH setting.
        'E'            Return the ENDLIBPATH setting.

 Example:

 /* Show the current setting of the extended LIBPATH */
  say "BEGINLIBPATH is:" SysQueryExtLIBPATH("B")
  say "ENDLIBPATH is:  " SysQueryExtLIBPATH("E")



 Ŀ
                                                                         
  >>SysQuerySwitchList(stem)>< 
                               ,flags                                
                                                                         
 

 This function obtains information about the entries in the Window List.
 By default only visible and jumpable entries will be returned.

 Parameters

  stem
      The name of a REXX stem variable. SysQuerySwitchList sets REXX
      variable stem.0 to the number of Window List entries and stores the
      individual entries in stem.1 to stem.n.

  flags
       Any combination of the following:

        'I'  Include invisible entries in the list.
        'G'  Include grayed entries in the list.
        'N'  Include entries in the list that are not jumpable.
        'D'  Return the list in the detailed form:PID SID Visibility
             Jumpable ProgType Name

       The returned values are directly taken from the SWCNTRL structure.
       For description of the possible values see the PM Guide and
       Reference.

 Example:

 /* Type the Window List */
  call SysQuerySwitchList "list."
  do i = 1 to list.0
    say 'Entry' i 'is' list.i
  end



 Ŀ
                                                                         
  >>SysSetExtLIBPATH(,flag)>< 
                        path                                         
                                                                         
 

 This function defines the current path to be searched before or after the
 system LIBPATH when locating DLLs.
 The OS/2 error code will be returned (0 if successful).

 Parameters

  path
      The extended LIBPATH string. The string can be up to 1024 characters
      long. The extended LIBPATH may contain the strings "%BEGINLIBPATH%"
      or "%ENDLIBPATH%" in which case the current values will be inserted
      in the resulting extended LIBPATH. However, if the resulting extended
      LIBPATH is longer than 1024 characters, the function will return an
      error.

      To remove the current extended LIBPATH you can specify an empty
      string or omit this parameter.

  flag
      The flag controlling which extended LIBPATH should be set:

       'B'            Set the BEGINLIBPATH.
       'E'            Set the ENDLIBPATH.

 Example:

 /* Add D:\TEST to BEGINLIBPATH and delete ENDLIBPATH */
  Call SysSetExtLIBPATH "D:\TEST;%BEGINLIBPATH%", "B"
  Call SysSetExtLIBPATH , "E"





 Ŀ
                                                                         
  >>SysSwitchSession(name)>< 
                                                                         
 

 This function makes a specific program the active program. The function
 returns the error code from WinSwitchToProgram (0 if successful).

 Parameters

 name
     The name of the session to switch to. The name must match the
     appropriate program name as used in the Window List
     (see function SysQuerySwitchList).



 SysDumpVariables
 ----------------

 Syntax: result = SysDumpVariables([filename])

 Params: filename - name of the file where variables are appended to
         (dump is written to STDOUT if omitted)

 Function: This function dumps all variables in the current scope either
           to the specified file (new data will be appended) or to STDOUT
           if the filename parameter is omitted. The format of the data
           is (one variable per line):
           Name=MYVAR, Value="This is the content of MYVAR"

           Examples:
             Call SysDumpVariables "MyVars.Lst" /* append vars to file */
             Call SysDumpVariables              /* list vars on STDOUT */

 Return:    0 - dump completed OK
           -1 - failure during dump









 SysSetFileDateTime
 ------------------

Syntax: result = SysSetFileDateTime(filename [,newdate] [,newtime])

Params: filename - name of the file to update
        newdate  - new date to set in format YYYY-MM-DD
         OS/2: (YYYY > 1980)
          Win: (YYYY > 1800)
    AIX/Linux: (YYYY > 1900)
    newtime  - new time to set in format HH:MM:SS (24 hr format)

Function: This function can be used to modify the "Last Modified"
          Date of the specified file. If no new date or new time is
          specified then the file date and time will be set to the
          current time (TOUCH). If only one of date or time is omitted
          then this parameter will be left unchanged.

          For OS/2 and Windows NT the filename may also specify a directory
          name. This does not work with Windows 95/98 or AIX/Linux however.

          The file you want to change must not be opened by another process
          or at least it must allow shared writes in order to update the
          timestamp.

          Examples:
              Call SysSetFileDateTime "MyFile.Log"  /* touch file */
              Call SysSetFileDateTime "MyFile.Log", "1998-12-17"
              Call SysSetFileDateTime "MyFile.Log",, "16:37:21"
              Call SysSetFileDateTime "MyFile.Log", "1998-12-17", "16:37:21"

              Call SysSetFileDateTime "C:\MyDir"  /* touch dir on OS/2, NT */

 Return:    0 - file date/time was updated correctly
           -1 - failure attribute update


















 SysGetFileDateTime
 ------------------

 Syntax: result = SysGetFileDateTime(filename [,timesel])

 Params: filename - name of the file to query
           timesel  - What filetime to query: CREATE/ACCESS/WRITE

Function: The function call returns the selected file date time attribute
          of the specified file if this is supported by the operating
          and file system (e.g. FAT does not provide Create/Access). The
          selector for the time to be returned can be abbreviated with
          its first character.

          For OS/2 and Windows NT the filename may also specify a directory
          name. This does not work with Windows 95/98 or AIX/Linux however.

          The file you want to query must not be opened by another process
          or at least it must allow shared reads in order to query the
          timestamp.

    Examples:
      Say "File creation time:" SysGetFileDateTime("MyFile.Log", "C")
      Say "File last access time:" SysGetFileDateTime("MyFile.Log", "A")
      Say "File last update time:" SysGetFileDateTime("MyFile.Log", "W")

      Say "Directory creation time:" SysGetFileDateTime("C:\MyDir", "C")

 Return: -1 - file date/time query failed
         other - date and time as YYYY-MM-DD HH:MM:SS



 SysStemCopy
 -----------

 Syntax: result = SysStemCopy(fromstem, tostem, [from], [to], [count]
                  [,insert])

 Params: fromstem - name of source stem
         tostem - - name of target stem
         from  - first index in source stem to copy
         to - position where items are copied/inserted in target stem
         count - number of items to copy/insert
         insert - 'I' to indicate insert instead of 'O' overwrite




 Function: Copy elements from the source stem to the target stem. Elements
           in the source stem are copied starting at the from index
           (default 1) into the target stem beginning at the to index
           (default 1). The number of items to copy to the target stem can
           be specified with count (default is to copy all items in the
           source stem). You can optionally specify that the items should
           be inserted into the target stem at the position and the
           existing items will be shifted to the back accordingly.

           This function operates only on stem arrays that specify the
           number of elements in stem.0 and all elements must be numbered
           from 1 to n with no omitted index.

           Examples:
             Source.0 = 3
             Source.1 = "Hello"
             Source.2 = "from"
             Source.3 = "REXX"
             Call SysStemCopy "Source.", "Target."

             Call SysStemCopy "Source.", "Target.", 1, 5, 2, "I"

 Return:    0 - stem copy was successful
           -1 - stem copy failed



 SysStemDelete
 -------------

 Syntax: result = SysStemDelete(stem, startitem [,itemcount])

 Params: stem - name of stem where item will be deleted
         startitem - index of item to delete
         itemcount - number of items to delete if more than 1

Function: Deletes the specified item at index startitem in the stem.
          If more than one item is to be deleted then the count of
          items can be specified as the third parameter. After deleting
          the requested items the stem will be compacted, that means
          items following the deleted items will be shifted up into the
          vacant positions.

          This function operates only on stem arrays that specify the number
          of elements in stem.0 and all elements must be numbered from 1 to
          n with no omitted index.

          Examples:

            Call SysStemDelete "MyStem.", 5

            Call SysStemDelete "MyStem.", 5, 4

 Return:    0 - delete was successful
           -1 - delete failed





 SysStemInsert
 -------------

 Syntax: result = SysStemInsert(stem, position, value)

 Params: stem - name of stem where item will be inserted
         position - index where new item will be inserted
         value - new item value

 Function: A new item will be inserted at the specified position in
           the stem. All existing items in the stem from the specified
           position will be shifted up by one to make room for the new
           item.

           This function operates only on stem arrays that specify the
           number of elements in stem.0 and all elements must be numbered
           from 1 to n with no omitted index.

           Example:
             Call SysStemInsert "MyStem.", 5, "New value for item 5"

 Return:    0 - insert was successful
           -1 - insert failed



 SysStemSort
 -----------

 Syntax: result = SysStemSort(stem, order, type, start, end,
                  firstcol, lastcol)

 Params: stem - name of stem to sort
         order - 'A' or 'D' for sort order (default: ascending)
         type - 'C', 'I'  for comparision type (case/ignore, default: case)
         start - first index to sort (default: 1)
         end - last index to sort (default: last item)
         firstcol - first column to use as sort key (default: 1)
         lastcol - last column to use as sort key (default: last column)

 Function: This call sorts all or the specified items in the stem.
           Sort order can be specified as ascending or descending,
           comparison type can respect or ignore the case of the strings
           being compared. The sorting can further be narrowed by specifying
           the first and last item to be sorted or by specifying the columns
           used as the sorting key. The sort uses a quicksort algorithm, so
           the order of equal elements according to the sort key is
           undetermined.




           This function operates only on stem arrays that specify the
           number of elements in stem.0 and all elements must be numbered
           from 1 to n with no omitted index.

           Examples:
            /* sort all elements descending, use cols 5 to 10 as key */
             Call SysStemSort "MyStem.", "D",,,,5, 10

            /* sort all elements ascending, ignore the case */
             Call SysStemSort "MyStem.", "A", "I"

            /* sort elements 10 to 20 ascending, use cols 1 to 10 as key */
             Call SysStemSort "MyStem.",,,10, 20, 1, 10

 Return:    0 - sort was successful
           -1 - sort failed


 SysVersion
 ----------

 Syntax: result = SysVersion()

 Params: None

 Function: This function returns a string to identify the operating system
           and its version. The returned string contains an identifier for
           the operating system as the first word and then the version in
           the second word.

           Examples:
            Say SysVersion()       /* show OS and version */

 Return: Operating system and version

         Possible output for operating systems supported by Object REXX:

          Say SysVersion()   ->  "WindowsNT 4.00"
          Say SysVersion()   ->  "OS/2 2.40"
          Say SysVersion()   ->  "AIX 4.2"
          Say SysVersion()   ->  "Linux 2.0.34"

Note: This function can be used to replace the operating system specific
      functions SysOS2Ver(), SysWinVer(), and SysLinVer().




 SysUtilVersion
 --------------

 Syntax: result = SysUtilVersion()

 Params: None

 Function: This function returns a version number that identifies the current
           level of the REXX Utilities package. This can be used to verify
           that certain functions are available.

           Examples:

           Since this function was not part of the original packaging a
           sample logic to check for a certain level of REXXUTIL could look
           like this:

              If RxFuncQuery("SysUtilVersion") = 1 |,
                 SysUtilVersion() < "2.00" Then
                   Say "Your REXXUTIL.DLL is not at the current level"

           If a specific function should be used that was added at a later
           REXXUTIL level a similar check can be performed by querying that
           function:

              If RxFuncQuery("SysSetFileDateTime") = 1 Then
                Say "Your REXXUTIL.DLL is not at the current level"

 Return:  REXXUTIL version number in the format (n.mm)
