Retro1.org codex

XLIST                                            (MECAFF) CMS User Area command

XLIST is a MECAFF-based fullscreen file browser with the possibility to
switch to FSVIEW to browse or to EE for editing a file in the list.

XLIST is an extension to the FSLIST allowing to select files in the list and
to apply an arbitrary CMS command to each of the selected files, i.e. the
same command is applied to each of these files.
This help topic describes the XLIST-extensions to FSLIST. For the underlying
file lister functionality see the FSLIST help topic.

+----------+------------------------------------------------------------------+
| XLIST    | fn-pattern ft-pattern [fm-pattern]                               |
+----------+------------------------------------------------------------------+
| XXLIST   | fn-pattern ft-pattern [fm-pattern]                               |
| XXLIST   | fn-pattern.ft-pattern[.fm-pattern]                               |
+----------+------------------------------------------------------------------+

(see FSLIST for the file pattern definition)

The command XLIST is implemented as EXEC and can be used in all environments
supported by the MECAFF tools, but allows to specify the file pattern only in
the conventional CMS notation (file-id components separated by blanks).

The XXLIST command is implemented as REXX script and allows to specify the
file pattern both in the CMS or the dot-notation (see 2.1), but requires the
REXX interpreter available since VM/370R6 SixPack 1.2.

The basic functionality of FSLIST (commands, default PF-key assignments,
configuration) is extended by XLIST with file selection handling and applying
an arbitrary CMS command to the selected files.

Selected files are indentified in the list by displaying their line with the
CURRLINE attribute (see ATTR configuration command). With default settings,
the files in the list are displayed in green with selected files being
rendered in white resp. highlighted on monochrome displays.

Selecting and deselecting files can be done:
  - using the prefix zone: a blank deselects the file, any other character
    selects the file,
  - using PF11 (MARK command, assigned to PF11 by default) in the file area
    toggles the selection state of the file under the cursor,
  - using the commands SELECT or DESELECT to switch the selection of a group
    of files identified with a file pattern,
  - using the CLEAR commands to deselect all files.

Once the target files are selected, the command to be applied to these files
can be entered on the command prompt of XLIST. The name components of each
selected file can be passed with the following tokens to the CMS command:
   /   :  the complete file-id (fn ft fm)
   /n  :  the filename component (fn)
   /t  :  the filetype component (ft)
   /m  :  the filemode component (fm)

The process to execute the CMS command on the selected files is as follows:
  - XLIST (more precisely EE in XLIST mode) writes an intermediate EXEC to
    the first minidisk with write access, this EXEC basically invokes the
    CMS command for each file and contains enough information to restore the
    file list state on a later restart of XLIST; if requested, the returncodes
    for each CMS command invocation are collected in a result file;
  - XLIST terminates with a special returncode indicating to run the generated
    EXEC;
  - the wrapper script invokes the intermediate EXEC; after the execution of
    the last command, the ENTER key must be pressed to continue;
  - the wrapper script restarts EE in XLIST mode, specifying the intermediate
    file;
  - if the returncodes for the commands were requested, the result file is
    first shown in a fullscreen panel.
    This panel supports paging and scrolling through the PF-keys 06 to 10 as
    defined as default for FSLIST. This panel is left with PF03 or PF15.
  - XLIST will then restore the file list state (reload the list based on the
    last used file pattern and sort command and the last scrolling position)
    and the selection state of the files; restoring the file selection will
    of course show a different result if the command removed some or all files
    of the last list state.

The XLIST mode adds the following commands to the FSLIST command set:

+----------+------------------------------------------------------------------+
| Mark     |                                                                  |
+----------+------------------------------------------------------------------+

If the cursor is placed on a line in the file list: toggle the selection state
of the file under the cursor. This command is assigned to PF11 by default.


+----------+------------------------------------------------------------------+
| SElect   | file-pattern                                                     |
+----------+------------------------------------------------------------------+

Extend the selected file set by the items in the file list matching the given
file-pattern.


+----------+------------------------------------------------------------------+
| DESelect | file-pattern                                                     |
+----------+------------------------------------------------------------------+

Remove the items matching the given file-pattern from the selected file set.


+----------+------------------------------------------------------------------+
| CLear    |                                                                  |
+----------+------------------------------------------------------------------+

Deselect all files, i.e. empty selected file set.


+----------+------------------------------------------------------------------+
| !        | cms-command parameters                                           |
+----------+------------------------------------------------------------------+

Execute cms-command for each file selected, passing the parameters which can
(should) contain one of the tokens / /n /t or /m to specify the file to work
with. If none of these tokens is given, a / is automatically added to the
command as last parameter.
If the cms-command is an EXEC, then the command must be prefixed with EXEC.

For example to copy the selected files to disk Q, the following command can
be given to XLIST:

    ! copyfile / = = q ( replace olddate


+----------+------------------------------------------------------------------+
| *        | cms-command parameters                                           |
+----------+------------------------------------------------------------------+

Like the XLIST ! command, but additionally collect the returncodes of the
command invocations and display this list in a fullscreen panel after
executing the command.


+----------+------------------------------------------------------------------+
| #        | cms-command parameters                                           |
+----------+------------------------------------------------------------------+

Prepare the command to be invoked for each selected file, but do not execute
it. Instead, the command line will stay on the XLIST command prompt until it
is cleared or the # character is replaced by a ! (execute) or a * (execute
and collect returncodes) or ? (display intermediate EXEC).


+----------+------------------------------------------------------------------+
| ?        | cms-command parameters                                           |
+----------+------------------------------------------------------------------+

Display the intermediate EXEC that would be generated for the currently
selected files and the given command in a fullscreen panel. This panel
supports paging and scrolling through the PF-keys 06 to 10 as defined as
default for FSLIST. This panel is left with PF03 or PF15, after which the ?
character is replaced by a # and the command specified will stay on the
command prompt until cleared (see above).


+----------+------------------------------------------------------------------+
| Quit     |                                                                  |
| QQuit    |                                                                  |
+----------+------------------------------------------------------------------+

The FSLIST-command Quit (assigned to PF03 by default) works differently in
XLIST as it does not always leave the file list, depending on the dialog state:
  - If a CMS command has been entered for preparation on the command prompt
    (a # cms-command parameters  line has been redisplayed by XLIST on the
    command line), the command line is cleared.
  - If files are selected but no command is in preparation, the file selection
    is cleared.
  - If no files are selected and no CMS command is in preparation, XLIST list
    left.
The command QQuit (assigned to PF15 by default) leaves XLIST immediately,
independently of file selection or command preparation.


Usage Note:

The address represented by symbol or hexloc must be within your virtual machine
storage size.