no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Next revision | |||
— | en:docs:fapi:dosfindfirst [2018/08/30 14:22] – created prokushev | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | This call finds the first file object or group of file objects whose name(s) match the specification. | ||
+ | |||
+ | ==Syntax== | ||
+ | | ||
+ | | ||
+ | |||
+ | ==Parameters== | ||
+ | ;FileName (PSZ) - input : Address of the ASCIIZ path name of the file or subdirectory to be found. The name component may contain global file name characters. | ||
+ | ;DirHandle (PHDIR) - input/ | ||
+ | :0001H - Assign handle 1, which is always available to a process. | ||
+ | :FFFFH - The system allocates and returns a handle. If on input FFFFH is specified, on output :DirHandle contains the handle allocated by the system. | ||
+ | :The DosFindFirst handle is used with subsequent DosFindNext requests. Reuse of this handle in another DosFindFirst closes the association with the previous DosFindFirst and opens a new association. | ||
+ | ;Attribute (USHORT) - input : Attribute value that determines the file objects to be searched for. | ||
+ | ''' | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived. | ||
+ | | ||
+ | If Attribute is 0, normal file entries are found. Entries for subdirectories, | ||
+ | | ||
+ | Attribute cannot specify the volume label. Volume labels are queried using DosQFSInfo. Attributes of a file are queried and set with DosQFileMode and DosSetFileMode. | ||
+ | |||
+ | ; ResultBuf (PFILEFINDBUF) - output : Address of the structure that contains the returned directory information. The information reflects the last DosClose, DosBufReset, | ||
+ | |||
+ | * filedate (FDATE) : Structure containing the date of file creation. | ||
+ | |||
+ | ''' | ||
+ | | ||
+ | | ||
+ | | ||
+ | |||
+ | * filetime (FTIME) : Structure containing the time of file creation. | ||
+ | |||
+ | ''' | ||
+ | | ||
+ | | ||
+ | | ||
+ | |||
+ | * fileaccessdate (FDATE) : Structure containing the date of last access. See FDATE in filedate. | ||
+ | |||
+ | * fileaccesstime (FTIME) : Structure containing the time of last access. See FTIME in filetime. | ||
+ | |||
+ | * writeaccessdate (FDATE) : Structure containing the date of last write. See FDATE in filedate. | ||
+ | |||
+ | * writeaccesstime (FTIME) : Structure containing the time of last write. See FTIME in filetime. | ||
+ | |||
+ | * filesize (ULONG): File size. | ||
+ | |||
+ | * filealloc (ULONG) : Allocated file size. | ||
+ | |||
+ | * fileattrib (USHORT) : Attributes of the file, defined in DosSetFileMode. | ||
+ | |||
+ | * length (UCHAR) : Length of the ASCIIZ name string. | ||
+ | |||
+ | * matchfilename (CHAR) : ASCIIZ name string for the first occurrence of FileName. | ||
+ | |||
+ | ; ResultBufLen (USHORT) - input : Length of ResultBuf | ||
+ | |||
+ | ; SearchCount (PUSHORT) - input/ | ||
+ | |||
+ | ; Reserved (ULONG) - input : Reserved, must be set to zero. | ||
+ | |||
+ | ==Return Code== | ||
+ | rc (USHORT) - return | ||
+ | Return code descriptions are: | ||
+ | * 0 NO_ERROR | ||
+ | * 2 ERROR_FILE_NOT_FOUND | ||
+ | * 3 ERROR_PATH_NOT_FOUND | ||
+ | * 6 ERROR_INVALID_HANDLE | ||
+ | * 18 | ||
+ | * 26 | ||
+ | * 87 | ||
+ | * 108 ERROR_DRIVE_LOCKED | ||
+ | * 111 ERROR_BUFFER_OVERFLOW | ||
+ | * 113 ERROR_NO_MORE_SEARCH_HANDLES | ||
+ | * 206 ERROR_FILENAME_EXCED_RANGE | ||
+ | ==Remarks== | ||
+ | DosFindFirst returns directory entries (up to the number requested in SearchCount) for as many files or subdirectories whose names and attributes match the specification and whose information fits in ResultBuf. On output, SearchCount contains the actual number of directory entries returned. | ||
+ | |||
+ | DosFindNext uses the directory handle associated with DosFindFirst to continue the search started by the DosFindFirst request. | ||
+ | |||
+ | Any non-zero return code indicates no handle has been allocated, including such non-error indicators as ERROR_NO_MORE_FILES. | ||
+ | |||
+ | DosQSysInfo is called by an application to determine the maximum path length allowed by OS/2. | ||
+ | |||
+ | For programs running without the NEWFILES bit set, only 8.3 filename format names are returned. These names are changed to uppercase. | ||
+ | |||
+ | ===Family API Considerations=== | ||
+ | Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restrictions apply to DosFindFirst when coding for the DOS mode: | ||
+ | |||
+ | DirHandle must always equal hex 0001H or FFFFH on the initial call to DosFindFirst. Subsequent calls to DosFindFirst must have a DirHandle of hex 0001H unless a DosFindClose had been issued. In this case, 0001H or FFFFH is allowed. | ||
+ | |||
+ | ==Example Code== | ||
+ | ===C Binding=== | ||
+ | <PRE> | ||
+ | typedef struct _FDATE { /* fdate */ | ||
+ | |||
+ | unsigned day : 5; /* binary day for directory entry */ | ||
+ | unsigned month : 4; /* binary month for directory entry */ | ||
+ | unsigned year : 7; /* binary year for directory entry */ | ||
+ | |||
+ | } FDATE; | ||
+ | |||
+ | typedef struct _FTIME { /* ftime */ | ||
+ | |||
+ | unsigned twosecs : 5; /* binary number of two-second increments */ | ||
+ | unsigned minutes : 6; /* binary number of minutes */ | ||
+ | unsigned hours : 5; /* binary number of hours */ | ||
+ | |||
+ | } FTIME; | ||
+ | |||
+ | typedef struct _FILEFINDBUF { /* findbuf */ | ||
+ | |||
+ | FDATE fdateCreation; | ||
+ | FTIME ftimeCreation; | ||
+ | FDATE fdateLastAccess; | ||
+ | FTIME ftimeLastAccess; | ||
+ | FDATE fdateLastWrite; | ||
+ | FTIME ftimeLastWrite; | ||
+ | ULONG cbFile; | ||
+ | ULONG cbFileAlloc; | ||
+ | USHORT attrFile; | ||
+ | UCHAR cchName; | ||
+ | CHAR | ||
+ | |||
+ | } FILEFINDBUF; | ||
+ | |||
+ | #define INCL_DOSFILEMGR | ||
+ | |||
+ | USHORT | ||
+ | | ||
+ | |||
+ | PSZ FileName; | ||
+ | PHDIR DirHandle; | ||
+ | USHORT | ||
+ | PFILEFINDBUF | ||
+ | USHORT | ||
+ | PUSHORT | ||
+ | ULONG 0; /* Reserved (must be zero) */ | ||
+ | |||
+ | USHORT | ||
+ | |||
+ | </ | ||
+ | |||
+ | This example searches for a file matching the pattern ' | ||
+ | <PRE> | ||
+ | #define INCL_DOSFILEMGR | ||
+ | |||
+ | #define NORMAL_FILES 0 | ||
+ | #define HIDDEN_FILES 2 | ||
+ | #define SEARCH_PATTERN " | ||
+ | #define FILE_ATTRIBUTE NORMAL_FILES | HIDDEN_FILES | ||
+ | #define RESERVED 0L | ||
+ | |||
+ | HDIR FindHandle; | ||
+ | FILEFINDBUF FindBuffer; | ||
+ | USHORT | ||
+ | USHORT | ||
+ | |||
+ | | ||
+ | | ||
+ | |||
+ | rc = DosFindFirst(SEARCH_PATTERN, | ||
+ | & | ||
+ | | ||
+ | & | ||
+ | | ||
+ | & | ||
+ | | ||
+ | </ | ||
+ | ===MASM Binding=== | ||
+ | <PRE> | ||
+ | FDATE struc | ||
+ | |||
+ | fdate_fs | ||
+ | |||
+ | FDATE ends | ||
+ | |||
+ | FTIME struc | ||
+ | |||
+ | ftime_fs | ||
+ | |||
+ | FTIME ends | ||
+ | |||
+ | FILEFINDBUF struc | ||
+ | |||
+ | findbuf_fdateCreation | ||
+ | findbuf_ftimeCreation | ||
+ | findbuf_fdateLastAccess dw (size FDATE)/2 dup (?) ;file date of last access | ||
+ | findbuf_ftimeLastAccess dw (size FTIME)/2 dup (?) ;file time of last access | ||
+ | findbuf_fdateLastWrite | ||
+ | findbuf_ftimeLastWrite | ||
+ | findbuf_cbFile | ||
+ | findbuf_cbFileAlloc | ||
+ | findbuf_attrFile | ||
+ | findbuf_cchName | ||
+ | findbuf_achName | ||
+ | |||
+ | FILEFINDBUF ends | ||
+ | |||
+ | EXTRN DosFindFirst: | ||
+ | INCL_DOSFILEMGR | ||
+ | |||
+ | PUSH@ ASCIIZ | ||
+ | PUSH@ WORD DirHandle | ||
+ | PUSH | ||
+ | PUSH@ OTHER | ||
+ | PUSH | ||
+ | PUSH@ WORD SearchCount | ||
+ | PUSH | ||
+ | CALL | ||
+ | |||
+ | Returns WORD | ||
+ | </ | ||
+ | |||
+ | |||
+ | ====== Note ====== | ||
+ | |||
+ | Text based on [[http:// | ||
+ | |||
+ | {{page> |