DIRLIST—directory list service

The DIRLIST service allows you to write your own z/OS® UNIX directory list dialog. This service is similar to ISPF option 3.17, the z/OS UNIX Directory List Utility, which displays the list of files in a z/OS UNIX directory. The DIRLIST service allows the caller to control the format of the data displayed in the list and to process line commands entered against entries in the list.

Command invocation format


>>-ISPEXEC--DIRLIST--PATH(path-var)--+--------------------+----->
                                     '-CONFIRM(-+-YES-+-)-'   
                                                '-NO--'       

>--+--------------------+--+-------------------+---------------->
   '-CONFDRD(-+-YES-+-)-'  '-PANEL(panel-name)-'   
              '-NO--'                              

>--+-------------------+--+--------------------+---------------->
   '-COLS(column-list)-'  '-FIXCOLS(-+-YES-+-)-'   
                                     '-NO--'       

>--+--------------------------+--+-----------------+-----------><
   '-LCMDS(line-command-list)-'  '-FROM(file-name)-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('DIRLISTb'--,--path-var--,-+-'b'--------+---->
                                              +-'YESbbbbb'-+   
                                              '-'NObbbbbb'-'   

>--,-+-'b'--------+--,-+-panel-name-+--,-+-column-list-+-------->
     +-'YESbbbbb'-+    '-'b'--------'    '-'b'---------'   
     '-'NObbbbbb'-'                                        

>--,-+-'b'--------+--,-+-line-command-list-+-;------------------>
     +-'YESbbbbb'-+    '-'b'---------------'     
     '-'NObbbbbb'-'                              

>--,-+-file-name-+-;-------------------------------------------><
     '-'b'-------'

Parameters

path-var

The name of an ISPF variable containing the pathname for a z/OS UNIX directory. The pathname can contain glob characters to perform searching of the z/OS UNIX file system.

CONFIRM(YES|NO)

Specifies whether the Confirm Delete panel appears when using the D (delete) line command from the displayed directory list to delete a file or empty directory. YES is the default.

If YES is specified, ISPF displays the Confirm Delete panel. This gives you the opportunity to change your mind and keep the file.

If NO is specified, ISPF does not display the Confirm Delete panel. The file is deleted without your having to take any additional actions.

CONFDRD(YES|NO)

Specifies whether the Confirm Non-empty Directory Delete panel appears when using the D (delete) line command from the displayed directory list to delete a directory containing files.

YES is the default. If YES is specified, ISPF displays the Confirm Non-empty Directory Delete panel. This gives you the opportunity to change your mind and keep the directory.

If NO is specified, ISPF does not display the Confirm Non-empty Directory Delete panel. The directory and all the contained files and sub-directories are deleted without your having to take any additional actions.

panel-name

The name of the panel to use for the display of the directory list. The default is the panel (ISRUUDL0) used for the directory list displayed using ISPF option 3.17, the z/OS UNIX Directory List Utility.

column-list

Specifies the columns of data displayed on the z/OS UNIX directory list. If the parameter is omitted, the directory list is displayed using the column arrangement defined by the user using the Directory List Column Arrangement choice from the z/OS UNIX Directory List Utility Options pull-down menu.

To request that the ISPF-defined default column arrangement is used for the directory list display, specify an asterisk: COLS(*).

Table 1 shows the ISPF-defined column arrangement:

Table 1. ISPF-defined column arrangement
Column	Width
Type	4
Permissions	10
Audit	6
Extended Attributes (Ext)	4
Format (Fmat)	4
Owner	8
Group	8
Links	6
Size	10
Modified Date/Time	19
Changed Date/Time	19
Accessed Date/Time	19
Created Date/Time	19

Alternatively, you can specify a paired list of columns and widths values. You specify the column values using the abbreviations shown in Table 2. The table also shows the maximum widths that can be specified for each column.

Table 2. Column abbreviations and widths
Column	Abbreviation	Maximum width
Type	TY	4
Permissions	PE¹	10
Permissions - Octal	PO¹	4
Audit	AU	6
Extended Attributes (Ext)	EX	4
Format (Fmat)	FM	4
Owner	OW	8
Group	GR	8
Links	LI	14
Size	SZ	20
Modified Date/Time	MD	19
Changed Date/Time	CH	19
Accessed Date/Time	AC	19
Created Date/Time	CR	19
Note: PE (Permissions) and PO (Permissions - Octal) are mutually exclusive.

If a column is not specified with the COLS parameter, then that column is not displayed with the directory list. For example, the COLS parameter shown here causes the display of a z/OS UNIX directory list (see Figure 1) showing only a Type column, Owner column, and a Changed Date/Time column 10 characters in width:

COLS(TY,4,OW,8,CH,10)

Figure 1. z/OS UNIX Directory List

                           z/OS UNIX Directory List          Row 1 to 11 of 11
Command ===>                                                  Scroll ===> CSR

Pathname . : /SYSTEM

