FLIST

Authorization

General User

Purpose

Use the FLIST command to display a full-screen list of information about selected files residing on accessed minidisks and accessed shared file system (SFS) directories. Aliases, external objects, and subdirectories are also listed for directories. Once in FLIST, you can do normal CMS file operations such as EDIT, COPY, and ERASE on the listed files by entering the command in the input area immediately to the right of each file ID on the screen. You can also issue FLIST subcommands to sort the displayed data, or to enter a new FLIST level that displays a full-screen listing of another set of files.

Operands

fn

is the file name, the alias, the external object, or the subdirectory to be listed. The default is an asterisk (*). Specify only the first eight characters of subdirectory names. See Pattern Matching for information on using * and + to specify a subset of files.

ft

is the file type of the file(s) to be listed. The default is an asterisk (*). Subdirectories will not be listed if a file type other than * is specified.

fm

is the file mode of the file(s) to be listed. The default is A.

Options

Help fn

specifies the file name of an exec to be called on invocation of the Help function (/H is a FLIST command). If this option is not specified, the default exec name used is HFLIST.

Menu

is used with the USE option to prevent formatting of the screen to the right of the input areas. When MENU is specified, the text from input file columns 8–27 is placed in screen columns 1–20. The text from file columns 29–68 (for short date) or 29–71 (for full or ISO date) is moved intact to the right of the input areas.

Profile fn

specifies the name of an alternate file to be used as the FLIST profile. The file type must be $PROFILE. Anything entered after fn is ignored. If fn $PROFILE does not exist, or if this option is not specified, the default profile used is FLIST $PROFILE *.

Noclear

specifies not to clear the screen on entry to FLIST. The default is to clear the screen before display of FLIST.

Stack

specifies the following line is to be stacked (and not executed) if the input area is used:

*FLIST  nnnnn  filename  filetype  filemode  user_input

where:

*FLIST

will make it a comment if CMS reads it.

nnnnn

is the file entry number in the list.

filename

is the displayed file name.

filetype

is the displayed file type.

filemode

is the displayed file mode.

user_input

is anything the user typed in the input area.

If the input area used is for a subdirectory, the format of the stacked line will be:

*FLIST  nnnnn  +fm.ni fm user_input

where:

nnnnn

is the file entry number in the list.

+fm.ni

identifies the subdirectory named ni in the directory accessed as file mode fm.

fm

is the displayed subdirectory's access mode.

user_input

is anything the user typed in the input area.

For more information about the input area, see Using the Input Areas .

One recnum

causes the selected input line to be stacked (implies the STACK option) with any text entered in the input area, then the FLIST session ends. The display starts at the record number specified. If an incorrect value is found for recnum, the display starts with the first record. Any extraneous input following recnum will be ignored. Following are some occurrences when recnum is ignored, and the display starts with the first record:

• No number specified
• Negative numbers or zero are specified as recnum
• Number specified as recnum exceeds the total number of records
• Any erroneous value or text specified as recnum

PROTect

specifies input fields can be used only once.

SOrt fn

specifies an alternate exec file name to be called when an FLIST /SORT subcommand (/Sx) is issued and the USE option is also given. The default file name is FLISTS. A sample FLISTS EXEC is not shipped with FLIST. However, one is shown as a sample under Using a Sort Exec.

Use fn

specifies a display of the named file (which must be in CMS EXEC format) rather than FLIST's file listing. The file type must be EXEC and the file mode is assumed to be all (*). Parameters entered after fn are ignored.

The data from file columns 8–27 is placed in screen columns 1–20. The remainder of the data columns are placed in the appropriate columns of the display, to the right of the user input areas. This means the LISTFILE DATE or LABEL options should be used when the input file is created. For more information on using the LISTFILE command, see LISTFILE.

Pattern Matching

FLIST Subcommands

The following subcommands are available to help you once you enter FLIST. (In the syntax diagrams, uppercase letters indicate abbreviations. Only the uppercase letter(s) are needed; all subsequent characters are ignored.)

/BOTTOM Subcommand

The /BOTTOM subcommand displays the last page of the current FLIST level.

/CANCEL Subcommand

