xcall MIAMEX, MX_FSPEC, spec, locpath, ext, flags, ddb, status

MAP1 SPEC,S,40         ! DevPPN specification

MAP1 LOCPATH,S,160     ! Local (native OS) equivalent fspec

MX_FSPEC is used as an approximation to the FSPEC monitor call. It takes an AMOS format file specification or device name (spec), and processes it into its constituent parts of Device name, File name, and extension (ddb). It also optionally returns the host machine pathname corresponding to the DevPPN specification in locpath.

Parameters

spec  (String)  [in]

should contain the AMOS-format file specification that you want to parse or convert to native format. If the device and/or PPN are omitted, they will be supplied by your current login directory. If the extension is omitted, it will be supplied by the ext parameter. Note that the file does not need to exist, but it must have valid syntax (e.g. "a.a") and not be null (or else an invalid filespec error will result and the returned locpath will either be null or the previously processed filespec). See Comments, below, for information on how to retrieve the current native directory.

locpath  (String)  [out]

is only used if you wish to return the host machine pathname for the file specification given in spec. This is specified by the FS_TOH bit in the flags parameter, in which case the variable locpath should be mapped to an appropriate length for the longest path you expect to deal with. (The maximum path length under Windows is 260 characters.) Otherwise, the parameter may be specified as a null string (""), and it will be set to "" in case of error.

ext  (String)  [in]

 is the default extension to use when processing a full file specification. It will be used if the given specification contains only a filename and no extension. The extension used is returned in the extension field of the ddb structure variable, and is used in the host format pathname if one is returned.

flags  (Num)  [in]

is used to determine exactly how the file specification processing is to take place. It is bit-mapped, and each bit may be set by adding together the symbolic values defined in the include file ashell.def.

ddb  (Structure)  [in/out]

is a structure defined in the include file, ashell.bsi, and is defined as follows:

MAP1 DDB

MAP2 DEV,s,6         ! 6 characters AMOS device

MAP2 FILNAM,s,32     ! 6 characters AMOS or 32 host

MAP2 EXT,s,8         ! 3 characters AMOS or 8 host

MAP2 PRJ,s,3         ! 3 character justified P

MAP2 PRG,s,3         ! 3 character justified PN

It is used to receive either the output of the function call if FS_FMA is specified, or the input to it if FS_TOH is specified, or both. Note the size of the filnam and ext fields. If the FS_FMA bit is specified, then the AMOS format file specification passed, can actually be in the format of a local pathname (with long filename), in which case the filename and extension will be processed correctly.

Note that if you are only interested in translating an AMOS-style specification into the equivalent native specification (i.e. using code FS_FMA+FS_TOH) then you do not really need the fields of the ddb parameter and can just supply an X or S variable of 52+ bytes.

status  (Num)  [out]

returns a non-zero value if the device name (in the spec or ddb parameter/structure) does not exist and the FS_TOH bit is set in the flags parameter. Otherwise it should return zero.

Comments

A common objective is to determine the host directory corresponding to a particular AMOS-style DEVICE:[P,PN] or ersatz device. One way to accomplish this is to start with a dummy filename, like A.A, e.g. "DSK0:A.A[100,222]" or "MYERZ:A.A". Since the A.A will be the last 3 characters of the resulting filespec, you can easily trim them using a substring qualifier, e.g. DIR$ = LOCAL[1,-4].