DIRLIST
- 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
- For more information on how to customize this command, see Customizing Profiles for CMS Productivity Aids.
- 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. - 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. - 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.
- 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. Anot found
message will appear beside each file not meeting the criteria you have specified. - 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. - 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.
- 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.
- 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.
- 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.
- 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:
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 (NICK
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 (NONICK
DIRLIST MYDEPT.GOODIES
- 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.
- 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'
- If you want to issue DIRLIST from an exec program, you should precede it with the EXEC command;
that is, specify
exec dirlist
Examples
dirlist
from the command line, and the following screen
is displayed:
For more information on each column, see Responses.
dirlist (mdisk
from the command line, and the following
screen is displayed:
For more information on each column, see Responses.
For more examples using the DIRLIST command, see z/VM®: CMS User's Guide.
Responses
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
- *
- 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.
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 |