The /CANCEL subcommand cancels all active FLIST levels without processing any other commands entered after the /CANCEL command.

/DSPF Subcommand

The /DSPF subcommand displays the PF key settings for FLIST.

/ENTER Subcommand

The /ENTER subcommand enters another FLIST level.

The options are the same as the FLIST options except Profile and Noclear will be ignored if specified. When creating the second level, the screen will be split into two equal parts. To change the location of the split, move the cursor to the place you want the screen to be split and press the SPL PF key (usually PF5).

To display a previous level, use the /En form of the subcommand, where n is a digit in the range 0–9 and corresponds to the level desired. The level identifier (LVL n ) is in the upper left corner of the display.

/HELP Subcommand

The /HELP subcommand displays information on the use of the FLIST command.

/LEVEL Subommand

The /LEVEL subcommand enters another FLIST level.

The options are the same as the FLIST options except Profile and Noclear will be ignored if specified. When creating the second level, the screen will be split into two equal parts. To change the location of the split, move the cursor to the place you want the screen to be split and press the SPL PF key (usually PF5).

To display a previous level, use the /Ln form of the subcommand, where n is a digit in the range 0–9 and corresponds to the level desired. The level identifier (LVL n) is in the upper left corner of the display.

/OMIT Subcommand

The /OMIT subcommand (as the first token) prevents appending the file ID to the input text and may be used to issue CP or CMS commands. However, specific /n, /t, or /m symbols are substituted.

/QUIT Subcommand

The /QUIT subcommand leaves the current FLIST level after processing entered commands for the level.

/SORT Subcommand

/sn

specifies sorting by file name, file type, file mode.

/st

specifies sorting by file type, file name, file mode.

/sm

specifies sorting by file mode, file name, file type.

/sl

specifies sorting by record length, file name, file type, file mode. (Largest record length first.)

/sb

specifies sorting by number of blocks, file name, file type, file mode. (Largest number of blocks first.)

/sd

specifies sorting by date, time, file name, file type, file mode. (Most recent file first.)

The /SORT subcommand lets you sort the current FLIST level on the specified field(s). After sorting, the level is redisplayed from the top. If entries have been deleted, they are removed during the sort. (See also Using a Sort Exec.)

/TOP Subcommand

The /TOP subcommand displays the first (top) page for the current level.

/n Subcommand

The /n subcommand positions the indicated line on the top line of the current level.

= (EQUALS) Subcommand

The = subcommand repeats the last non-FLIST function for the current level. (FLIST functions, save for the /LEVEL, /ENTER, and /OMIT subcommands, cannot be repeated.) The repeat function does not cross level boundaries.

? (QUESTION MARK) Subcommand

The ? subcommand displays the last non-FLIST function for the current level. This allows you to see what command would execute if the = subcommand were entered. To re-execute the displayed command, you must overtype at least one character of the command.

Program Access Keys

FLIST PF Key Settings

Several PF keys are already set for use with FLIST. The settings and associated FLIST functions follow. Keywords marked with an asterisk are valid only when issued from a PF key.

Using the Input Areas

You may use the input areas after the file IDs to enter any command as if in the normal CMS environment, to execute CMS/CP functions, or to invoke an exec. You do not have to indicate the command is for CP or that it is an exec. However, to prevent any part of the file ID from being used in the command string, use the /OMIT (/O) subcommand as the first parameter.

Use a slash (/) if you want all or part of the file ID specified in the user input area. It may be used anywhere in the command sequence, as follows:

/

Insert the complete file ID.

/n

Insert the file name.

/t

Insert the file type.

/m

Insert the file mode.

/f

Insert the subdirectory name (+fm.ni).

Any combination of n, t, and m is valid up to a maximum of seven characters.

If not explicitly specified, FLIST will append the complete file ID to the user command area. For example, if erase alone is entered, FLIST will generate the command string erase filename filetype filemode and pass it to CMS for execution.

After executing a command, the CMS console input stack is processed. Input starting with a slash will replace the original command and will be processed as if it had been entered by the user. Input not starting with a slash will be passed to CMS without any change in the contents of the line. If the stack is empty, the next input field is processed.

