home *** CD-ROM | disk | FTP | other *** search
/ Merciful 3 / Merciful_Release_3.bin / software / d / data_division_docs / datadivisiondocs02.dms / datadivisiondocs02.adf / 17 < prev    next >
Text File  |  1996-10-14  |  72KB  |  1,893 lines
  1.  
  2.                              Chapter Sixteen
  3.  
  4. ARexx ...........................................205
  5. ARexx Commands ..................................206
  6.     dopus .......................................206
  7.     lister ......................................213
  8.     command .....................................239
  9. ARexx Error Codes ...............................239
  10. Custom Handlers .................................241
  11.     Custom Handlers for Listers .................241
  12.     Trapped Functions ...........................245
  13.     AddStem Pop-Ups .............................245
  14.     Custom Handlers for AppIcons ................246
  15. ARexx Modules ...................................248
  16.  
  17.  
  18.                                   ARexx
  19.  
  20.  The Directory Opus 5 ARexx port name is DOPUS.x, where x is the
  21. invocation count of the program (the first and most often used one is
  22. DOPUS.1).  Since ARexx scripts launched from Directory Opus do not
  23. automatically inherit the command address, you may want to use the {Qp}
  24. command sequence in Opus functions (this is described elsewhere in the
  25. manual).
  26.  
  27.  If a command returns a value or information, the data will generally be
  28. returned in the RESULT variable.  The only exceptions to this are the
  29. dopus getstring and lister getstring commands (see below) which return
  30. information in the special DOPUSRC variable.  Error codes are returned in
  31. the RC variable.
  32.  
  33.  The ARexx command set is very comprehensive and flexible. Almost complete
  34. control of listers in name mode is offered, along with the ability to
  35. launch functions and commands. You can add your own commands to Opus via
  36. ARexx scripts which are loaded automatically - the commands appear
  37. identical to the built-in functions. You can even replace the default
  38. commands with your own.
  39.  
  40.  There is also a powerful custom handler ability. This allows your ARexx
  41. program to receive messages from Opus for a variety of user actions,
  42. including lister and icon events. See the section on Custom Handlers on
  43. page 241 for more information.
  44.  
  45.                              Directory Opus 5                        205
  46.  
  47.                               ARexx Commands
  48.  
  49.  For simplicity, the Directory Opus 5 command set is arranged in a
  50. hierarchical structure, with only three main (or base) commands:- dopus,
  51. lister and command.
  52.  
  53.     dopus
  54.  
  55.  The first base command is dopus.  This is a general purpose command, and
  56. allows you to perform functions not falling into the other categories.
  57.  
  58.   *     dopus addappicon <port> <label> <id> [pos <x> <y>]
  59.         [icon<filename>] [quotes] [info] [snap] [close]
  60.         [local] [locked] [menu <stem>] [base <base>]
  61.  
  62.         This command allows you to add your own AppIcons to the DOpus (and
  63.      optionally the Workbench) screen from ARexx. You can specify an icon
  64.      image to use, the label of the icon and the position on the screen,
  65.      as well as several other parameters. You can also specify the items
  66.      for the pop-up menu for the new icon. Opus sends messages to the
  67.      message port you specify - see the example scripts provided for more
  68.      information on how to receive and process these messages.
  69.  
  70.         The parameters for "addappicon" are:-
  71.  
  72.               port    -    the name of the port messages are sent to
  73.               label   -    the icon label (text displayed under the icon)
  74.               id      -    your own ID for the icon; this is returned in
  75.                            messages
  76.               pos     -    position for the icon (xy coordinates)
  77.               icon    -    optional pathname of icon file to use (without
  78.                            the .info suffix)
  79.               quotes  -    specify this keyword if you want filenames
  80.                            quoted when sent to the message port
  81.               info    -    if you want Information to work on this icon
  82.               snap    -    if you want Snapshot to work on this icon
  83.               close   -    if you want Close instead of Open in
  84.                            the pop-up menu
  85.                            
  86.      206                     Directory Opus 5
  87.  
  88.               local   -    if you want the icon to be local to Opus
  89.                            (and not appear on Workbench)
  90.               locked  -    the icon will start out locked in position,
  91.                            unable to be moved
  92.               menu    -    name of a stem variable containing
  93.                            your own menu items
  94.               base    -    allows you to specify the base ID of
  95.                            messages sent from the pop-up menu
  96.  
  97.         The menu parameter allows you to specify your own items for the
  98.      icon's pop-up menu. The stem variable must be in the following
  99.      format:
  100.  
  101.                 stem.COUNT      - number of items
  102.                 stem.0 - item 1
  103.                 stem.1 - item 2
  104.                 etc.
  105.  
  106.         If you specify "---" as an item, a separator bar will appear. When
  107.      you receive a message that the user has selected one of these menu
  108.      items, the message will contain the ID of the item. This is the value
  109.      corresponding to the item's position in the stem array (eg 0 for item
  110.      1, 1 for item 2, etc). If the base field is specified, the value
  111.      given for the base will be added to this ID.
  112.  
  113.      This command returns an appicon handle in RESULT if it is successful.
  114.      This same handle can be passed to dopus setappicon to modify the
  115.      icon, and must be passed to dopus remappicon to remove the appicon
  116.      when you are finished.  If you do not specify an icon file to use
  117.      then the system's default "tool" icon will be used for the image.
  118.  
  119.      Messages from the appicon are sent to the port you specified.  The
  120.      messages are structured in much the same way as messages sent from
  121.      listers, so there's no reason you shouldn't be able to use the same
  122.      code for both.  For more information, see the Custom Handlers
  123.      section on page 241.
  124.      
  125.                              Directory Opus 5                        207
  126.  
  127.   *     dopus addtrap [abort |<command>] <handler> [port <portname>]
  128.  
  129.         This command allows your script to trap the progress bar's abort
  130.      button or any Opus internal command.  Specify the abort keyword to
  131.      trap the abort message, or the name of the internal command you wish
  132.      to trap. handler is the name of your custom handler message port. If
  133.      you pass the name of a message port with the optional port keyword,
  134.      the message will be sent to that port instead of your usual handler
  135.      port.  This can be very useful when used with abort if your handler
  136.      is busy doing something synchronously when the abort is pressed.  If
  137.      the abort port is on a separate process, it may be able to interrupt
  138.      the main handler process using signals for instance. The dopus
  139.      remtrap command is used to remove trapped functions. See the Custom
  140.      Handlers section on page 241 for more information on the messages
  141.      sent.
  142.  
  143.   *     dopus back
  144.  
  145.         This command moves the Directory Opus 5 window (and screen) to the
  146.      rear of the display.
  147.  
  148.   *     dopus command <name> program <scriptname> [desc <description>]
  149.         [template <template>] [source] [dest]
  150.  
  151.         This command provides the ability to add new internal commands to
  152.      Directory Opus, or to replace existing commands.  It is generally
  153.      called from within the init function of an Opus ARexx module and the
  154.      program parameter will be the name of that module.  The program field
  155.      is mandatory, and Opus will run the script name you provide here
  156.      whenever this function is invoked. See ARexx modules and the example
  157.      script on page 248 for more information.
  158.  
  159.   *     dopus error <code>
  160.  
  161.         This command is used to retrieve meaningful error messages when
  162.      passed an Opus ARexx error code.  For example,
  163.  
  164.      208                     Directory Opus 5
  165.  
  166.                 > dopus error 1
  167.                         --> File rejected by filters
  168.                 > dopus error 10
  169.                         --> Invalid lister handle
  170.  
  171.   *     dopus front
  172.  
  173.      This command moves the Directory Opus 5 window (and screen) to the
  174.      front of the display.
  175.  
  176.   *     dopus getfiletype <filename> [id]
  177.  
  178.      This command allows you to query a file to see if it is recognised by
  179.      Directory Opus 5.  <filename> is the name of the file, including the
  180.      full path.  By default, if the file is recognised the Filetype
  181.      description string will be returned in RESULT.  If you specify the id
  182.      keyword, the Filetype ID will be returned instead.  For example,
  183.  
  184.                 > dopus getfiletype ram:testfile.lha
  185.                         --> LHA Archive
  186.                 > dopus getfiletype ram:picture.jpg id
  187.                          --> JPEG
  188.  
  189.   *     dopus getstring <text> [secure] [<length>] [<default]> [<buttons>]
  190.  
  191.         This command allows you to prompt the user to input a text string.
  192.      <text> is a string of text to be displayed in the requester, and
  193.      should be surrounded by quotes if it contains spaces.  The secure
  194.      keyword causes the string to be displayed as asterisks, which can be
  195.      useful for passwords.  <length> is the maximum length of the string
  196.      to accept and defaults to 80 if not specified.  <default> is the
  197.      default value of the string; that is, the text you wish to initially
  198.      appear in the field.  <buttons> are the buttons you wish the
  199.      requester to have; each button should be separated by a vertical bar
  200.      character.  If the buttons parameter is omitted the requester will
  201.      have a single button marked 'OK'.  For example,
  202.  
  203.         > dopus getstring '"Please enter some text" 40 ""Okay|Cancel'
  204.  
  205.                              Directory Opus 5                        209
  206.  
  207.         This would display a requester with the string "Please enter some
  208.      text", a maximum input length of 40 characters, no default text, and
  209.      buttons labelled Okay and Cancel.
  210.  
  211.         The string (if any) is returned in RESULT.  The cardinal number of
  212.      the selected button is returned in the special variable DOPUSRC.  In
  213.      the above example, if the user clicked Okay, DOPUSRC would contain 1,
  214.      and if the user clicked Cancel it would contain 0.  This command and
  215.      the lister getstring command are the only ones that use the DOPUSRC
  216.      variable currently, but this may change in the future.
  217.  
  218.   +-------------------------------------------------------------------+
  219.   | Please note that previous versions of Opus 5 did not clear RESULT |
  220.   | if an empty string was entered.  Make sure that this change does  |
  221.   | not affect your scripts.                                          |
  222.   +-------------------------------------------------------------------+
  223.  
  224.   *      dopus read <filename>
  225.   *      dopus read <handle> <filename>
  226.   *      dopus read <handle> quit
  227.  
  228.      The read command is provided to allow you greater control over the
  229.      Opus text viewer.  They basically allow you to open a viewer and view
  230.      multiple files in it one by one before closing it again.  You use the
  231.      viewer handle in much the same way as you would a lister handle.  For
  232.      example,
  233.  
  234.                 > dopus read ram:file1.txt
  235.                         --> 121839492
  236.                 > dopus read 121839492 ram:file2.txt
  237.                         --> 121839492
  238.                 > dopus read 121839492 quit
  239.                          --> 0
  240.  
  241.   *     dopus remappicon <handle>
  242.  
  243.      Removes an appicon that was added previously with the dopus
  244.      addappicon command.
  245.  
  246.      210                     Directory Opus 5
  247.  
  248.   *     dopus remtrap [abort | <command>] <handler>
  249.  
  250.      Disables the trapping of the progress bar's abort button or the
  251.      specified Opus internal command as initiated with the dopus addtrap
  252.      command.  If you specify "*" as the command, all traps added for this
  253.      handler will be removed. handler is the name of the message port as
  254.      specified in the dopus addtrap command.
  255.  
  256.   *     dopus request <text> <buttons>
  257.  
  258.      This command allows you to request a choice from the user.  <text> is
  259.      a string of text to be displayed in the requester.  <buttons> are the
  260.      buttons you wish the requester to have; each button should be
  261.      separated by a vertical bar character.  For example,
  262.  
  263.                 > dopus request '"Please choose an option" "
  264.                         Option 1|Option 2|Option 3"' (all one line)
  265.  
  266.      This would display a requester with the string "Please choose an
  267.      option", and three buttons labelled Option 1, Option 2 and Option 3.
  268.  
  269.      The cardinal number of the selected button is returned in RC.  The
  270.      last button supplied (Option 3 in this case) is designated a Cancel
  271.      button, and so returns the value 0.  Therefore, the values returned
  272.      by this example are 1, 2 and 0 respectively.
  273.  
  274.   *     dopus screen
  275.  
  276.      This command returns information about the Opus screen in the
  277.      following format:-
  278.  
  279.                 <name> <width> <height> <depth> <barheight>
  280.  
  281.      If Opus is iconified it does not have a screen.  In this case RC will
  282.      be set to 5.  You can use this to find out whether or not Opus is
  283.      currently iconified.  Here is an example of the output:
  284.  
  285.                 > dopus screen
  286.                         --> DOPUS.1 640 512 2 10
  287.                         
  288.                              Directory Opus 5                        211
  289.                         
  290.       The barheight value is useful if you intend to open listers or other
  291.       windows just below the screen title bar.
  292.  
  293.   *     dopus send <port name> <string>
  294.  
  295.      This command does nothing to DOpus itself, but instead makes it easy
  296.      for you to send a string (or any length) to another ARexx task (via a
  297.      message). The string is supplied in Arg0 of the message sent to the
  298.      named port.
  299.  
  300.   *     dopus setappicon <handle> <item>
  301.  
  302.      This allows you to do things to AppIcons added with the dopus
  303.      addappicon command. Valid <item> fields are :-
  304.  
  305.      text   <text>
  306.  
  307.      Change the icon label.
  308.  
  309.      busy   [on |off]
  310.  
  311.      Make icon busy or non-busy.
  312.  
  313.      locked [on |off]
  314.  
  315.      Make icon locked or unlocked.
  316.  
  317.  If an icon is busy, it is unselectable by the user. It will not respond
  318. to double-clicks, pop-up menu events, drag'n'drops, etc. The icon image is
  319. ghosted when it is busy.  When an icon is locked, its position can not be
  320. changed and it can not be moved manually by the user, nor will a CleanUp
  321. will not affect it.
  322.  
  323.   *     dopus version
  324.  
  325.       The version command returns a string in the format <version>
  326.      <revision> and is useful in ARexx scripts for determining if certain
  327.      features exist.
  328.      
  329.      212                     Directory Opus 5     
  330.  
  331.    lister
  332.  
  333.  The next base command, lister, allows you to control listers and entries
  334. within listers.
  335.  
  336.  *   lister add <handle> <name> <size> <type><seconds> <protect> <comment>
  337.  
  338.      This command adds an entry to the specified lister.  <name> is the
  339.      full name of the entry; <size> is the size of the entry; <type> is
  340.      the type of the entry (less than 0 for a file, greater then 0 for a
  341.      directory); <seconds> is the datestamp of the entry in seconds from
  342.      1/1/78; <protect> is the protection bits of the file (in ascii
  343.      format); <comment> is the comment of the entry (if any).  Valid entry
  344.      types are:-
  345.  
  346.                  0      device
  347.                  1      plain directory
  348.                 -1      plain file
  349.                  2      directory in assign colour
  350.                 -2      file in device colour
  351.                  3      directory in bold (link)
  352.                 -3      file in bold (link)
  353.                  4      directory in assign colour and bold
  354.                 -4      file in device colour and bold
  355.  
  356.   +--------------------------------------------------------------------+
  357.   | After a 'lister add' command, the display is not updated until you |
  358.   | execute a 'lister refresh' command.                                |
  359.   +--------------------------------------------------------------------+
  360.  
  361.         For example,
  362.  
  363.                 > lister add 121132636 '"My file!"' 12839 -1 540093905
  364.                         prwed my comment
  365.  
  366.   *     lister addstem <handle> <stem>
  367.  
  368.      This command adds files to a lister via a stem variable.  It is more
  369.      powerful than the lister add command and should be used in
  370.      preference. The fields of the stem variable are very similar to those
  371.      returned by a lister query <handle> entry stem command (in fact,  you
  372.      could pass the result the query  directly to an addstem  to add an
  373.    
  374.                              Directory Opus 5                        213
  375.      
  376.      identical entry to another lister.) The fields that are used are :-
  377.  
  378.         name            - name of entry
  379.         size            - file size
  380.         type            - type of entry (same as for lister add)
  381.         protstring      - protection bits (ASCII string, eg "rwed")
  382.         protect         - protection value (number, used if
  383.                            protstring is not given)
  384.         comment         - file comment
  385.         datestring      - creation date and time (ASCII string)
  386.         date            - number of seconds since 1/1/78 (used
  387.                           if datestring is not given)
  388.         filetype        - ascii string for file type display
  389.         selected        - 0 or 1
  390.         version         - version number
  391.         revision        - revision number
  392.         verdate         - version date string
  393.         userdata        - user data (value, not a string)
  394.         display         - custom display string
  395.         menu            - custom pop-up menu
  396.         base            - base ID for pop-up menu
  397.  
  398.      Not all of these fields are required. As a bare minimum you should
  399.      specify either the name or the display field.
  400.  
  401.      The display string allows you to specify a completely custom string
  402.      to display for the entry.  None of the other information will be
  403.      displayed if this string is supplied.  The maximum length is 256
  404.      characters.
  405.  
  406.      The userdata field allows you to specify your own ID value (or any
  407.      other value) to be associated with this entry. Its main usage is with
  408.      the custom pop-up menu and custom handlers.
  409.  
  410.      The menu field allows you to specify a stem variable containing
  411.      custom items for the pop-up menu that appears when the user presses
  412.      the right button on this entry.  Its format is the same as for
  413.      AppIcon pop-up menus;
  414.  
  415.         stem.COUNT - number of entries
  416.         stem.BASE  - base ID
  417.         
  418.      214                     Directory Opus 5
  419.         
  420.         stem.0 - entry 1
  421.         stem.1 - entry 2
  422.  
  423.      If count is set to 0, right-button pop-ups will be disabled for this
  424.      file. If this field is not specified, the default pop-up menu will be
  425.      displayed. If you specify "---" as an item, a separator bar will
  426.      appear. When you receive a message that the user has selected one of
  427.      these menu items, the message will contain the ID of the item. This
  428.      is the value corresponding to the item's position in the stem array
  429.      (eg 0 for item 1, 1 for item 2, etc). If the base field is specified,
  430.      the value given for the base will be added to this ID.
  431.  
  432.         See the Custom Handlers section later in this chapter for more
  433.      information on the messages sent.
  434.  
  435.   *     lister copy <handle> <destination>
  436.  
  437.      This command copies the contents of one lister to another lister.
  438.      Unlike most commands, the display of the destination lister is
  439.      refreshed immediately.  For example,
  440.  
  441.                 > lister copy 121132636 121963868
  442.  
  443.   *     lister clear <handle>
  444.  
  445.      This command clears the contents of the specified lister.  The
  446.      display will not be updated until you execute a lister refresh
  447.      command.
  448.  
  449.  +------------------------------------------------------------------+
  450.  |    In previous versions of Opus 5, this command also cleared the |
  451.  |   custom handler name.  This is no longer the case.              |
  452.  +------------------------------------------------------------------+
  453.  
  454.   *     lister clear <handle> <item> <value>
  455.  
  456.      This command clears a particular item of information in the specified
  457.      lister.  <handle> is the handle of the lister in question; <item> can
  458.      be one of the following keywords:-
  459.  
  460.                              Directory Opus 5                        215
  461.  
  462. abort
  463.  
  464.  This clears the abort flag in the specified lister.
  465.  
  466.         > lister clear 121132636 abort
  467.  
  468. flags <flags>
  469.  
  470.  Clears sort/display flags for this lister.  The display is not updated
  471. unless you execute a lister refresh command.  See the lister query section
  472. for the keywords to use.  For example,
  473.  
  474.         > lister clear 121132636 flags reverse
  475.  
  476. progress
  477.  
  478.  This turns the progress indicator off in the specified lister.
  479.  
  480.         > lister clear 121132636 progress
  481.  
  482.   *     lister close [all |<handle>]
  483.  
  484.      This command closes the specified lister or all listers if the all
  485.      keyword is supplied in place of a lister handle.  Any function that
  486.      is currently taking place will be aborted.  <handle> is the lister
  487.      handle that was returned when you created this lister with the lister
  488.      new command.       For example,
  489.  
  490.                 > lister close 121132636
  491.  
  492.   *     lister empty <handle>
  493.  
  494.      This command will display an empty cache in the specified lister
  495.      (unlike lister clear which clears the contents of the current cache).
  496.      If no empty caches are available (and a new one can not be created),
  497.      the existing cache will be cleared.  If the lister has a custom
  498.      handler attached, it will receive an inactive message.
  499.  
  500.   +-------------------------------------------------------------------+
  501.   | Note that previous versions of Opus 5 did not send the 'inactive' |
  502.   | message to the custom handler when this command was used.         |
  503.   +-------------------------------------------------------------------+
  504.   
  505.      216                     Directory Opus 5
  506.   
  507.   *    lister getstring <handle> <text> [secure] [<length>] [<default]>
  508.        [<buttons>]
  509.  
  510.      This command is identical to the dopus getstring command except that
  511.      it takes a lister handle as an additional parameter and the requester
  512.      will be centred over that lister.
  513.      <text> is a string of text to be displayed in the requester, and
  514.      should be surrounded by quotes if it contains spaces.  The secure
  515.      keyword causes the string to be displayed as asterisks, which can be
  516.      useful for passwords.  <length> is the maximum length of the string
  517.      to accept and defaults to 80 if not specified.  <default> is the
  518.      default value of the string; that is, the text you wish to initially
  519.      appear in the field.  <buttons> are the buttons you wish the
  520.      requester to have; each button should be separated by a vertical bar
  521.      character.  If the buttons parameter is omitted the requester will
  522.      have a single button marked 'OK'.  For example,
  523.  
  524.                 > lister getstring 121132636 '"Please enter some text"
  525.                         40 "" Okay|Cancel'
  526.  
  527.      This would display a requester over the lister with the string
  528.      "Please enter some text", a maximum input length of 40 characters, no
  529.      default text, and buttons labelled Okay and Cancel.
  530.  
  531.      The string (if any) is returned in RESULT.  The cardinal number of
  532.      the selected button is returned in the special variable DOPUSRC.  In
  533.      the above example, if the user clicked Okay, DOPUSRC would contain 1,
  534.      and if the user clicked Cancel it would contain 0.  This command and
  535.      the dopus getstring command are the only ones that use the DOPUSRC
  536.      variable currently, but this may change in the future.
  537.  
  538.  
  539.   *    lister new [<x/y/w/h>] [toolbar <toolbar>] [<path>]
  540.  
  541.      This command creates a new lister.  You may optionally specify the
  542.      position and size of the new lister.  The default position is -1/-1
  543.      causes the lister to open under the mouse pointer.  A custom toolbar
  544.      for the lister can be specified with the toolbar keyword; toolbar
  545.      
  546.                              Directory Opus 5                        217
  547.      
  548.      files are expected to be found in the DOpus5:Buttons directory if the
  549.      full path is not given.  You may also specify a path to read when the
  550.      lister opens.      For example,
  551.  
  552.                 > lister new
  553.                 > lister new 100/50/400/300
  554.                 > lister new ram:
  555.                 > lister new 80/30/200/200 dh0:work
  556.                 > lister new toolbar custom_toolbar work:
  557.                         --> 121132636
  558.  
  559.      If the lister opens successfully, its handle is returned in the
  560.      RESULT variable.  You must save the value of this handle if you wish
  561.      to do anything further with this lister.  In the above example, a
  562.      handle of 121132636 was returned.  This will be used for further
  563.      examples below.
  564.  
  565.   *     lister query <handle> <item>
  566.  
  567.      This command returns a particular item of information from the
  568.      specified lister.  <handle> is the handle of the lister in question.
  569.      All information is returned in the RESULT variable, unless an error
  570.      occurs.  <item> can be one of the following keywords:-
  571.  
  572. all
  573.  
  574.  This command returns the handles of all non-busy listers (that is, any
  575. listers that are not performing a function at the time).  Note that this
  576. does not require a lister handle to operate.  This also supports the use
  577. of stem variables. For example,
  578.  
  579.         > lister query all
  580.                 --> 121132636 121963868
  581.  
  582. abort
  583.  
  584.  This returns a boolean value indicating the status of the lister's abort
  585. flag.  This query command is only valid if the lister has a progress
  586. indicator open (as this is the only way the user can abort a function
  587.  
  588.      218                     Directory Opus 5
  589.  
  590. anyway).  This will return 1 if the user has clicked the abort gadget, 0
  591. if she has not.  For example,
  592.  
  593.         > lister query 121132636 abort
  594.                 --> 0
  595.   +-------------------------------------------------------------------+
  596.   | Note that in Opus 4, querying the abort flag would also reset it. |
  597.   | This is not the case in Opus 5; if you wish to reset the state of |
  598.   | the abort flag you must use the "lister clear" command.           |
  599.   +-------------------------------------------------------------------+
  600.  
  601. busy
  602.  
  603.  Returns a boolean value (0 or 1) indicating the lister busy status.  That
  604. is, if the lister is currently busy, it will return 1, otherwise it will
  605. return 0.  For example,
  606.  
  607.         > lister query 121132636 busy
  608.                 --> 1
  609.  
  610. dest
  611.  
  612.  This command returns the handles of all destination listers currently
  613. open.  Note that this does not require a lister handle to operate.  This
  614. also supports the use of stem variables.  For example,
  615.  
  616.         > lister query dest
  617.                 --> 121963868
  618.  
  619.  This command supports the stem and var keywords (see lister query entry
  620. for more information.)
  621.  
  622. dirs <separator>
  623.  
  624.  Returns the names of all directories in the lister.  For example,
  625.  
  626.         > lister query 121132636 dirs
  627.                 --> "Clipboards","ENV","T"
  628.  
  629.  This command supports the stem and var keywords (see lister query entry
  630. for more information.)
  631.  
  632.                              Directory Opus 5                        219
  633.  
  634. display
  635.  
  636.  This returns a string indicating the current display items.  The string
  637. will consist of the same keywords as for sort, in the order that they
  638. appear in the lister (if they appear at all).  For example,
  639.  
  640.         > lister query 121132636 display
  641.                 --> name size date protect comment
  642.  
  643. entries <separator>
  644.  
  645.  Returns the names of all entries (that is, both files and directories) in
  646. the lister.  For example,
  647.  
  648.         > lister query 121132636 entries
  649.                 --> "Clipboards" "ENV" "T" "abc" "Disk.info"
  650.  
  651.  This command supports the stem and var keywords (see lister query entry
  652. for more information.) For example,
  653.  
  654.         > lister query 121132636 entries stem files
  655.  
  656.  This would return the following variables :-
  657.  
  658.         files.count = 7
  659.         files.0 = Clipboards
  660.         files.1 = ENV
  661.         files.2 = T
  662.         files.3 = abc
  663.         etc.
  664.  
  665. entry <name>
  666.  
  667.  Returns information about the specified entry.  <name> is the actual name
  668. of the entry to return information about.  You can supply #xxx for the
  669. name (where xxx is a number), to specify the cardinal number of the
  670. desired entry.  This command can return information in two ways.  The
  671. default way is to return a string of information in either the RESULT
  672. variable or another variable of your choice.  The information returned in
  673. this case is
  674.  
  675.      220                     Directory Opus 5
  676.  
  677.         <name> <size> <type> <selection> <seconds> <protect> <comment>
  678.  
  679. where <name> is the full name of the entry, <size> is the size of the
  680. entry, <type> is the type of the entry (<0 means a file, >0 means a
  681. directory), <selection> indicates the selection status of the entry (1 if
  682. the entry is selected, 0 if it is not selected), <seconds> is the
  683. datestamp of the entry in seconds from 1/1/78, <protect> is the protection
  684. bits of the file (in ascii format); and <comment> is the comment of the
  685. entry (if any).  For example,
  686.  
  687.         > lister query 121132636 entry ENV
  688.                 --> ENV -1 2 0 543401724 ----   rwed
  689.  
  690.  By default the string is returned in the RESULT variable. If you wish to
  691. use another variable name, specify the var keyword followed by the
  692. variable name. For example,
  693.  
  694.         > lister query 121132636 entry ENV var my variable
  695.  
  696.  The second, and more elegant method, returns information about the entry
  697. in a stem variable.  To use this second method, you must specify the stem
  698. keyword followed by the name of the stem variable you wish to use.  For
  699. example,
  700.  
  701.         > lister query 121132636 entry ENV stem fileinfo
  702.  
  703.  The specified stem variable will have several fields, each containing
  704. information about the entry in question.  These fields are as follows:-
  705.  
  706.         name            - filename
  707.         size            - file size
  708.         type            - type (<0 = file, >0 = dir)
  709.         selected        - 0 or 1
  710.         date            - seconds since 1/1/78
  711.         protect         - protection bits (long value)
  712.         datestring      - datestamp in ascii form
  713.         protstring      - protection bits in ascii form
  714.         comment         - file comment (if any)
  715.         
  716.                              Directory Opus 5                        221
  717.         
  718.         filetype        - file type (if any)
  719.         version         - version number
  720.         revision        - revision number
  721.         verdate         - version date (numerical dd.mm.yy format)
  722.         datenum         - file date in numerical dd.mm.yy format
  723.         time            - file time in hh:mm:ss 24 hour format
  724.  
  725.  Several other query commands in this section support the var and stem
  726. keywords.
  727.  
  728.   +--------------------------------------------------------------------+
  729.   | Note regarding the lister query files, dirs, entries, selfiles,    |
  730.   | seldirs, and selentries commands.  In previous versions of Opus 5, |
  731.   | RESULT was not cleared if there were no entries to return.  This   |
  732.   | problem has been fixed.  Also when using these commands with the   |
  733.   | STEM keyword, the COUNT field will now be set to zero in this case.|
  734.   +--------------------------------------------------------------------+
  735.  
  736. files <separator>
  737.  
  738.  Returns the names of all files in the lister.  The names are returned as
  739. one long string, separated by spaces.  You may change the separation
  740. character by specifying it after the files keyword.  For example,
  741.  
  742.         > lister query 121132636 files
  743.                 --> "abc" "Disk.info" "readme" "zzz.zzz"
  744.  
  745.  This command supports the stem and var keywords (see lister query entry
  746. for more information.)
  747.  
  748. firstsel
  749.  
  750.  Returns the name of the first selected entry in the lister.  The entry is
  751. not deselected, so if you don't deselect it yourself this command will
  752. only ever return the one name.  For example,
  753.  
  754.         > lister query 121132636 firstsel
  755.                 --> "ENV"
  756.  
  757.      222                     Directory Opus 5
  758.  
  759. flags
  760.  
  761.  This returns a string indicating any sort or display flags that are
  762. active for the lister.  These flags are:-
  763.  
  764.         reverse - sort in reverse order
  765.         noicons - filter icons
  766.         hidden  - filter hidden bit
  767.  
  768.  For example,
  769.  
  770.         > lister query 121132636 flags
  771.                 --> noicons
  772.  
  773. hide
  774.  
  775.  This returns the current hide filter for this lister.  For example,
  776.  
  777.         > lister query 121132636 hide
  778.                 --> #?.o
  779.  
  780. handler
  781.  
  782.  Returns the name of the current custom handler port.  For example,
  783.  
  784.         > lister query 121132636 handler
  785.                 --> ArcDir121132636
  786.  
  787. label
  788.  
  789.  This command returns the label that appears beneath this lister when it
  790. is iconified.  By default, the label will be the name of the current
  791. directory.  This label can however be changed by calling the lister set
  792. label command.  For example,
  793.  
  794.         > lister query 121132636 label
  795.                 --> Ram Disk
  796.  
  797.                              Directory Opus 5                        223
  798.  
  799. lock <type>
  800.  
  801.  This command returns to current lock status of the lister where <type> is
  802. either state or format.  See the lister set lock command.
  803.  
  804. mode
  805.  
  806.  This returns the current mode for this lister and also the word showall
  807. if the lister is in an icon mode and displaying files without icons.  The
  808. lister modes are:-
  809.  
  810.         name            - name mode
  811.         icon            - workbench style icon mode
  812.         icon action     - icon action mode
  813.  
  814.  For example,
  815.  
  816.         > lister query 121132636 mode
  817.                 --> icon action showall
  818.  
  819. numdirs
  820.  
  821.  Returns the number of directories in the lister.  For example,
  822.  
  823.         > lister query 121132636 numdirs
  824.                 --> 3
  825.  
  826. numentries
  827.  
  828.  Returns the total number of entries in the lister (files + dirs).  For
  829. example,
  830.  
  831.         > lister query 121132636 numentries
  832.                 --> 7
  833.  
  834. numfiles
  835.  
  836.  Returns the number of files in the lister.  For example,
  837.  
  838.         > lister query 121132636 numfiles
  839.                 --> 4
  840.  
  841.      224                     Directory Opus 5
  842.  
  843. numselentries
  844.  
  845.  Returns the number of selected entries in the lister.
  846.  
  847. numseldirs
  848.  
  849.  Returns the number of selected directories in the lister.
  850.  
  851. numselfiles
  852.  
  853.  Returns the number of selected files in the lister.
  854.  
  855. path
  856.  
  857.  Returns a string indicating the current path visible in the lister.  For
  858. example,
  859.  
  860.         > lister query 121132636 path
  861.                 --> ram:
  862.  
  863. position
  864.  
  865.  Returns the current position and size of the lister.  The word locked
  866. will also be returned if the lister is locked in position.  For example,
  867.  
  868.         > lister query 121132636 position
  869.                 --> 80/30/200/200 locked
  870.  
  871. selfiles <separator>
  872.  
  873.  Returns the names of all selected files in the lister.  This command
  874. supports the stem and var keywords (see lister query entry  for more
  875. information.)
  876.  
  877.                              Directory Opus 5                        225
  878.  
  879. seldirs <separator>
  880.  
  881.  Returns the names of all selected directories in the lister.  This
  882. command supports the stem and var keywords (see lister query entry  for
  883. more information.)
  884.  
  885.  
  886. selentries <separator>
  887.  
  888.  Returns the names of all selected entries (ie both files and directories)
  889. in the lister.  This command supports the stem and var keywords (see
  890. lister query entry  for more information.)
  891.  
  892. separate
  893.  
  894.  This returns a keyword indicating the current file separation method in
  895. this lister.  Valid methods are:-
  896.  
  897.         mix             - mix files and directories
  898.         dirsfirst       - directories first
  899.         filesfirst      - files first
  900.  
  901.  For example,
  902.  
  903.         > lister query 121132636 separate
  904.                 --> dirsfirst
  905.  
  906. show
  907.  
  908.  This returns the current show filter for this lister.
  909.  
  910. source
  911.  
  912.  This command returns the handles of all source listers currently open.
  913. Note that this does not require a lister handle to operate.  For example,
  914.  
  915.         > lister query source
  916.                 --> 121132636 128765412
  917.  
  918.  This command supports the stem and var keywords (see lister query entry
  919. for more information.) For example,
  920.  
  921.         > lister query source stem sources.
  922.  
  923.  This would return:-
  924.  
  925.         sources.count   = 2
  926.         
  927.      226                     Directory Opus 5
  928.         
  929.         sources.0 = 121132636
  930.         sources.1 = 128765412
  931.  
  932. sort
  933.  
  934.  This returns a keyword indicating the current sort method in this lister.
  935. Valid sort methods are:-
  936.  
  937.         name      - filename
  938.         size      - file size
  939.         protect   - protection bits
  940.         date      - datestamp
  941.         comment   - comment
  942.         filetype  - file type
  943.         version   - file version
  944.  
  945.  For example,
  946.  
  947.         > lister query 121132636 sort
  948.                 --> name
  949.  
  950. toolbar
  951.  
  952.  This returns the toolbar currently being used by this lister.
  953.  
  954.  For example,
  955.  
  956.         > lister query 121132636 toolbar
  957.                         --> DOpus5:Buttons/toolbar
  958.  
  959. visible
  960.  
  961.  Returns a boolean value indicating if the lister is currently visible.
  962. For example,
  963.  
  964.         > lister query 121132636 visible
  965.                 --> 1
  966.  
  967.   *     lister read <handle> <path> [force]
  968.  
  969.      This command will read the given path into the specified lister.
  970.      By default a new cache is used to read the directory; if the force
  971.      keyword is specified, the current cache will be cleared and the
  972.      
  973.                              Directory Opus 5                        227
  974.      
  975.      directory will be read into that.  The old path is returned in
  976.      RESULT.  For example,
  977.  
  978.                 > lister read 121132636 'dh0:test'
  979.                         --> RamDisk:
  980.  
  981.   *     lister refresh (all  | <handle>) [full] [date]
  982.  
  983.      This command refreshes the display of the specified lister or all
  984.      listers if the keyword all is given in place of a lister handle.
  985.      Unlike Opus 4, none of the lister modifying commands above will
  986.      actually refresh or update the lister display; hence, you must use
  987.      this command after making any changes (changing sort method, adding
  988.      files, etc) to have the changes display.  The optional full keyword
  989.      causes the lister title and status displayed to be refreshed as well.
  990.      For example,
  991.  
  992.                 > lister refresh 121132636 full
  993.  
  994.      If the date keyword is specified, the lister will update its
  995.      directory datestamp, which will stop it re-reading itself the next
  996.      time it is activated. If this keyword is specified, the lister
  997.      display itself is not refreshed.
  998.  
  999.                 >lister refresh 12113236 date
  1000.  
  1001.   *     lister remove <handle> <name>
  1002.  
  1003.      This command removes an entry from the specified lister.  <name> is
  1004.      either the name of the entry, or #xxx (where xxx is a number) to
  1005.      specify the cardinal number of the entry.  The display is not updated
  1006.      until you execute a lister refresh command.  For example,
  1007.  
  1008.                 > lister remove 121132636 #5
  1009.  
  1010.   *     lister request <handle> <text> <buttons>
  1011.  
  1012.      This command is identical to the dopus request command except that it
  1013.      takes an additional handle parameter and the requester will be
  1014.      centred over that lister.
  1015.      
  1016.      228                     Directory Opus 5
  1017.      
  1018.      <text> is a string of text to be displayed in the requester.
  1019.      <buttons> are the buttons you wish the requester to have; each button
  1020.      should be separated by a vertical bar character.  For example,
  1021.  
  1022.                 > lister request 121132636 '"Please choose an option" "
  1023.                         Option 1|Option 2|Option 3"'
  1024.  
  1025.      This would display a requester with the string "Please choose an
  1026.      option", and three buttons labelled Option 1 to Option 3.
  1027.  
  1028.      The cardinal number of the selected button is returned in RC.  The
  1029.      last button supplied (Option 3 in this case) is designated a Cancel
  1030.      button, and so returns the value 0.  Therefore, the values returned
  1031.      by this example are 1, 2 and 0 respectively.
  1032.  
  1033.   *  lister set <handle> <item> <value>
  1034.  
  1035.      This command sets a particular item of information in the specified
  1036.      lister.  <handle> is the handle of the lister in question.  <item>
  1037.      can be one of the following keywords:-
  1038.  
  1039. busy <state> [wait]
  1040.  
  1041.  Sets the busy status for this lister.  You can specify 0 or off  to turn
  1042. the busy pointer off, or 1 or on to turn it on.  When turning busy status
  1043. on you can also provide the wait keyword which will cause the command to
  1044. be synchronous.  For example,
  1045.  
  1046.         > lister set 121132636 busy on wait
  1047.         > lister set 121132636 busy 0
  1048.  
  1049. case
  1050.  
  1051.  This command turns on or off case sensitivity for this lister.  Since
  1052. Amiga filenames are not case sensitive this setting defaults to off.  It
  1053. may be useful for some custom handlers to turn case sensitivity on
  1054. however.
  1055.  
  1056.         > lister set 121132636 case on
  1057.         > lister set 121132636 case off
  1058.         
  1059.                              Directory Opus 5                        229
  1060.         
  1061. dest [lock]
  1062.  
  1063.  Makes this lister the destination.  If you specify the lock keyword, it
  1064. will be locked as a destination.  For example,
  1065.  
  1066.         > lister set 121132636 dest
  1067.  
  1068. display <items>
  1069.  
  1070.  Sets the display items for this lister.  The display will not be updated
  1071. until you execute a lister refresh command.  See the lister query section
  1072. for the item keywords to use.
  1073.  
  1074.  For example,
  1075.  
  1076.         > lister set 121132636 display name date size protect
  1077.  
  1078. field [<number> <string>]
  1079.  
  1080.  This allows you to set your own strings to be used in the lister field
  1081. titles. You can not change the nature of the columns in the lister - this
  1082. just allows you to change the heading.
  1083.  
  1084.  The <number> (0-9) specifies which string to replace; counting from 0
  1085. they are:-
  1086.  
  1087. name, size, access, date, comment, type,
  1088. owner, group, net, version
  1089.  
  1090.  Set to an empty string to restore the default. You will need to do a
  1091. lister refresh <handle> full to update the display once you have changed
  1092. the titles.
  1093.  
  1094.  You can also do lister set <handle> field off to turn field titles off
  1095. altogether, and on to turn them back on again. Note that if field titles
  1096. have not been enabled in the configuration, an ARexx script is unable to
  1097. turn them on.
  1098.  
  1099.  For example,
  1100.  
  1101.         > lister set 121132636 field 0 FileName 4 Notes
  1102.  
  1103.      230                     Directory Opus 5
  1104.  
  1105. flags <flags>
  1106.  
  1107.  Sets sort/display flags for this lister.  The display is not updated
  1108. unless you execute a lister refresh command.  See the lister query section
  1109. for the keywords to use.   For example,
  1110.  
  1111.         > lister set 121132636 flags reverse noicons
  1112.  
  1113. header <string>
  1114.  
  1115.  This works just like lister set title except it changes the text in the
  1116. 'Files x/y Dirs x/y' bar. The old header string is returned in RESULT. Set
  1117. this to an empty string to restore the default. If you wish to actually
  1118. display an empty header, set it to a - (hyphen character.)
  1119.  
  1120. handler <port name> [quotes] [fullpath]
  1121.  
  1122.  Sets the custom handler port name for this lister.  This is the name of
  1123. the message port to which messages from Opus will be sent. If you specify
  1124. the quotes flag, any filenames sent in messages to the port will be
  1125. enclosed in quotes (this is a good idea as it allows you to support
  1126. filenames containing spaces). If you specify the fullpath flag, messages
  1127. will always contain the full path name of a file, irrespective of whether
  1128. it came from an Opus lister or not.  (Usually, if the file comes from a
  1129. lister you will only get the filename itself, plus the lister handle with
  1130. which to find out the path).  For example,
  1131.  
  1132.         > lister set 121132636 handler 'lhadir_handler' quotes
  1133.  
  1134.  See Custom Handlers later in this chapter for more details.
  1135.  
  1136. hide <pattern>
  1137.  
  1138.  Sets the hide pattern for this lister.  The pattern is applied
  1139. immediately but the display is not updated until you execute a lister
  1140. refresh command.  For example,
  1141.  
  1142.         > lister set 121132636 hide '#?.info'
  1143.  
  1144.                              Directory Opus 5                        231
  1145.  
  1146. label
  1147.  
  1148.  This command can be used to set the label that will be displayed beneath
  1149. the iconified lister.  To remove a custom label, simply use this command
  1150. with no label specified.  For example,
  1151.  
  1152.         > lister set 121132636 label Custom Lister
  1153.         > lister set 121132636 label
  1154.  
  1155. lock <type>
  1156.  
  1157.  The type parameter may currently be:-
  1158.  
  1159. state [on|off]
  1160.  
  1161.  The state  parameter allows you to lock the lister to its current state
  1162. so the user will be unable to change it until you unlock it.
  1163.  
  1164. format [on |off]
  1165.  
  1166.  The format parameter allows you to lock the lister to its current display
  1167. format. Currently this just prevents the user bringing up the Format Edit
  1168. Requester.
  1169.  
  1170.  You can string these commands on the one line, for example,
  1171.  
  1172.         > lister set 121132636 lock state on format on
  1173.  
  1174. mode
  1175.  
  1176.  This command sets the mode for this lister.  See the lister query section
  1177. for the keywords to use.  For example,
  1178.  
  1179.         > lister set 121132636 mode name
  1180.         > lister set 121132636 mode icon action showall
  1181.  
  1182.      232                     Directory Opus 5
  1183.  
  1184. namelength
  1185.  
  1186.  This command sets the maximum length allowed for filenames in this
  1187. lister.  The minimum length is 30 characters which is also the default
  1188. length.  This command will only be useful for writers of custom handlers.
  1189. Note that the internal Opus commands, for the most part, do not currently
  1190. support filenames longer than 30 characters. For example,
  1191.  
  1192.         > lister set 121132636 namelength 256
  1193.  
  1194. newprogress [name] [file] [info] [bar] [abort]
  1195.  
  1196.  This turns the progress indicator on in the specified lister.  This is
  1197. similar to the old lister set progress command, but allows greater control
  1198. over the information displayed.
  1199.  
  1200.         name            - allocates space for filename display
  1201.         file            - allocates space for file progress display
  1202.         info            - allocates space for information line
  1203.         bar             - allocates space for progress bar
  1204.         abort           - adds abort gadget
  1205.  
  1206.  Progress windows that show both the bar graph and the file progress will
  1207. have the graph and file displays swapped around.  This means that instead
  1208. of the graph showing the percentage of files copies, and a 'xx%' display
  1209. showing the progress of that file, the graph shows the file progress and a
  1210. 'xxx of yyy' display gives overall information.
  1211.  
  1212.  > lister set 121132636 newprogress name file info bar abort
  1213.  
  1214. newprogress name <filename>
  1215.  
  1216.  If the progress bar was opened with the name parameter, this will set the
  1217. current filename.
  1218.  
  1219.         > lister set 121132636 newprogress name 'myfile.txt'
  1220.  
  1221.                              Directory Opus 5                        233
  1222.  
  1223. newprogress file <total> <count>
  1224.  
  1225.  If the progress indicator was opened with the file but not the bar
  1226. parameter, this will set the total number of files and the number of the
  1227. current file.  This is shown as 'xx%' in the top right of the requester.
  1228.  
  1229.  If the progress indicator was opened with both the file and bar
  1230. parameters, this will set the total number of bytes and the current byte
  1231. count.  This is shown in the bar graph part of the requester.
  1232.  
  1233.         > lister set 121132636 newprogress file 12 4
  1234.  
  1235. newprogress info <text>
  1236.  
  1237. <text> is a text string to be displayed between the filename and the bar
  1238. graph of the progress indicator.  For example,
  1239.  
  1240.  > lister set 121132636 newprogress info "From 'T' to 'Ram:'"
  1241.  
  1242. newprogress bar <total> <count>
  1243.  
  1244.  If the progress indicator was opened with the bar but not the file
  1245. parameter, this will set the total number of bytes and the current byte
  1246. count.  This is shown in the bar graph part of the requester.
  1247.  
  1248.  If the progress indicator was opened with both the file and bar
  1249. parameters, this will set the total number of files and the number of the
  1250. current file.  This is shown as 'xxx of yyy' in the top right of the
  1251. requester.
  1252.  
  1253.         > lister set 121132636 newprogress bar 1024 100
  1254.  
  1255. newprogress title <text>
  1256.  
  1257.  <text> is a text string to be displayed in the title bar of the progress
  1258. indicator.  For example,
  1259.  
  1260.         > lister set 121132636 newprogress title 'Copying...'
  1261.  
  1262.      234                     Directory Opus 5
  1263.  
  1264.   +------------------------------------------------------------------+
  1265.   | You can use the old 'lister set progress' commands on a          |
  1266.   | 'newprogress'  indicator, but obviously they can only change the |
  1267.   | filename and bar count.  Use 'lister clear progress' to remove   |
  1268.   | either the 'old' or 'new' progress indicators.                   |
  1269.   +------------------------------------------------------------------+
  1270.  
  1271. off
  1272.  
  1273.  Turns this lister off (ie neither source nor destination).  For example,
  1274.  
  1275.         > lister set 121132636 off
  1276.  
  1277. path <path string>
  1278.  
  1279.  Sets the current path string in the lister.  Note that this does NOT
  1280. cause the directory to be read, it merely changes the displayed string.
  1281. To read a new directory, use the lister read command.  For example,
  1282.  
  1283.         > lister set 121132636 path 'dh0:work'
  1284.  
  1285. position <x/y/w/h>
  1286.  
  1287.  This sets the current position and size of the lister if it has not been
  1288. locked.  If the lister is visible the window will be moved immediately.
  1289. For example,
  1290.  
  1291.         > lister set 121132636 position 20/20/400/300
  1292.  
  1293. progress <total> <text>
  1294.  
  1295.  Please note that the 'lister set progress' commands have now been
  1296. superseded by the 'lister set newprogress' commands.  Please use those
  1297. commands in any new scripts.
  1298.  
  1299.  This turns the progress indicator on in the specified lister.  <total>
  1300. specifies the total amount to be processed, and controls the bar graph
  1301. display.  <text> is a text string to be displayed in the title bar of the
  1302. progress indicator.  For example,
  1303.  
  1304.         > lister set 121132636 progress 38 'Archiving files...'
  1305.  
  1306.                              Directory Opus 5                        235
  1307.  
  1308. progress count <count>
  1309.  
  1310.  This updates the bar graph display in the progress indicator (which must
  1311. have already been turned on); <count> is the current progress count to be
  1312. indicated by the bar graph.  For example,
  1313.  
  1314.         > lister set 121132636 progress count 4
  1315.  
  1316. progress name <name>
  1317.  
  1318.  This updates the filename display in the progress indicator.  The
  1319. filename is displayed above the bar graph.  For example,
  1320.  
  1321.         > lister set 121132636 progress name 'myfile.txt'
  1322.  
  1323. separate <method>
  1324.  
  1325.  Sets the separation method for this lister.  The list is rearranged
  1326. immediately, but the display will not be updated until you execute a
  1327. lister refresh command.  See the lister query section for the separation
  1328. keywords recognised. For example,
  1329.  
  1330.         > lister set 121132636 separate mix
  1331.  
  1332. show <pattern>
  1333.  
  1334.  Sets the show pattern for this lister.  The pattern is applied
  1335. immediately but the display is not updated until you execute a lister
  1336. refresh command.  For example,
  1337.  
  1338.         > lister set 121132636 show '#?.c'
  1339.  
  1340. sort <method>
  1341.  
  1342.  Sets the sort method for this lister.  The list is resorted immediately,
  1343. but the display will not be updated until you execute a lister refresh
  1344. command.  See the lister query section for the sort method keywords
  1345. available.  For example,
  1346.  
  1347.      236                     Directory Opus 5
  1348.  
  1349.         > lister set 121132636 sort date
  1350.         > lister set 121132636 sort filetype
  1351.  
  1352. source [lock]
  1353.  
  1354.  Makes this lister the source.  If you specify the lock keyword, it will
  1355. be locked as a source.  For example,
  1356.  
  1357.         > lister set 121132636 source lock
  1358.  
  1359. title <string>
  1360.  
  1361.  Sets the title for this lister (the title displayed in the lister title
  1362. bar).  The title bar display will not be updated until you execute a
  1363. lister refresh full command.  The old title is returned in RESULT.  For
  1364. example,
  1365.  
  1366.         > lister set 121132636 title 'hello'
  1367.                 --> RESULT
  1368.         > lister set 121132636 title
  1369.                 --> hello
  1370.  
  1371. toolbar
  1372.  
  1373.  This command changes the toolbar that is used in this lister.  For
  1374. example,
  1375.  
  1376.         > lister set 121132636 toolbar Ram:custom_toolbar
  1377.  
  1378. visible <state>
  1379.  
  1380.  Sets the visible status for this lister.  By default, listers are visible
  1381. when they are created.  If you set this state to 0 or off, the lister will
  1382. disappear from the display, until you make it visible again.  For example,
  1383.  
  1384.         > lister set 121132636 visible off
  1385.         > lister set 121132636 visible 1
  1386.  
  1387.                              Directory Opus 5                        237
  1388.  
  1389.   *     lister select <handle> <name> <state>
  1390.  
  1391.      This command changes the selection status of an entry in the
  1392.      specified lister.  <name> is either the name of the entry, or #xxx
  1393.      (where xxx is a number) to specify the cardinal number of the entry.
  1394.      <state> is the desired selection status (0 or off' for off, 1 or on
  1395.      for on).  If <state> is not given then the state of the entry is
  1396.      toggled.  The display is not refreshed until you execute a lister
  1397.      refresh command.  The previous selection state of the entry is
  1398.      returned in RESULT.  For example,
  1399.  
  1400.                 > lister select 121132636 ENV on
  1401.                         --> off
  1402.  
  1403.   *     lister wait <handle> [quick]
  1404.  
  1405.      This command causes the rexx script to wait for the specified lister
  1406.      to finish whatever it is doing.  Because Opus 5 multitasks, all rexx
  1407.      commands (like lister read, or lister new) will return immediately,
  1408.      even if the lister has not completed its task.  This command will
  1409.      force the script to wait until the lister goes non-busy.  If the
  1410.      lister is not in a busy state when this command is called, the
  1411.      program will wait for up to two seconds for it to go busy, otherwise
  1412.      this call is aborted.  If the quick keyword is specified, the command
  1413.      will return immediately if the lister is not busy, instead of waiting
  1414.      for  two seconds.  It would be silly to do lister set busy 1 and then
  1415.      lister wait.  For example,
  1416.  
  1417.                 > lister read 121132636 'c:'
  1418.                 > lister wait 121132636
  1419.  
  1420.   *     lister iconify (all | <handle>) <state>
  1421.  
  1422.         This command causes either all listers or the specified lister to
  1423.         become iconified if state is 1, on, or omitted altogether, and to
  1424.         deiconify if state is 0 or off.
  1425.  
  1426.                 > lister iconify 121132636
  1427.                 > lister iconify all off
  1428.  
  1429.     command
  1430.  
  1431.  The third base command is command.  This allows you to call the internal
  1432. commands of Directory Opus 5 from an ARexx script.  The commands execute
  1433. exactly as if they had been run from a custom button or menu.
  1434.  
  1435. command [wait] [source <handle>] [dest <handle>]
  1436.                 [original]      command [arguments]
  1437.  
  1438.  If the wait flag is specified, the command will be run synchronously,
  1439. otherwise it will return immediately. Ordinarily, commands operate on the
  1440. current source and destination listers - the source and dest parameters
  1441. allow you to specify alternative listers to use.
  1442.  
  1443.  The original flag allows you to run an original Opus internal function if
  1444. the command has been replaced in the command list by an external module
  1445. (external modules which add commands to Opus override the internal list).
  1446. This means you could have a module that replaced some Opus commands, did
  1447. something special in some circumstances, and in others just called the
  1448. original Opus function.
  1449.  
  1450.  The command parameter is the name of the command, and arguments are any
  1451. optional arguments for the command, as normal. Some examples are:
  1452.  
  1453.         > command all
  1454.         > command wait copy
  1455.         > command read s:startup-sequence
  1456.         > command source 121132636 makedir name=MyDir noicon
  1457.         > command original wait delete ram:#?
  1458.  
  1459.                             ARexx Error Codes
  1460.  
  1461.  Lister handles are the actual address in memory of the lister structure.
  1462. Opus 5 will reject any non-valid handles with an RC of 10.  All commands
  1463. that return data return it in RESULT (with the exception of dopus
  1464. getstring and lister getstring) or a specified stem variable; if an error
  1465.  
  1466.                              Directory Opus 5                        239
  1467.  
  1468. occurs, the error code is returned in RC.  An RC of 0 generally indicates
  1469. that everything is ok.  Error codes are:-
  1470.  
  1471. 1       RXERR_FILE_REJECTED
  1472.  
  1473. The file you tried to add was rejected by the current lister filters.
  1474.  
  1475.   +--------------------------------------------------------------------+
  1476.   | Note that this is not an error, just a warning.  The file is still |
  1477.   | added, it will just not be visible until the filters are changed.  |
  1478.   +--------------------------------------------------------------------+
  1479.  
  1480. 5       RXERR_INVALID_QUERY
  1481.         RXERR_INVALID_SET
  1482.  
  1483.         The query/set item you specified was invalid.
  1484.  
  1485. 6       RXERR_INVALID_NAME
  1486.         RXERR_INVALID_KEYWORD
  1487.  
  1488.         The filename, or keyword you specified was invalid.
  1489.  
  1490. 8       RXERR_INVALID_TRAP
  1491.  
  1492.         The trap you tried to remove didn't exist.
  1493.  
  1494. 10      RXERR_INVALID_HANDLE
  1495.  
  1496.         The lister handle you gave was invalid.
  1497.  
  1498. 12      RXERR_NO_TOOLBAR
  1499.  
  1500.         The lister has no valid toolbar.
  1501.  
  1502. 15      RXERR_NO_MEMORY
  1503.  
  1504.         There wasn't enough memory to do what you wanted.
  1505.  
  1506. 20      RXERR_NO_LISTER
  1507.  
  1508.         A lister failed to open (usually because of low-memory).
  1509.  
  1510.      240                     Directory Opus 5
  1511.  
  1512.                              Custom Handlers
  1513.  
  1514.  The custom handler system allows you to specify the name of an external
  1515. public message port.  This port will be sent messages whenever certain
  1516. things happen that you are interested in. Messages that are sent are
  1517. properly formatted ARexx messages. An example code fragment to receive a
  1518. message is:
  1519.  
  1520.         call waitpkt(myportname)  /* wait for messages to arrive */
  1521.         packet=getpkt(myportname) /* get waiting message */
  1522.         arg0=getarg(packet,0)     /* get Argument 0 */
  1523.         arg1=getarg(packet,1)     /* get Argument 1 */
  1524.         arg2=getarg(packet,2)     /* get Argument 2, etc... */
  1525.  
  1526.         call reply(packet,0)      /* reply to the message */
  1527.  
  1528.                        Custom Handlers for Listers
  1529.  
  1530.  A custom handler is "attached" to a lister by calling lister set <handle>
  1531. handler for that lister, giving the name of your message port. Whenever
  1532. something interesting happens to your lister, the handler will be sent an
  1533. ARexx message.  The handler can be implemented either as a rexx program or
  1534. as a C program (in which case it must interpret the rexx message itself).
  1535. Unlike Opus 4, messages sent to handlers do not cause Directory Opus 5 to
  1536. "hang" until they are replied (although you should try to reply to any
  1537. messages as soon as possible).
  1538.  
  1539.   +---------------------------------------------------------------------+
  1540.   | Note that custom handlers for listers are specific only to the      |
  1541.   | cache that is visible in the lister at the time the handler name is |
  1542.   | set. The same handler port may be used set for multiple caches, and |
  1543.   | indeed for multiple listers.  Note also that message port names are |
  1544.   | case-sensitive.                                                     |
  1545.   +---------------------------------------------------------------------+
  1546.  
  1547.  The rexx message identifies the type of event, the lister the event
  1548. happened to, and other pertinent data.  The events that you will be
  1549. notified of are :-
  1550.  
  1551.                              Directory Opus 5                        241
  1552.  
  1553. doubleclick
  1554.  
  1555.  This is a double-click event, and indicates that an item in the lister
  1556. has been double-clicked on by the user.  The message arguments are:-
  1557.  
  1558.            Arg0 - "doubleclick"    (a string indicating the event type)
  1559.            Arg1 - <handle>         (lister handle)
  1560.            Arg2 - <name>           (entry name)
  1561.            Arg3 - undefined
  1562.            Arg4 - undefined
  1563.            Arg5 - <userdata>       (if userdata was specified with the
  1564.                                    lister addstem command)
  1565.            Arg6 - <qualifiers>     (string indicating qualifiers pressed
  1566.                 - shift, alt, and control keys)
  1567.  
  1568. drop
  1569.  
  1570.  This is a drag'n'drop event, and indicates that one or more entries have
  1571. been dropped into a lister.  The message arguments are:-
  1572.  
  1573.                 Arg0 - "drop"         (event type)
  1574.                 Arg1 - <handle>       (destination lister handle)
  1575.                 Arg2 - <names>        (filenames)
  1576.                 Arg3 - <handle>       (source lister handle)
  1577.                 Arg4 - undefined
  1578.                 Arg5 - undefined
  1579.                 Arg6 - <qualifiers>   (shift, alt, and control keys)
  1580.  
  1581.  The filenames are separated by spaces (if there is more than one), and
  1582. will be within quotes if the quotes keyword was specified for the lister
  1583. set handler command.  If the files originated from another Opus 5 lister,
  1584. Arg3 gives the handle of that lister.  If this is the case, and the
  1585. fullpath option was not specified in lister set handler, only the
  1586. filenames (and not their paths) are supplied in Arg2 (you can get the
  1587. source path using lister query).  If Arg3 is null then the drop most
  1588. likely originated from Workbench, and the names in Arg2 include the full
  1589. paths.
  1590.  
  1591.      242                     Directory Opus 5
  1592.  
  1593. dropfrom
  1594.  
  1595.  This is exactly the same as the drop event, except that it indicates a
  1596. drop from a lister rather than a drop to one.  The message arguments are:-
  1597.  
  1598.                 Arg0    - "dropfrom"    (event type)
  1599.                 Arg1    - <handle>      (source lister handle)
  1600.                 Arg2    - <names>       (filenames)
  1601.                 Arg3    - <handle>      (destination lister handle)
  1602.                 Arg4    - undefined
  1603.                 Arg5    - undefined
  1604.                 Arg6    - <qualifiers>  (shift, alt, and control keys)
  1605.  
  1606.  Note that appicons can also receive dropfrom events but they have
  1607. slightly different arguments.  They can be distinguished by the word
  1608. "icon" always present in Arg4.  See below for more information.
  1609.  
  1610. parent
  1611.  
  1612.  This event will be received when the Parent Directory  item is chosen
  1613. from the lister cache pop-up menu, or whenever the user clicks on the
  1614. border parent gadget or uses the parent hot key, "/".  The message
  1615. arguments are:-
  1616.  
  1617.                 Arg0 - "parent"         (event type)
  1618.                 Arg1 - <handle>         (source lister handle)
  1619.                 Arg2 - <path>           (path of lister)
  1620.                 Arg3 - undefined
  1621.                 Arg4 - undefined
  1622.                 Arg5 - undefined
  1623.                 Arg6 - <qualifiers>     (only shift key)
  1624.  
  1625. root
  1626.  
  1627.  A root event will be received when the Root Directory item is chosen from
  1628. the lister cache pop-up menu, or whenever  the user uses the root hot key,
  1629. ":".  The message arguments are:-
  1630.  
  1631.                 Arg0 - "root"            (event type)
  1632.                 Arg1 - <handle>          (source lister handle)
  1633.                 Arg2 - <path>            (path of lister)
  1634.  
  1635.                              Directory Opus 5                        243
  1636.  
  1637.                 Arg3 - undefined
  1638.                 Arg4 - undefined
  1639.                 Arg5 - undefined
  1640.                 Arg6 - <qualifiers>      (shift keys)
  1641.  
  1642. path
  1643.  
  1644.  When the user enters a new path in the path gadget of a lister you will
  1645. receive this message.  The arguments are:-
  1646.  
  1647.                 Arg0 - "path"           (event type)
  1648.                 Arg1 - <handle>         (lister handle)
  1649.                 Arg2 - <path>           (path of lister)
  1650.  
  1651. reread
  1652.  
  1653.  The reread event will be sent to your handler when the Re-read Directory
  1654. item is chosen from the lister cache pop-up menu.  Its arguments are:-
  1655.  
  1656.                 Arg0 - "reread"         (event type)
  1657.                 Arg1 - <handle>         (lister handle)
  1658.                 Arg2 - <path>           (new path for lister)
  1659.  
  1660. active
  1661.  
  1662.  This event indicates that a cache with a custom handler attached has just
  1663. become visible.  The message arguments are:-
  1664.  
  1665.                 Arg0 - "active"         (event type)
  1666.                 Arg1 - <handle>         (lister handle)
  1667.                 Arg2 - <title>          (cache title)
  1668.                 Arg3 - undefined
  1669.                 Arg4 - <path>           (path of the lister)
  1670.  
  1671.  Arg2 will contain the custom title of the cache that became active, if it
  1672. has been set with lister set title.  If no custom title has been defined,
  1673. the path string of the cache is returned instead (ie in this case Arg2
  1674. will be the same as Arg4).
  1675.  
  1676.      244                     Directory Opus 5
  1677.  
  1678. inactive
  1679.  
  1680.  This event indicates that the cache this custom handler is attached to is
  1681. no longer active (visible in the lister).  The message arguments are the
  1682. same as for active above, except for a different event type in Arg0.  This
  1683. message is caused by the cache in the lister being changed (either by the
  1684. user or under rexx control), or even by the lister being closed.  Note
  1685. that you may receive an active message for another cache with a custom
  1686. handler, or even for the same cache, immediately after receiving an
  1687. inactive message.
  1688.  
  1689.                             Trapped Functions
  1690.  
  1691.  Messages for trapped commands are sent to the lister much like the other
  1692. messages. The arguments are :
  1693.  
  1694.              Arg0 - <command>   (name of the command, or "abort")
  1695.              Arg1 - <handle>    (source lister handle, if any)
  1696.              Arg2 - <files>     (selected files, if any)
  1697.              Arg3 - <handle>    (destination lister handle, if any)
  1698.              Arg4 - <path>      (source path; useful if there's no lister
  1699.                                  associated with it)
  1700.              Arg5 - <args>      (user-supplied arguments to the function)
  1701.              Arg7 - <path>      (destination path; allows you to support
  1702.                                  the Select Destination requester)
  1703.                                  
  1704.                               AddStem Pop-Ups
  1705.  
  1706.  If you have added files to a lister with lister addstem and specified
  1707. your own pop-up menus for the files, you will receive messages when these
  1708. menus are chosen by the user. The arguments sent are:
  1709.  
  1710.              Arg0 - "menu"       (string identifies this as a menu event)
  1711.              Arg1 - <handle>     (lister handle)
  1712.              Arg2 - <name>       (entry name)
  1713.              Arg3 - <id>         (ID of the menu item + base ID if
  1714.                                   specified)
  1715.              Arg4 - "file"       (string identifying this as a "file" menu
  1716.                                   event)
  1717.              Arg5 - <userdata>   (userdata specified via the lister
  1718.                                   addstem command)
  1719.                                   
  1720.                              Directory Opus 5                        245
  1721.  
  1722.                           Custom Handlers for AppIcons
  1723.  
  1724.  AppIcons added with the addappicon command will also cause messages to be
  1725. sent.  All AppIcon messages have the same arguments:-
  1726.  
  1727.              Arg0 - <event>     (string identifying the event)
  1728.              Arg1 - <id>        (ID specified in the addappicon command)
  1729.              Arg2 - <data>      (filenames/menu ID/other information)
  1730.              Arg3 - <handle>    (source lister handle - if applicable)
  1731.              Arg4 - "icon"      (string identifying this as an "icon"
  1732.                                  event)
  1733.  
  1734.  These are the events that apply to AppIcons:
  1735.  
  1736. doubleclick
  1737.  
  1738.  This event indicates that an icon has been double-clicked, or has had
  1739. Open selected from its menu.
  1740.  
  1741. dropfrom
  1742.  
  1743.  This is a drag'n'drop event, and indicates that one or more entries have
  1744. been dropped on this appicon from a lister or elsewhere. The names of the
  1745. entries are available in Arg2.
  1746.  
  1747. snapshot
  1748.  
  1749.  This event occurs when the Snapshot menu item is selected. The current
  1750. position of the icon is available in Arg2 (as an x,y string). You are
  1751. responsible for storing this position.
  1752.  
  1753. unsnapshot
  1754.  
  1755.  This event occurs when the Un-Snapshot menu item is selected.
  1756.  
  1757. removed
  1758.  
  1759.  This event warns that Opus has quit and the handler code should now clean
  1760. up and exit.
  1761.  
  1762.      246                     Directory Opus 5
  1763.  
  1764. info
  1765.  
  1766.  This event occurs when the Information menu item is selected.
  1767.  
  1768. close
  1769.  
  1770.  This will occur when Close is selected from the pop-up menu.
  1771.  
  1772. menu
  1773.  
  1774.  This event indicates that one of the user-supplied menu items has been
  1775. selected in the pop-up menu.  The number of the menu item will be returned
  1776. in Arg2.
  1777.  
  1778. menuhelp
  1779.  
  1780.  This event indicates that the help key was pressed while the mouse
  1781. pointer was over one of the user-supplied menu items.  The number of the
  1782. menu item will be returned in Arg2.
  1783.  
  1784.  
  1785.  Because of the multi-tasking nature of Opus 5, information custom
  1786. handlers receive can not be 100% relied on.  For example, you may receive
  1787. an active message, but the cache that caused it may have immediately gone
  1788. inactive again.  You should therefore check your port is clear of all
  1789. messages before processing any that have come in, and you should also use
  1790. the lister query  command to make sure that things are how you expect
  1791. them. Also note that listers (unless you have turned busy on) can be
  1792. closed by the user at any time.  An inactive message is sent when the
  1793. lister is closed. To check that a lister is still open, use the lister
  1794. query path command (or any other query command).  If the lister no longer
  1795. exists, RC will contain the error code  XERR_INVALID_HANDLE (10).  Be
  1796. aware though that while these possibilities exist, generally they will not
  1797. cause a problem.  For the most part it will only be if the user is
  1798. "playing around" that weird situations will occur.
  1799.  
  1800.                              Directory Opus 5                        247
  1801.  
  1802.                               ARexx Modules
  1803.  
  1804.  ARexx Modules are ARexx scripts which are installed in the DOpus5:Modules
  1805. directory.  They must have the suffix .dopus5 to work correctly.
  1806.  
  1807.  Each ARexx Module can add new internal commands to Opus.
  1808.  
  1809.  Once both Opus 5 and ARexx have been started on the computer, the
  1810. DOpus5:Modules directory will be scanned for ARexx Modules and each will
  1811. have its init function called.  Every ARexx Module must have an init
  1812. function or else it will not work.  This is the function that adds the
  1813. extra commands to Opus.
  1814.  
  1815.  The scripts are called with 4 or more parameters.  The first 4 are always
  1816. provided - the portname of Directory Opus 5 and the function name,
  1817. followed by the source and destination lister handles.  Any user-supplied
  1818. arguments to the function will follow.
  1819.  
  1820.  You can add as many commands as you like.  To add commands, use the dopus
  1821. command command.  The template is :
  1822.  
  1823.         dopus command <name> program <scriptname>
  1824.                 [desc <description>] [template <template>]
  1825.                 [source] [dest]
  1826.  
  1827.        command        - the name of the command
  1828.        scriptname     - filename of the script (this has to be the name of
  1829.                         the script as it appears in the DOpus5:Modules
  1830.                         directory, without the .dopus5 suffix)
  1831.        desc           - optional command description (for the pop-up
  1832.                         command list in editors)
  1833.        template       - optional ReadArgs style command template
  1834.                         (you'll have to do parsing yourself!)
  1835.        source         - indicates that the command needs a source
  1836.                         directory
  1837.        dest           - indicates that the command needs a destination
  1838.                         directory
  1839.  
  1840.  The program field is mandatory, and Opus will run the script name you
  1841. provide here whenever this function is invoked. The desc and template
  1842. fields are optional. If you specify the source or dest keywords (or both),
  1843.  
  1844.      248                     Directory Opus 5
  1845.  
  1846. you will be passed the appropriate lister handle(s) as an argument to the
  1847. script. If these flags are not set, the arguments will still be passed,
  1848. but will be zero. Any user-supplied arguments to the function will be at
  1849. the end of the command line; you are responsible for parsing these
  1850. yourself.
  1851.  
  1852.  Here is a complete example of an ARexx Module:-
  1853.  
  1854. /* Example Directory Opus 5 ARexx Module */
  1855.  
  1856. parse arg portname function source dest arguments
  1857. address value portname
  1858. options results
  1859.  
  1860. /* Initialise */
  1861.  
  1862. if function='init' then do
  1863.      dopus command "Test1" program "test-command" desc "'Test command 1'"
  1864.      template "TEST/S"
  1865.      dopus command "Test2" program "test-command" desc "'Test command 2'"
  1866.      source
  1867.         exit
  1868.         end
  1869.  
  1870. /* Test function 1 */
  1871.  
  1872. if function='Test1' then do
  1873.         dopus request "'Test command 1 received!'" "Ok"
  1874.         exit
  1875.         end
  1876.  
  1877.  
  1878. /* Test function 2 */
  1879.  
  1880. if function='Test2' then do
  1881.         str="'Test command 2 received - source handle " || source
  1882.         dopus request str "Ok"
  1883.         exit
  1884.         endThis page is left intentionaly blank.
  1885.  
  1886.                              Directory Opus 5                        249
  1887.                              
  1888.                    This page is left intentionaly blank
  1889.  
  1890.      250                     Directory Opus 5
  1891.  
  1892.  
  1893.