home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rexxupda.zip / readrexx.txt next >
Text File  |  2000-04-11  |  15KB  |  449 lines
  1.  
  2.  
  3.                                 REXX FUNCTIONS
  4.                                 --------------
  5.  
  6.  ┌────────────────────────────────────────────────────────────────────────┐
  7.  │                                                                        │
  8.  │ >>──SysQueryExtLIBPATH(flag)────────────────────────────────────────>< │
  9.  │                                                                        │
  10.  └────────────────────────────────────────────────────────────────────────┘
  11.  
  12.  This function returns the current path to be searched before or after the
  13.  system LIBPATH when locating DLLs.
  14.  
  15.  Parameters
  16.  
  17.   flag
  18.       The flag controlling which extended LIBPATH should be returned:
  19.  
  20.         'B'            Return the BEGINLIBPATH setting.
  21.         'E'            Return the ENDLIBPATH setting.
  22.  
  23.  Example:
  24.  
  25.  /* Show the current setting of the extended LIBPATH */
  26.   say "BEGINLIBPATH is:" SysQueryExtLIBPATH("B")
  27.   say "ENDLIBPATH is:  " SysQueryExtLIBPATH("E")
  28.  
  29.  
  30.  
  31.  ┌────────────────────────────────────────────────────────────────────────┐
  32.  │                                                                        │
  33.  │ >>──SysQuerySwitchList(stem──┬────────┬──)──────────────────────────>< │
  34.  │                              └─,flags─┘                                │
  35.  │                                                                        │
  36.  └────────────────────────────────────────────────────────────────────────┘
  37.  
  38.  This function obtains information about the entries in the Window List.
  39.  By default only visible and jumpable entries will be returned.
  40.  
  41.  Parameters
  42.  
  43.   stem
  44.       The name of a REXX stem variable. SysQuerySwitchList sets REXX
  45.       variable stem.0 to the number of Window List entries and stores the
  46.       individual entries in stem.1 to stem.n.
  47.  
  48.   flags
  49.        Any combination of the following:
  50.  
  51.         'I'  Include invisible entries in the list.
  52.         'G'  Include grayed entries in the list.
  53.         'N'  Include entries in the list that are not jumpable.
  54.         'D'  Return the list in the detailed form: PID SID Visibility
  55.              Jumpable ProgType Name
  56.  
  57.        The returned values are directly taken from the SWCNTRL structure.
  58.        For description of the possible values see the PM Guide and
  59.        Reference.
  60.  
  61.  Example:
  62.  
  63.  /* Type the Window List */
  64.   call SysQuerySwitchList "list."
  65.   do i = 1 to list.0
  66.     say 'Entry' i 'is' list.i
  67.   end
  68.  
  69.  
  70.  
  71.  ┌────────────────────────────────────────────────────────────────────────┐
  72.  │                                                                        │
  73.  │ >>──SysSetExtLIBPATH(─┬──────┬─,flag)───────────────────────────────>< │
  74.  │                       └─path─┘                                         │
  75.  │                                                                        │
  76.  └────────────────────────────────────────────────────────────────────────┘
  77.  
  78.  This function defines the current path to be searched before or after the
  79.  system LIBPATH when locating DLLs.
  80.  The OS/2 error code will be returned (0 if successful).
  81.  
  82.  Parameters
  83.  
  84.   path
  85.       The extended LIBPATH string. The string can be up to 1024 characters
  86.       long. The extended LIBPATH may contain the strings "%BEGINLIBPATH%"
  87.       or "%ENDLIBPATH%" in which case the current values will be inserted
  88.       in the resulting extended LIBPATH. However, if the resulting extended
  89.       LIBPATH is longer than 1024 characters, the function will return an
  90.       error.
  91.  
  92.       To remove the current extended LIBPATH you can specify an empty
  93.       string or omit this parameter.
  94.  
  95.   flag
  96.       The flag controlling which extended LIBPATH should be set:
  97.  
  98.        'B'            Set the BEGINLIBPATH.
  99.        'E'            Set the ENDLIBPATH.
  100.  
  101.  Example:
  102.  
  103.  /* Add D:\TEST to BEGINLIBPATH and delete ENDLIBPATH */
  104.   Call SysSetExtLIBPATH "D:\TEST;%BEGINLIBPATH%", "B"
  105.   Call SysSetExtLIBPATH , "E"
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  ┌────────────────────────────────────────────────────────────────────────┐
  112.  │                                                                        │
  113.  │ >>──SysSwitchSession(name)──────────────────────────────────────────>< │
  114.  │                                                                        │
  115.  └────────────────────────────────────────────────────────────────────────┘
  116.  
  117.  This function makes a specific program the active program. The function
  118.  returns the error code from WinSwitchToProgram (0 if successful).
  119.  
  120.  Parameters
  121.  
  122.  name
  123.      The name of the session to switch to. The name must match the
  124.      appropriate program name as used in the Window List
  125.      (see function SysQuerySwitchList).
  126.  
  127.  
  128.  
  129.  SysDumpVariables
  130.  ----------------
  131.  
  132.  Syntax: result = SysDumpVariables([filename])
  133.  
  134.  Params: filename - name of the file where variables are appended to
  135.          (dump is written to STDOUT if omitted)
  136.  
  137.  Function: This function dumps all variables in the current scope either
  138.            to the specified file (new data will be appended) or to STDOUT
  139.            if the filename parameter is omitted. The format of the data
  140.            is (one variable per line):
  141.            Name=MYVAR, Value="This is the content of MYVAR"
  142.  
  143.            Examples:
  144.              Call SysDumpVariables "MyVars.Lst" /* append vars to file */
  145.              Call SysDumpVariables              /* list vars on STDOUT */
  146.  
  147.  Return:    0 - dump completed OK
  148.            -1 - failure during dump
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  SysSetFileDateTime
  159.  ------------------
  160.  
  161. Syntax: result = SysSetFileDateTime(filename [,newdate] [,newtime])
  162.  
  163. Params: filename - name of the file to update
  164.         newdate  - new date to set in format YYYY-MM-DD
  165.          OS/2: (YYYY > 1980)
  166.           Win: (YYYY > 1800)
  167.     AIX/Linux: (YYYY > 1900)
  168.     newtime  - new time to set in format HH:MM:SS (24 hr format)
  169.  
  170. Function: This function can be used to modify the "Last Modified"
  171.           Date of the specified file. If no new date or new time is
  172.           specified then the file date and time will be set to the
  173.           current time (TOUCH). If only one of date or time is omitted
  174.           then this parameter will be left unchanged.
  175.  
  176.           For OS/2 and Windows NT the filename may also specify a directory
  177.           name. This does not work with Windows 95/98 or AIX/Linux however.
  178.  
  179.           The file you want to change must not be opened by another process
  180.           or at least it must allow shared writes in order to update the
  181.           timestamp.
  182.  
  183.           Examples:
  184.               Call SysSetFileDateTime "MyFile.Log"  /* touch file */
  185.               Call SysSetFileDateTime "MyFile.Log", "1998-12-17"
  186.               Call SysSetFileDateTime "MyFile.Log",, "16:37:21"
  187.               Call SysSetFileDateTime "MyFile.Log", "1998-12-17", "16:37:21"
  188.  
  189.               Call SysSetFileDateTime "C:\MyDir"  /* touch dir on OS/2, NT */
  190.  
  191.  Return:    0 - file date/time was updated correctly
  192.            -1 - failure attribute update
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  SysGetFileDateTime
  212.  ------------------
  213.  
  214.  Syntax: result = SysGetFileDateTime(filename [,timesel])
  215.  
  216.  Params: filename - name of the file to query
  217.            timesel  - What filetime to query: CREATE/ACCESS/WRITE
  218.  
  219. Function: The function call returns the selected file date time attribute
  220.           of the specified file if this is supported by the operating
  221.           and file system (e.g. FAT does not provide Create/Access). The
  222.           selector for the time to be returned can be abbreviated with
  223.           its first character.
  224.  
  225.           For OS/2 and Windows NT the filename may also specify a directory
  226.           name. This does not work with Windows 95/98 or AIX/Linux however.
  227.  
  228.           The file you want to query must not be opened by another process
  229.           or at least it must allow shared reads in order to query the
  230.           timestamp.
  231.  
  232.     Examples:
  233.       Say "File creation time:" SysGetFileDateTime("MyFile.Log", "C")
  234.       Say "File last access time:" SysGetFileDateTime("MyFile.Log", "A")
  235.       Say "File last update time:" SysGetFileDateTime("MyFile.Log", "W")
  236.  
  237.       Say "Directory creation time:" SysGetFileDateTime("C:\MyDir", "C")
  238.  
  239.  Return: -1 - file date/time query failed
  240.          other - date and time as YYYY-MM-DD HH:MM:SS
  241.  
  242.  
  243.  
  244.  SysStemCopy
  245.  -----------
  246.  
  247.  Syntax: result = SysStemCopy(fromstem, tostem, [from], [to], [count]
  248.                   [,insert])
  249.  
  250.  Params: fromstem - name of source stem
  251.          tostem - - name of target stem
  252.          from  - first index in source stem to copy
  253.          to - position where items are copied/inserted in target stem
  254.          count - number of items to copy/insert
  255.          insert - 'I' to indicate insert instead of 'O' overwrite
  256.  
  257.  
  258.  
  259.  
  260.  Function: Copy elements from the source stem to the target stem. Elements
  261.            in the source stem are copied starting at the from index
  262.            (default 1) into the target stem beginning at the to index
  263.            (default 1). The number of items to copy to the target stem can
  264.            be specified with count (default is to copy all items in the
  265.            source stem). You can optionally specify that the items should
  266.            be inserted into the target stem at the position and the
  267.            existing items will be shifted to the back accordingly.
  268.  
  269.            This function operates only on stem arrays that specify the
  270.            number of elements in stem.0 and all elements must be numbered
  271.            from 1 to n with no omitted index.
  272.  
  273.            Examples:
  274.              Source.0 = 3
  275.              Source.1 = "Hello"
  276.              Source.2 = "from"
  277.              Source.3 = "REXX"
  278.              Call SysStemCopy "Source.", "Target."
  279.  
  280.              Call SysStemCopy "Source.", "Target.", 1, 5, 2, "I"
  281.  
  282.  Return:    0 - stem copy was successful
  283.            -1 - stem copy failed
  284.  
  285.  
  286.  
  287.  SysStemDelete
  288.  -------------
  289.  
  290.  Syntax: result = SysStemDelete(stem, startitem [,itemcount])
  291.  
  292.  Params: stem - name of stem where item will be deleted
  293.          startitem - index of item to delete
  294.          itemcount - number of items to delete if more than 1
  295.  
  296. Function: Deletes the specified item at index startitem in the stem.
  297.           If more than one item is to be deleted then the count of
  298.           items can be specified as the third parameter. After deleting
  299.           the requested items the stem will be compacted, that means
  300.           items following the deleted items will be shifted up into the
  301.           vacant positions.
  302.  
  303.           This function operates only on stem arrays that specify the number
  304.           of elements in stem.0 and all elements must be numbered from 1 to
  305.           n with no omitted index.
  306.  
  307.           Examples:
  308.  
  309.             Call SysStemDelete "MyStem.", 5
  310.  
  311.             Call SysStemDelete "MyStem.", 5, 4
  312.  
  313.  Return:    0 - delete was successful
  314.            -1 - delete failed
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  SysStemInsert
  321.  -------------
  322.  
  323.  Syntax: result = SysStemInsert(stem, position, value)
  324.  
  325.  Params: stem - name of stem where item will be inserted
  326.          position - index where new item will be inserted
  327.          value - new item value
  328.  
  329.  Function: A new item will be inserted at the specified position in
  330.            the stem. All existing items in the stem from the specified
  331.            position will be shifted up by one to make room for the new
  332.            item.
  333.  
  334.            This function operates only on stem arrays that specify the
  335.            number of elements in stem.0 and all elements must be numbered
  336.            from 1 to n with no omitted index.
  337.  
  338.            Example:
  339.              Call SysStemInsert "MyStem.", 5, "New value for item 5"
  340.  
  341.  Return:    0 - insert was successful
  342.            -1 - insert failed
  343.  
  344.  
  345.  
  346.  SysStemSort
  347.  -----------
  348.  
  349.  Syntax: result = SysStemSort(stem, order, type, start, end,
  350.                   firstcol, lastcol)
  351.  
  352.  Params: stem - name of stem to sort
  353.          order - 'A' or 'D' for sort order (default: ascending)
  354.          type - 'C', 'I'  for comparision type (case/ignore, default: case)
  355.          start - first index to sort (default: 1)
  356.          end - last index to sort (default: last item)
  357.          firstcol - first column to use as sort key (default: 1)
  358.          lastcol - last column to use as sort key (default: last column)
  359.  
  360.  Function: This call sorts all or the specified items in the stem.
  361.            Sort order can be specified as ascending or descending,
  362.            comparison type can respect or ignore the case of the strings
  363.            being compared. The sorting can further be narrowed by specifying
  364.            the first and last item to be sorted or by specifying the columns
  365.            used as the sorting key. The sort uses a quicksort algorithm, so
  366.            the order of equal elements according to the sort key is
  367.            undetermined.
  368.  
  369.  
  370.  
  371.  
  372.            This function operates only on stem arrays that specify the
  373.            number of elements in stem.0 and all elements must be numbered
  374.            from 1 to n with no omitted index.
  375.  
  376.            Examples:
  377.             /* sort all elements descending, use cols 5 to 10 as key */
  378.              Call SysStemSort "MyStem.", "D",,,,5, 10
  379.  
  380.             /* sort all elements ascending, ignore the case */
  381.              Call SysStemSort "MyStem.", "A", "I"
  382.  
  383.             /* sort elements 10 to 20 ascending, use cols 1 to 10 as key */
  384.              Call SysStemSort "MyStem.",,,10, 20, 1, 10
  385.  
  386.  Return:    0 - sort was successful
  387.            -1 - sort failed
  388.  
  389.  
  390.  SysVersion
  391.  ----------
  392.  
  393.  Syntax: result = SysVersion()
  394.  
  395.  Params: None
  396.  
  397.  Function: This function returns a string to identify the operating system
  398.            and its version. The returned string contains an identifier for
  399.            the operating system as the first word and then the version in
  400.            the second word.
  401.  
  402.            Examples:
  403.             Say SysVersion()       /* show OS and version */
  404.  
  405.  Return: Operating system and version
  406.  
  407.          Possible output for operating systems supported by Object REXX:
  408.  
  409.           Say SysVersion()   ->  "WindowsNT 4.00"
  410.           Say SysVersion()   ->  "OS/2 2.40"
  411.           Say SysVersion()   ->  "AIX 4.2"
  412.           Say SysVersion()   ->  "Linux 2.0.34"
  413.  
  414. Note: This function can be used to replace the operating system specific
  415.       functions SysOS2Ver(), SysWinVer(), and SysLinVer().
  416.  
  417.  
  418.  
  419.  
  420.  SysUtilVersion
  421.  --------------
  422.  
  423.  Syntax: result = SysUtilVersion()
  424.  
  425.  Params: None
  426.  
  427.  Function: This function returns a version number that identifies the current
  428.            level of the REXX Utilities package. This can be used to verify
  429.            that certain functions are available.
  430.  
  431.            Examples:
  432.  
  433.            Since this function was not part of the original packaging a
  434.            sample logic to check for a certain level of REXXUTIL could look
  435.            like this:
  436.  
  437.               If RxFuncQuery("SysUtilVersion") = 1 |,
  438.                  SysUtilVersion() < "2.00" Then
  439.                    Say "Your REXXUTIL.DLL is not at the current level"
  440.  
  441.            If a specific function should be used that was added at a later
  442.            REXXUTIL level a similar check can be performed by querying that
  443.            function:
  444.  
  445.               If RxFuncQuery("SysSetFileDateTime") = 1 Then
  446.                 Say "Your REXXUTIL.DLL is not at the current level"
  447.  
  448.  Return:  REXXUTIL version number in the format (n.mm)
  449.