When all input fields are processed, the screen is redisplayed and the input area is changed to indicate what happened. If the first character of the input area is displayed as:

Invalid FLIST functions will remain displayed. If any error condition arises, FLIST will sound the terminal's audible alarm.

APPLE    PIE      A0 erase     V         74         33          1  4/13/00 12:48
RECIPE   EXEC     A1 /tn       V        107         14          1  3/18/00 16:00
VANILLA  ICECREAM A1 copy / /nt b1                              
SWEET    ROLLS    A2 copy / = = b (rep                          
COOKIES           A  ac /f o   DIRECTORY                           9/11/99 13:07
INGREDIE ASSEMBLE A5 assemble /n                                
FUDGE    BROWNIES A2 /o msg Come and get it!                    
EMPTY    FILE     A1 xedit     V          1          0          0  4/11/99 12:58
DROP     TEST     A1 erase     Dropped or revoked alias         
EXTERNAL OBJECT   A1 erase     -          -          -          -  3/09/99  5:42

erase apple pie a0
exec recipe
copy vanilla icecream a1 vanilla icecream b1
copy sweet rolls a2 = = b (rep
ac +A.cookies o
assemble ingredie
msg Come and get it!
xedit empty file a1
erase drop test a1
erase external object a1

Using a FLIST Profile

FLIST looks for a profile (FLIST $PROFILE * by default) when it is first invoked. The profile may define PF key functions, the title for level 0, and the text at the bottom of the screen. FLIST will use default values for anything left undefined by the profile.

After processing the profile, FLIST checks the CMS console input stack and treats any stacked records the same way it treats profile records. This means you can use the stack to override the profile definitions.

FLIST only processes the profile once. It will ignore the PROFILE option if it is specified with the /ENTER or the /LEVEL subcommands.

**********************************************************************
**                                                                  **
**                         FLIST Profile                            **
**                                                                  **
**********************************************************************
*PFKEYS 01 (HLP) /H   Invoke HELP function
*PFKEYS 02 BRW  BROWSE the file on cursor line
*PFKEYS 03 END  Terminate this level after processing input
*PFKEYS 04 (XED) XEDIT
*PFKEYS 05 SPL  Split the screen (only in multiple levels)
*PFKEYS 06 /SB  Sort by block size (descending)
*PFKEYS 07 SCB  Scroll backward (to top of list)
*PFKEYS 08 SCF  Scroll forward (to end of list)
*PFKEYS 09 /SD  Sort by date (descending)
*PFKEYS 10 /ST  Sort alphabetically by file type
*PFKEYS 11 >I   Increase input area length
*PFKEYS 12 CAN  Cancel all levels, do not process input
*PFKEYS 13 (HLP) /H   Invoke HELP function
*PFKEYS 14 BRW  BROWSE the file on cursor line
*PFKEYS 15 END  Terminate this level after processing input
*PFKEYS 16 (XED) XEDIT
*PFKEYS 17 SPL  Split the screen (only in multiple levels)
*PFKEYS 18 /SB  Sort by block size (descending)
*PFKEYS 19 SCB  Scroll backward (to top of list)
*PFKEYS 20 SCF  Scroll forward (to end of list)
*PFKEYS 21 /SD  Sort by date (descending)
*PFKEYS 22 /ST  Sort alphabetically by file type
*PFKEYS 23 >I   Increase input area length
*PFKEYS 24 CAN  Cancel all levels, do not process input
PF:1 HLP 2 BRW 3 END 4 XED 5 SPL 6 /SB 7 SCB 8 SCF 9 /SD 10 /ST 11 >I 12 CAN

Using a Sort Exec

If the SORT and USE options are specified when the FLIST command is issued, users should invoke their own sort routines while within the FLIST environment. The exec specified on the SORT option will be given control when the user issues a sort subcommand (/Sn) from the FLIST screen. FLIST will pass four parameters to the user's sort exec. They are:

1. The file name
2. The file type
3. An asterisk (*) as the file mode of the file specified with the USE option of the FLIST command
4. The second character of the sort subcommand issued from the FLIST screen (for example, the n in /Sn)

When the exec completes, FLIST redisplays the file specified on the USE option of the FLIST command.

/* Sample SORT routine */
Trace Off
/*                                                           */
/* Routine to parse the input parameters, determine the type */
/* of SORT to be done, and perform the SORT of the file.     */
/* This routine assumes the file to be sorted is in CMS EXEC */
/* format. The sorted file retains the input fileid.         */
/*                                                           */
Parse upper arg fn ft fm type .
'SET CMSTYPE HT'
'TYPE' fn ft fm
A = POS(type,'XY')         /* X and Y are defined SORT types */
say A
say type
If A ¬= 0 then Do
   If A = 1 then Queue '8 15'  /* X - SORT file by filename  */
   Else Queue '17 24'          /* Y - SORT file by filetype  */
   'SORT' fn ft fm 'HOLD FILE A'
   'COPY HOLD FILE A' fn ft '= (REP'
   'ERASE HOLD FILE A'
End
Else rc = 111
Exit rc
/* End of EXEC */

The following steps show how you can try out the sample FLISTS EXEC.

1. Be sure you are running in the CMS environment with a R/W minidisk or directory accessed as A.
2. Create a CMS EXEC A file, which you will specify with the USE option of FLIST. (Be sure files exist on the minidisk or directory accessed as A.) Issue the following CMS command:

   listfile * * a (exec label

3. Make sure the sample FLISTS EXEC exists on an accessed minidisk or directory.

   Unless someone already created it, you will have to create the FLISTS EXEC.

4. Make sure you do not have a HOLD FILE A file.

   If the file exists, you should rename it before invoking the FLISTS EXEC, because the exec erases HOLD FILE A.

5. Issue the following command to invoke FLIST:

   flist (use cms sort flists m

6. From the FLIST screen, issue the sort subcommand /sx. This causes FLISTS EXEC to get control and to sort CMS EXEC by file name. When the sort exec finishes, FLIST redisplays the sorted CMS EXEC.
7. From the FLIST screen, issue the sort subcommand /sy. This causes FLISTS EXEC to get control and to sort CMS EXEC by file type. Again, when the sort exec finishes, FLIST redisplays the sorted CMS EXEC.
8. When you are ready to quit, press PF3 (End) to leave FLIST. If you renamed HOLD FILE A in step 4, you may want to change its file ID back to HOLD FILE A.

Usage Notes

1. Never reaccess a minidisk or directory displayed on one of the levels.
2. Do not erase files displayed on any level with an exec or with an erase * filetype filemode sequence.
3. Do not erase a file displayed on more than one level.

   The situations described above cannot be detected by FLIST and may result in randomly displayed file IDs or FLIST termination.

4. Executing commands which alter files other than the subject file may result in randomly displayed file IDs upon return to FLIST. Processing of these commands is not affected.
5. FLIST will not clear the user-supplied I/O interrupt table. Therefore, you can handle your own interrupts if you want to.
6. FLIST loads itself as a nucleus extension.
7. FLIST supports the following screen sizes: 24 x 80, 32 x 80, 43 x 80. Screen sizes other than these are forced to 24 x 80. For example, screen size 27 x 132 is forced to a 24 x 80 screen size.
8. FLIST uses the date format your virtual machine is using and displays the date in that format.
9. In addition to the FLIST command, you can also use the preferred FILELIST command to obtain similar results. See FILELIST for details.

Messages and Return Codes

• DMS002E File not found [RC=28]
• DMS048E Invalid filemode fm [RC=24]
• DMS069E Filemode mode not accessed [RC=36]
• DMS104S Error rc reading file from disk or directory [RC=2xxx]
• DMS109S Insufficient free storage available [RC=2|4xxx]
• DMS514E Return code nn from command [RC=1xxx]
• DMS618E NUCEXT failed [RC=5xxx]
• DMS1153E File pool filepoolid is unavailable or unknown [RC=99]
• DMS2189E DMSRLD failed with return code rc. [RC=6xxx]
• DMS2190E Invalid console type or console disconnected. [RC=1]

Additional system messages may be issued by this command. The reasons for these messages and their location are: