MIAMEX 131: Get file stats

xcall MIAMEX, MX_FILESTATS, loc'rem, path, bytes {, mtime, ctime, mode, ver, hash, owner, group}

MX_FILESTATS returns stats for the specified PATH, either on the local system or the remote PC via ATE.

When MX_FILESTATS is used to query the status of a file on the PC (via ATE), if the filespec is a UNC spec (i.e. starts with "\\"), then the timeout wait is extended from 5 to 15 seconds. This eliminates most problems with ATE timing out before Windows times out, if the UNC spec is not available. The shorter timeout wait was leading to ATE becoming unsynchronized with the server, which in some cases was leading to application confusion.

Parameters

loc'rem (String, 1) [in]

"L" for local system, "R" for remote PC, "C" for client/cache. See History, below, for more info on "C."

path (String) [in]

specifies a native path or AMOS-style filespec. If native, may include embedded environment variables using the %env% syntax. Note that if loc'rem is "R," and AMOS specification in path will be interpreted relative to the INI file used by ATE on the PC.

bytes (F) [out]

returns the size of the file. If path is not found bytes will be set to -1. -2 indicates that you are attempting to use a remote PATH when you do not have ATE support.

mtime, ctime (F or B,4) [out]

return the last modification time and creation time, in seconds since "the epoch" (Midnight Jan 1, 1970). This format is very convenient for comparing file times, but be forewarned that comparing file times on different machines (e.g. to decide if a file transfer/update is needed) requires that you synchronize the clocks on the machines in question! If you want to display the file times in a more human-friendly format, use MX_FTFORMAT.

mode (F or B,2+) [out]

returns the mode bits indicating the type and other attributes of the file. The most interesting bits are:

Symbol	Value	Meaning
FSTS_PRVPX	&h0001	execute privilege (other)
FSTS_PRVPW	&h0002	write privilege (other)
FSTS_PRVPR	&h0004	read privilege (other)
FSTS_PRVGX	&h0008	execute (group)
FSTS_PRVGW	&h0010	write (group)
FSTS_PRVGR	&h0020	read (group)
FSTS_PRVOX	&h0040	execute (owner)
FSTS_PRVOW	&h0080	write (owner)
FSTS_PRVOR	&h0100	read (owner)
FSTS_SSWT	&h0200	save swapped text after use (sticky)
FSTS_SGID	&h0400	set group id on execution
FSTS_SUID	&h0800	set user id on execution
FSTS_PIPE	&h1000	pipe
FSTS_SPC	&h2000	chr/special
FSTS_DIR	&h4000	directory
FSTS_NORM	&h8000	regular file
Definition file: ashell.def

Hex-Decimal Values

ver (String) [out]

returns the file version information (for RUN, LIT and SBX files only), in the format "a.b.c{.d{.e})" where a=vmajor, b=vminor, c=vsub, d=vedit, e=vpatch. Note that because this format may not be convenient for easily comparing two versions to see which is later, optionally you can retrieve the string in the format "aaaaa.bbbbb.ccccc.ddddd.eeeee" by passing a string mapped as 30 bytes for the ver parameter.

Files that do not have versions will return empty version strings (rather than either of the formats described above).

The function does not yet support retrieving version strings from EXE and DLL files, but that may be added in a future update.

hash (String, 15+) [out]

returns the file hash code in the format ###-###-###-###

owner, group [out]

may be returned as either integers or strings. If passed as B,4 variables, the numeric value (uid and gid) will be returned. Otherwise, the string names will be returned. Note that their owner and group info applies only to UNIX versions of A-Shell, but may be supported under some Windows versions in the future.

2011 June, A-Shell 5.1.1222: A new loc'rem parameter value ("C", for client/cache) checks for the file on the local client computer, including looking in the cache and other default local directories. In the case of ATE, this is similar to the "R" (remote) option except that if the file is not found in the specified directory, a search will be made of the other directories that ATE normally checks when trying to open files at the behest of the server (%ATECACHE%, %ATEPERMCACHE%, %MIAME%\icon, and possibly others). In the case of local A-Shell/Windows, this is like the "L" (local) option, except that it also checks the above-mentioned directories. (The cache directory environment variables will typically not be defined for A-Shell/Windows, and thus will be ignored, but the %MIAME%\icons subdirectory and perhaps others may still be valid and searched.) See AG_FILESTATS if you want to retrieve the actual filespec of the found file.

2009 February, A-Shell 5.1.1139: Modify routine to retrieve version and hash along with other file info.