Command  Filename        Message          Type Owner    Changed
-------------------------------------------------------------------------------
         .                                Dir  IBMUSER  2007/01/31
         ..                               Dir  IBMUSER  2007/05/02
         bin                              Syml IBMUSER  2007/01/31
         dev                              Dir  IBMUSER  2007/05/13
         etc                              Dir  IBMUSER  2007/06/12
         lib                              Syml IBMUSER  2007/01/31
         opt                              Syml IBMUSER  2007/01/31
         samples                          Syml IBMUSER  2007/01/31
         tmp                              Dir  IBMUSER  2007/07/16
         usr                              Syml IBMUSER  2007/01/31
         var                              Dir  IBMUSER  2007/06/12
******************************* Bottom of data ********************************

FIXCOLS(YES|NO)

Specifies whether you can change the column arrangement for the directory list display using the Directory List Column Arrangement choice from the z/OS UNIX Directory List Utility Options pull-down menu. This parameter is ignored if the column-list parameter is not specified on the call to DIRLIST.

If you specify YES, you cannot change the column arrangement specified by the column-list parameter.

If you specify NO, you can change the column arrangement specified by the column-list parameter using the Directory List Column Arrangement choice from the z/OS UNIX Directory List Utility Options pull-down menu.

line-command-list

This parameter allows the calling application to process line commands entered on the z/OS UNIX directory list display. The caller can specify a directory list command processor and a list of line commands to be processed by the line command processor, rather than the ISPF directory list utility.

The first entry in the line-command-list is the name of the line command processor. This can be the name of a REXX exec or a program. The line command processor is invoked using the SELECT CMD service when one of the line commands specified in the line-command-list is entered on the directory list display. The line commands are specified after the name of the line command processor. Line commands can be from 1 to 8 characters in length. These line commands can include line commands normally processed by ISPF, allowing the application to override the processing of a line command.

The example of the LCMDS parameter shown here causes line commands DP, LCMD1, and W to be processed by line command processor LCMDPROC. Also the B line command, normally processed by the ISPF directory list utility to invoke the ISPF browse function, is instead handled by LCMDPROC.

LCMDS(LCMDPROC,DP,B,LCMD1,W)

The variables in the shared pool shown in Table 3 are used to pass data between ISPF and the line command processor:

Table 3. Variables used to pass data between ISPF and the line command processor
Variable name	Description	Length
ZUDLCMD	Line command	8
ZUDPATH	Pathname of file the line command was entered against	1023
ZUDFTYPE	File type	4
ZUDFPERM	File permissions	10
ZUDFPRMO	File permissions - octal	4
ZUDFOWN	Owner	8
ZUDFAUDT	Audit settings	6
ZUDFEXTA	Extended attributes	4
ZUDFFORM	File format	4
ZUDFGRP	Owner group	8
ZUDFLNKS	Links	14
ZUDFSIZE	File size	20
ZUDFMDTM	Modified date/time	19
ZUDFCDTM	Changed date/time	19
ZUDFADTM	Accessed date/time	19
ZUDCRDTM	Created date/time	19
ZUDMESSG	Allows the line command processor to set the message displayed against the file after the line command is processed	16

Line command processor parameters

Any parameters entered with a line command are passed to the line command processor.

For a REXX line command processor, each parameter specified with the line command is passed as an argument string to the REXX program. For example, if the line command

LL a1 B22 c333

is entered and processed by this REXX line command processor

/*  REXX  */
Arg p1 p2 p3 .
⋮

the REXX variable would have these values:

p1 = 'A1' p2 = 'B22' p3 = 'C333'

For a line command processor that is a program, on entry register 1 contains the address of a Command Processor Parameter List (CPPL). The format of the CPPL is described in the TSO/E ProgrammingGuide. The CPPL contains the address of the command buffer. The text area of the command buffer contains the name of the line command processor followed by any parameters specified with the line command. For example, if the line command

LL a1 B22 c333

is entered, the text area of the command buffer for the line command processor LCMDPGM would contain:

LCMDPGM a1 B22 c333

Line command processor return codes

0: Line command completed successfully.
1: Requests that processing of this line command be handled by the ISPF directory list utility or, if not a recognized directory list line command, passed to TSO.
>=8: The line command failed. ISPF issues message ISRU812.

file-name

The display starting point within the directory list. When this parameter is used, the directory list is positioned to start at the first file matching or after the specified filename.

Return codes

These return codes are possible:

0: Normal completion.
8: Error building the directory list. The error condition is described in the ISPF system dialog variables.
12: A keyword value is incorrect.
20: A severe error occurred while processing the directory list.

Example

This example shows an invocation of DIRLIST which displays the directory list for /SYSTEM/etc. The list shows columns for Permissions, File Type, and Modified Date. The line command processor LCPROC is invoked for line commands LL, B, and UPD.

Command invocation

dir = '/SYSTEM/etc'
ISPEXEC DIRLIST PATH(dir) COLS(PE,10,TY,4,MO,10) LCMDS(LCPROC,LL,B,UPD)

Call invocation

dir = '/SYSTEM/etc';
CALL ISPLINK('DIRLIST ',
             'DIR     ',' ',' ',' ',
             '(PE,10,TY,4,MO,10)',' ',
             '(LCPROC,LL,B,UPD)');