Get IFS Directory Entries

ifsGetDir

The ifsGetDir procedure returns the names of the files and/or directories in the specified directory.

The ifsGetDir procedure enumerates a list of files and/or directory names for the given directory. Each of those entries are returned to the specified user-supplied return variable. The file or directory name, type (*STMF or *DIR) and size (if *STMF) are returned for each entry.

 number-of-entries-returned   ifsGetDir(
     **  Return file/dir list buffer (any length)

D szRtnBuffer 1A OPTIONS(*VARSIZE)

** Return buffer length

D nBufLen 10I 0 Const

** IFS directory to enumerate

D szIFSPath 640A Const VARYING

** Type of list IFS_FILES or IFS_DIR

D nListType 10I 0 Const OPTIONS(*NOPASS:*OMIT)

** Return format DFT(IFSD0100)

D szFmt 8A Const OPTIONS(*NOPASS:*OMIT)
)

See also:

Parameters

szRtnBuffer: [ input Char(*) ] A variable that will receive the directory entries. The parameter may be any length. This parameter must be large enough to receive the entire list. The length of this parameter is specified on the nBufLen parameter. The format of this parameter must be as follows:; If szFmt is IFSD0100, or is unspecified the following data structure is returned for each entry in the specified directory.

D IFSD0100 DS DIM(xxx) QUALIFIED

D IFS_Entry1_Name...

D 20A

D IFS_Entry1_Type...

D 10A

D IFS_Entry1_Size...

D 20U 0

Where xxx is the maximum number of entries that you want to receive.

If szFmt is IFSD0200, the following data structure is returned for each entry in the specified directory.

D IFSD0200 DS DIM(xxx) QUALIFIED

D IFS_Entry2_Name...

D 640A

D IFS_Entry2_Type...

D 10A

D IFS_Entry2_Size...
D 20U 0

Where xxx is the maximum number of entries that you want to receive.

nBufLen: [ input Int4 (10i0) Const ] Specify the length of the return buffer specified on the first parameter, szRtnBuffer. If the length specified on this parameter is less than what is required to return all the entries on the list, the size of the return buffer will not be exceed and some data may not be returned.

szIFSPath: [ input VChar(*) ] A variable or literal that identifies the folder whose entries are to be enumerated. The files and directories in this IFS folder are listed and returned to the first parameter.

nListType - Optional - DFT(IFS_FILES)

[ input Int4 (10i0) Const ] Specify the type of entries to be enumerated. If this parameter is not specified, or specified as *OMIT, the IFS_FILE option is used as the default. The value List Type options include:

Option	Value	Description
IFS_FILES	1	Create a list of files in the specified folder.
IFS_DIR or IFS_DIRS	2	Create a list of directories in the specified folder.
IFS_ALL	3	Create a list of files and directories in the specified folder.

szFormat - Optional - DFT('IFSD0100'): [ input Char(8) ] Avariable or literal that identifies the folder whose entries are to be enumerated. The files and directories in this IFS folder are listed and returned to the first parameter.

Format Description

IFSD0100 A shorter entry name area is returned along with the entry type and size. The return data structure contains a 20-position field for the entry name. The format of this data structure is as follows:
     D IFSD0100        DS

     D IFS_Entry1_Name...

     D                               20A

     D IFS_Entry1_Type...

     D                               10A

     D IFS_Entry1_Size...

     D                               20U 0

Use this format when you are certain that the file and directory names in the folder are 20 characters or less. This format uses less storage than the IFSD0200 format.

IFSD0200 A full entry name area is returned along with the entry type and size. The return data structure contains a 640-position field for the entry name. The format of this data structure is as follows:
     D IFSD0200        DS

     D IFS_Entry2_Name...

     D                              640A

     D IFS_Entry2_Type...

     D                               10A

     D IFS_Entry2_Size...
     D                               20U 0

Use this format when you have long names in the folder.

IFSD0300 A full entry name area is returned along with the entry type, size, creation, last access, last modified, last changed date and times.
The date and time fields are named as follows:

IFS_Entry3_xxxDate

IFS_Entry3_xxxTime

Where xxx is CRT, CHG, MOD, ACC for Creation, Last Changed, Last data modified, last accessed.

Return Value

If the function succeeds, the return value the number of entries copied to the szRtnBuffer parameter. Note that this number may be less than the actual number of entries in the folder since ifsGetDir stops processing when it fills up the return value with nBufLen bytes.

If the function fails or there are no entries in the folder, 0 is returned. If an error occurs, a message is written to the joblog.

Example

The following example illustrates two methods for testing to see if an override exists for a file. The first technique actually saves the override information into the MYOVRDS data structure. The second technique simply tests for an override by comparing the return value to blanks, if it is not blanks, then an override exists for the ITEMMAST file.

      /INCLUDE qcpysrc,utils

      /INCLUDE qcpysrc,ifslib

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++

D MyFiles DS DIM(100) QUALIFIED INZ

D Name 20A

D Type 10A

D Size 10U 0

D nEntries 10I 0

D i 10I 0

.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++

     C**  Create a list of files in the /home/mystuff folder

     C                   eval      nEntries = ifsGetDir(szFiles:%size(szFiles):

     C                                          '/home/mystuff': IFS_FILES)

     C**  Write the name and size of each file to the joblog.

     C                   for       i = 1 to nEntries

     C                   CallP     WrtJobLog('%s %s': %TrimR(myFiles.Name):

     C                                        %char(MyFiles.Size) )

     C                   endfor

Format	Description
IFSD0100	A shorter entry name area is returned along with the entry type and size. The return data structure contains a 20-position field for the entry name. The format of this data structure is as follows: D IFSD0100 DS D IFS_Entry1_Name... D 20A D IFS_Entry1_Type... D 10A D IFS_Entry1_Size... D 20U 0 Use this format when you are certain that the file and directory names in the folder are 20 characters or less. This format uses less storage than the IFSD0200 format.
IFSD0200	A full entry name area is returned along with the entry type and size. The return data structure contains a 640-position field for the entry name. The format of this data structure is as follows: D IFSD0200 DS D IFS_Entry2_Name... D 640A D IFS_Entry2_Type... D 10A D IFS_Entry2_Size... D 20U 0 Use this format when you have long names in the folder.
IFSD0300	A full entry name area is returned along with the entry type, size, creation, last access, last modified, last changed date and times. The date and time fields are named as follows: IFS_Entry3_xxxDate IFS_Entry3_xxxTime Where xxx is CRT, CHG, MOD, ACC for Creation, Last Changed, Last data modified, last accessed.