A-Shell Reference

Updated August 2023; see History

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

MX_FILESTATS (MIAMEX 131) returns stats for the specified path, either on the local system or the remote PC via ATE.

This function has both a subroutine and a print tab implementation.

Parameters

loc'rem  (String, 1)  [in]

"L" for local system, "R" for remote PC, "C" for client/cache. See Comments, 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  (signed Num)  [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,6)  [out]

return the last modification time (mtime) or creation time (ctime), in seconds since "the epoch" (Midnight Jan 1, 1970). Note that "time" includes date, in this context. 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. See fndatetime.bsi in SOSLIB:[907,10] for some useful and related date/time functions. See History note, below, for A-Shell 6.5.1740.

mode  (F or B2+)  [out]

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

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 support retrieving version strings from EXE and DLL files.

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.

atime  (Num)  [out]

last access time

 

Comments

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.

The 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 Get File Stats if you want to retrieve the actual filespec of the found file.

See Also

History

2023 August, A-Shell 6.5.1740:  Add support for additional timestamp bits (beyond 32) to resolve the Year 2038 problem. Note that you have to specify a parameter type capable of supporting more than 32 bits, e.g. B6 or F6.

2023 August, A-Shell 6.5.1740:  Add support for atime, last access time