FINDDIR retrieves file and directory names from a starting directory that can be located local to the runtime or from a directory that exists on a PLBCLIENT workstation or a SUNDM data manager.
The returned set of file and directory names are stored in {dest} separated by a pipe (|) character in string variables or as individual items in a DATALIST.
{source} may contain a directory and file name combination with wild card '*' characters to retrieve specific file/directory names.
If the {source} variable data directory name starts with an exclamation point (!), the file and directory data is retrieved from a PLBCLIENT workstation.
If the {source} variable data directory name has
an
|{ip/hostname}:port
appended, the file/directory data is retrieved from a SUNDM data manager.
Each file/directory data item that is stored into the {dest}
variable has a format as follows:
fNAME or dNAME
Where:
f
The leading character of a 'f' indicates that the 'NAME' is a file.
d
The leading character of a 'd' indicates that the 'NAME' is a directory.
The {source} name may contain a filter timestamp that is appended to the {source} name before the SUNDM '|' delimiter. (9.3A) The ';' character is used as the delimiter character for the filter timestamp. The format of the filter is:
Where:
name
- is the search name used for FINDDIR.
op
- is optional operation character that can be a '=', '<', or '>'. If the [op] is not specified, the default operation is the same as a greater than or equal action.
YYYYMMDDhhmmss
- is the last modification timestamp that filters the returned values. The last modification timestamp can be specified from 1 to 14 characters to get the desired filter action.
Examples:
.
. This instruction returns all files and directories that have
. a YYYY year that is greater than or equal to 2008.
.
.
. This instruction returns all files and directories that have
. a YYYYMM year/month that is greater than or equal to 2008.
.
.
. This instruction returns all files and directories that have
. a YYYYMM year/month that is equal to the 200812. This
. instruction is on a Data Manager.
.
FINDDIR "c:\temp\*.*;=200812|127.0.0.1", Dest
.
. This instruction returns all files and directories that have
. a YYYYMMDDhhmmss year/month/day/hour/minute/second that is
. less than 20081215062045.
.
FINDDIR "c:\temp\x.*;<20081215062045", Dest
The {mode} numeric value has the following bit definitions that control various operations for the FINDDIR instruction:
|
Value |
Action |
|
0x1 |
Excludes any hidden files. |
|
0x2 |
Excludes any directory names. |
|
0x4 |
Excludes any file names. |
|
0x8
|
Include the last write time as a delimited field in the return string. These mode bit mask values are mutually exclusive. See Note (13.). (9.3A) 0x8 - The last write times are adjusted for the timezone and Daylight Savings Time (DST). On a Windows system, this last write time form is compatible with the Windows Explorer. 0x20 - The last write times are adjusted for the timezone without being adjusted for the Daylight Savings Time (DST). 0x40 - The raw last write times are returned. The raw last write time is the OS UTC timestamp which is not adjusted to any timezone or Daylight Savings Time (DST). |
|
0x10 |
Include the file size as a delimited field in the return string. (9.3A) |
When the file size and last write time data fields are returned, the fields are delimited with a semicolon (;). The size value is returned first followed by the time. (9.3A)
The first and second characters of the {delimiter} keyword are used in place of all ';' delimiter and '|' delimiter characters used in the FINDDIR instruction. This includes delimiter characters used in the {source} for a filter and the {dest}. However, the {delm} does not affect the '|' used to redirect to a SUNDM. (9.6C)
The ZERO flag is set when the FINDDIR instruction completes successfully.
The EOS flag indicates that there are more name items than can fit into the {dest} variable and data has been lost by truncation.
The MODE bit values of 0x8, 0x20, are 0x40 are mutually exclusive. The 0x40 value takes precedence over the 0x20 and 0x8 values. The 0x20 value takes precedence over the 0x8 value. (9.3A)
The OVER flag indicates that the item count is too large to fit into the {count} variable.
The first and second characters of the {delm} keyword are used in place of all ';' delimiter and '|' delimiter characters used in the FINDDIR instruction. This includes delimiter characters used in the {source} for a filter and the {dest}. However, the {delm} does not affect\replace the '|' used to redirect to a SUNDM.
When the 'DMAKEDEST' keyword is being using used, the end user application causes the FINDDIR behavior to be changed for a destination pointer operand. When 'DMAKEDEST' is used, the FINDDIR behavior changes to reallocate a {dest} DIM pointer by creating a DMAKE DIM variable that is big enough to receive all of finddir data. When 'DMAKEDEST' is used, the user should consider the following:
If
a {dest} DIM pointer DIM variable size is too small to receive all of the finddir data, the FINDDIR instruction
automatically reallocates and changes the {dest} DIM pointer to point to a newly created DMAKE DIM variable.
Therefore, a {dest} DIM pointer is automatically changed any time that the pointer DIM variable is too
small on input.
By
default, a {dest} pointer MUST contain a valid DIM variable reference before the FINDDIR instruction is
executed.
If
the FINDDIR has to reallocate a {des} DIM pointer, the previous DIM pointer is de-referenced and any previous
DMAKE pointer buffers are automatically released.
If
the FINDDIR operation encounters a DMAKE failure, a new F13 error occurs. This kind of internal DMAKE
failure can only occur if there is insufficient memory for a dynamic DIM variable.
If a DATALIST GUI object is used as the {dest} variable, each finddir data item is inserted into the DATALIST as a single line item entry. The end user application must process each DATALIST line item entry as required by the PLB application.
