DIRLIST

Read syntax diagramSkip visual syntax diagram DIRList1 dirid (2(3Options)
Options
Read syntax diagramSkip visual syntax diagramALLACCessedDIRControlFILecontrolPROFilePROFDLSTPROFilefnNODirlistDIRlistfnNOMdiskMDIskNONickNICkOWNerREADOnlyREADWrite APPend4
Notes:
  • 1 Special commands that can be used in the DIRLIST environment are AUTHLIST, DISCARD, and EXECUTE.
  • 2 Default options are shown above the line in the options group.
  • 3 You can enter Options in any order between the parentheses.
  • 4 APPEND is only valid when issued from the DIRLIST environment.

Authorization

General User

Purpose

Use the DIRLIST command to display a list of Shared File System (SFS) directories for a specified directory structure and your linked minidisks.

The LISTDIR and DIRLIST commands display identical information, but in the DIRLIST environment, information is displayed under the control of the XEDIT. You can issue XEDIT subcommands to manipulate the list itself. You can also issue CMS commands against the directories directly from the displayed list.

Operands

dirid
specifies the SFS directory where the list begins. The list contains this directory and all directories below it in the directory structure. Only the directories for which you have some authority are listed. You can also use a file mode for the dirid if the directory is already accessed. If dirid is not specified, directories are listed beginning with your top directory. Also, if you use the NICK option, the user ID portion of the dirid can be a nickname that has been set up for a user or a group of users. For more information on how to specify dirid, see Naming Shared File System (SFS) Directories.

Options

ALL
lists all the directories in the specified directory structure for which you have some authority. Directories are listed regardless of their attributes. They are listed even if they are not accessed. The default is ALL.
ACCessed
lists only the accessed directories in the specified directory structure. If dirid is not specified with this option, all accessed directories in the CMS search order are listed.
DIRControl
lists only directories with the directory control attribute. Directories are listed even if they are not accessed.
FILecontrol
lists only directories with the file control attribute. Directories are listed even if they are not accessed.
PROFile fn
specifies the name of an XEDIT macro to be executed when XEDIT is invoked by the DIRLIST command. If not specified, the default macro PROFDLST XEDIT is invoked. For more information, see Usage Note 10.
DIRlist fn
specifies a file called fn DIRLIST already contains a list of directories produced by an earlier invocation of DIRLIST. This existing list of directories is displayed. If you have also specified dirid with this option, it is ignored. For more information, see Usage Note 5.
NODirlist
specifies no list of directories is to be used. The default is NODIRLIST.
MDIsk
lists the minidisks you have linked. When the MDISK option is used with the ACCESSED option, only the minidisks you have accessed will be listed along with the directories that are listed. When the MDISK option is used with FILECONTROL, DIRCONTROL, or ALL, all the minidisks you have linked will be listed along with all the FILECONTROL, DIRCONTROL or ALL directories that are listed.
NOMdisk
does not list any minidisks you have linked. The default is NOMDISK.
NICk
allows the user ID portion of the dirid, passed in on a DIRLIST call, to be a nickname that has been set up for a user or group of users.
NONick
does not allow nicknames to be used as the user ID portion of the dirid. The default is NONICK.
OWNer
Specifies that if a temporary access of a directory is necessary, it will be done based on your ownership of the directory. This is the default. If the entry is a minidisk, this option is ignored.
READOnly
Specifies that if a temporary access of a directory is necessary, it will be accessed in R/O status regardless of your ownership or authority to it. If already accessed, the temporary access is not necessary, so this option will be ignored. If the entry is a minidisk, this option is ignored.
READWrite
Specifies that if a temporary access of a directory is necessary, it will be accessed in R/W status regardless of your ownership or authority to it. If the R/W attempt fails a R/O access attempt will be made. If already accessed, the temporary access is not necessary; so this option will be ignored. If the entry is a minidisk, this option is ignored.
APPend
lists the directories at the end of the existing list. APPEND is only valid within the DIRLIST environment.

Usage Notes

  1. For more information on how to customize this command, see Customizing Profiles for CMS Productivity Aids.
  2. Format of the List
    When you invoke the DIRLIST command you are placed in the XEDIT environment editing a file named userid DIRLIST A0. Each line in this file contains:
    • A command area.
    • A file mode (a dash is displayed for file mode if the directory or minidisk is not accessed).
    • The directory name or the minidisk address. Up to 70 characters are displayed on a line; therefore if the directory name is too long for the line, you can scroll right to see the remainder of the name.

    The full power of XEDIT is available while commands are issued against the list. For example, you can scroll through the list of directories, locate a particular directory, and so forth.

    However, some XEDIT subcommands are inappropriate in this environment. Subcommands that alter the format or the contents of userid DIRLIST (for example, SET LRECL, SET TRUNC, SET FTYPE, or SET LINEND) may cause unpredictable results.

  3. Entering CMS Commands from DIRLIST

    Begin CMS commands entered from the command line with CMS to prevent XEDIT from decoding the command. This prevents CMS commands from being mistaken as XEDIT subcommands.

  4. Using Special Commands from DIRLIST: EXECUTE, DISCARD, and AUTHLIST

    The EXECUTE command allows you to issue commands that use the directories and minidisks displayed by DIRLIST. The DISCARD command allows you to erase the directories and minidisks displayed by DIRLIST. The AUTHLIST command displays authority information about the directories displayed by DIRLIST. For more information, see Special Commands Used Within Other Commands.

  5. Saving a List of Directories, Minidisks or Both

    To save a list of displayed directories, minidisks, or both, issue FILE or SAVE from the command line. The list is saved in a file named userid DIRLIST until the next time you issue FILE or SAVE on the list.

    To save a particular list of directories, minidisks, or both, file it under a different file name. You have two choices on how to do this, issue FILE from the command line:
    • Specifying a different filename. For example, you could issue FILE MYDIRS.
    • And then use the RENAME command.

    Saving a list of directories, minidisks, or both, is useful when you want certain directories and minidisks to be listed each time you issue DIRLIST. For example, to combine several users' directories together in one list, you can use the APPEND option from DIRLIST. After saving the list, you may now issue DIRLIST with the DIRLIST option to display all the directories and minidisks previously saved.

    Note: Your entire saved list will always be displayed when you specify the DIRLIST fn option, even if you have also specified the ACCESSED, FILECONTROL or DIRCONTROL options, and some or all the files in your saved DIRLIST do not meet these criteria. Also if your saved list was from a DIRLIST that used the MDISK option your entire saved list will be displayed even if the MDISK option is not used when you specify the DIRLIST fn option. A not found message will appear beside each file not meeting the criteria you have specified.
  6. Tailoring the DIRLIST Command Options

    The DEFAULTS command can be used to set up options and override command defaults for DIRLIST. The options you specify from the command line when issuing DIRLIST will override the defaults specified in the DEFAULTS command. This allows you to customize the defaults yet override them when desired. For example, when you have set DIRLIST as your default option using the DEFAULTS command, CMS searches for a file called userid DIRLIST to use for the list of directories. For more information, see DEFAULTS.

  7. Issuing Commands from the DIRLIST Screen

    You can issue commands directly from the line that displays a directory, by typing the command in the command (Cmd) column. If a command is longer than the command space provided on the screen, just continue typing over the information in the line. You may type over the entire line displayed up to column 79. When you are finished typing the command, erase the rest of the line by pressing Erase EOF, or space over the rest of the line. Press Enter to execute the command. You may use the DELETE key to erase the rest of the line, but do not use it to erase only part of the rest of the line. After the command executes, press the PF2 key to refresh your screen so an updated screen is displayed to type other commands. For more information, see EXECUTE.

    When you enter a command without any symbols, the directory name is automatically appended to the end of the command.

  8. Using Symbols as Part of a Command
    Use the following symbols if the command you want to execute has operands or options that follow the directory name on the line where the directory is displayed:
    /
    is equivalent to the directory name.
    /m
    means the file mode that is displayed on the line.
    /d
    means the directory name that is displayed on the line.
    /o
    means execute the line as is and omit appending anything.

    For more information, see FILELIST.

  9. Using Special Symbols
    These special symbols can be typed alone on the lines of the DIRLIST display:
    =
    means execute the previous command for this directory. Commands are executed starting with the top of the screen. For example, if you issue the ERASE command on the top line, you can type an equal sign on any other line(s). Those directories preceded by equal signs are erased when you press Enter.
    ?
    displays the last executed command on the line that the ? was entered.
    /
    means make this line the current line. The current line for DIRLIST is the first directory on the screen.
  10. Setting Defaults for Keys

    The PROFDLST XEDIT macro is executed when DIRLIST is issued unless you specify a different macro as an option.

    The keys are set to:

    Key Setting Action
    Enter Execute Executes the command(s) typed on the directory line(s) or on the command line.
    PF1 Help Displays a help screen that gives the DIRLIST command description.
    PF2 Refresh Updates the list to indicate new directories, renamed directories, and so forth, using the same operands and options as when DIRLIST was invoked.
    PF3 Quit Exits from DIRLIST.
    PF4 Sort(fm) Sorts the list alphabetically by file mode, use the SMODE XEDIT macro.
    PF5 Sort(dir) Sorts the list alphabetically by directory name, use the SDIR XEDIT macro to do this.
    PF6 Auth Issues an AUTHLIST command for the directory where the cursor is placed. The AUTHLIST information is placed in an XEDIT file named userid AUTHLIST A0. This is now a new full screen environment with the PF keys set to new values. The AUTHLIST screen indicates which authority you have on the designated directory and the authorities you gave to other users.
    Note: The PF 6 key is used with directories only, therefore, issuing it on a minidisk entry will cause an error. For more information, see AUTHLIST.
    PF7 Backward Scrolls backward one screen.
    PF8 Forward Scrolls forward one screen.
    PF9   Not assigned.
    PF10   Not assigned.
    PF11 Filelist Issues the command FILELIST * * for the directory or minidisk where the cursor is placed. Displays a list of files for the designated directory or minidisk whether it is accessed or not accessed. If the directory or minidisk is not accessed, a temporary access is done using the last available file mode in the search order. The file mode is automatically released when you exit this FILELIST screen.
    PF12 Cursor Moves the cursor from its location to the command line or back to its previous location.
    Note: If you have 24 PF keys, PF keys 13 - 24 are assigned the same values as PF keys 1 - 12.
    In addition to these PF key settings, the PROFDLST XEDIT macro sets the following synonyms that can be used to sort the listed directories:
    SMODE
    Sorts the list alphabetically by file mode. Directories are not accessed are listed last, sorted alphabetically by directory name. SMODE is an XEDIT macro.
    SDIR
    Sorts the list alphabetically by directory name.
  11. Using nicknames with DIRLIST

    If there is a user ID that is the same as a nickname, the nickname takes precedence when the NICK option is used. The nickname is used in the user ID portion of dirid.

    For example, you have a MYDEPT nickname which is a list of your department members. There is also a MYDEPT user ID. If you want to use the MYDEPT nickname to display a list of all your department member's GOODIES directories (and subdirectories) for which you are authorized, you would enter:
    DIRLIST MYDEPT.GOODIES (NICK
    If you want to use the MYDEPT user ID to display a list of user MYDEPT's GOODIES directories (and subdirectories) for which you are authorized, you would enter:
    DIRLIST MYDEPT.GOODIES (NONICK
    If you allow the NICK/NONICK option to default to NONICK, you could also display user MYDEPT's GOODIES directories (and subdirectories) for which you are authorized by entering:
    DIRLIST MYDEPT.GOODIES
  12. The DIRLIST option of the DIRLIST command uses an input DIRLIST file containing a list of directory names. These directory names may not include nicknames.
  13. Displaying your authorized directories through an XEDIT macro
    This is a sample of the XEDIT macro you can choose to duplicate for a convenient way of displaying all the directories in your default file pool you have read or write access to.
    /**********************************************************/
    /* GETDIRS XEDIT:                                         */
    /*                                                        */
    /* Issue this XEDIT macro from DIRLIST.  It will display  */
    /* all of the directories that you are authorized for on  */
    /* your current default file pool.                        */
    /**********************************************************/
     
    'TOP'
    'QUERY ENROLL USER FOR ALL (FIFO'
    If rc ¬= 0 Then Exit
    pull .
    i = queued()
    DO i
      Pull userid .
      Address Command 'LISTDIR' userid││'. (XEDIT'
    End
    'SDIR'
  14. If you want to issue DIRLIST from an exec program, you should precede it with the EXEC command; that is, specify
    exec dirlist

Examples

User SMITH enters,
dirlist
from the command line, and the following screen is displayed:
Figure 1. Sample DIRLIST Screen
 SMITH    DIRLIST  A0  V  319  Trunc=319 Size=8  Line=1 Col=1 Alt=0
 
Cmd   Fm Directory Name
      A  FPOOL1:SMITH.
      -  FPOOL1:SMITH.ADDRESSES
      -  FPOOL1:SMITH.ADDRESSES.EMPLOYEES
      -  FPOOL1:SMITH.ADDRESSES.MANAGERS
      B  FPOOL1:SMITH.ANNIVERSARIES
      -  FPOOL1:SMITH.ANNIVERSARIES.EMPLOYEES
      -  FPOOL1:SMITH.BIRTHDAYS
      -  FPOOL1:SMITH.BIRTHDAYS.EMPLOYEES
 
 
 
 
1= Help     2= Refresh 3= Quit    4= Sort(fm)    5= Sort(dir)  6= Auth
7= Backward 8= Forward 9=        10=            11= Filelist  12= Cursor
 
====>
                                                       X E D I T  1  File

For more information on each column, see Responses.

User SMITH enters,
dirlist (mdisk
from the command line, and the following screen is displayed:
Figure 2. Sample DIRLIST Screen with MDISK Option
 SMITH    DIRLIST  A0  V  319  Trunc=319 Size=8  Line=1 Col=1 Alt=0
 
Cmd   Fm Directory Name/Minidisk Address
      A  FPOOL1:SMITH.
      -  FPOOL1:SMITH.ADDRESSES
      -  FPOOL1:SMITH.ADDRESSES.EMPLOYEES
      -  FPOOL1:SMITH.ADDRESSES.MANAGERS
      B  FPOOL1:SMITH.ANNIVERSARIES
      -  FPOOL1:SMITH.ANNIVERSARIES.EMPLOYEES
      -  FPOOL1:SMITH.BIRTHDAYS
      -  FPOOL1:SMITH.BIRTHDAYS.EMPLOYEES
      C  191
      Y  19E
      S  200
      -  555
 
 
1= Help     2= Refresh 3= Quit    4= Sort(fm)    5= Sort(dir)  6= Auth
7= Backward 8= Forward 9=        10=            11= Filelist  12= Cursor
 
====>
                                                       X E D I T  1  File

For more information on each column, see Responses.

For more examples using the DIRLIST command, see z/VM®: CMS User's Guide.

Responses

Issuing the DIRLIST command with no operands or options displays the following information:
Cmd Fm  Directory Name
    fm  directory name
    .   .
    .   .
Where:
Cmd
specifies a command column for typing and entering commands for the directory displayed on the line. You may use special characters. For example, / and = to represent what is already displayed on the line.
Fm
specifies the file mode letter of the accessed directory
- Dash
specifies the directory is not accessed
Directory Name
specifies the complete directory name
When a command is executed on the line where a directory is listed, one of the following symbols is displayed in the Cmd column:
*
specifies the command was executed successfully (RC=0).
*n
specifies the number for the return code (RC=n).
*?
specifies the command was unknown to CP or CMS (RC=-3).
*!
specifies the command is not valid in CMS subset. For a list of commands valid in the CMS subset mode, see z/VM: CMS User's Guide.
Issuing the DIRLIST command with the MDISK option displays this information:
Cmd Fm  Directory Name/Minidisk Address
    fm  directory name
    fm  minidisk address
    .   .
    .   .
Where:
Cmd
specifies a command column for typing and entering commands for the directory or minidisk displayed on the line. You may use special characters. For example, / and = to represent what is already displayed on the line.
Fm
specifies the file mode letter of the accessed directory or minidisk. The - (dash) means the directory or minidisk is not accessed.
Directory Name or Directory Name/Minidisk Address
specifies the complete directory name or the minidisk address.

Messages and Return Codes

  • DMS002E File fn ft fm not found [RC=28]
  • DMS069E Filemode mode not accessed [RC=36]
  • DMS105S Error nn writing file to XEDIT [RC=100]
  • DMS109S Virtual storage capacity exceeded [RC=104]
  • DMS557E No more storage to insert lines [RC=4]
  • DMS651E APPEND│SMODE must be issued from DIRLIST [RC=40]
  • DMS651E X$NDIR$X must be issued from FILELIST or DIRLIST [RC=40]
  • DMS653E Error executing LISTDIR, rc=nn [RC=nn]
  • DMS1184E Directory dirname not found or you are not authorized for it [RC=28]
  • DMS1187E Too many subdirectory levels in dirname [RC=24]
  • DMS1188E Filemode mode is not associated with a directory [RC=74]
  • DMS1189E Filemode mode is associated with a top directory [RC=24]
  • DMS1223E There is no default file pool currently defined [RC=40]
  • DMS1210E Directory dirname not found [RC=28]
  • DMS1227E No filemode is available to access directory|minidisk [RC=0]
  • DMS1228E Error executing access for directory|minidisk, rc=nn [RC=0]
  • DMS1229E Directory is empty [RC=0]
  • DMS1234E Error executing FILELIST, rc=nn [RC=nn]
  • DMS1249I Directory has been temporarily accessed (read/only) as filemode fm [RC=0]
  • DMS3995W You are not authorized to access in read/write mode [RC=4]

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

Reason Location
Errors in command syntax Command Syntax Error Messages
Errors in the Shared File System File Pool Server Messages