Reviewed and Revised April 2024
xcall MIAMEX, MX_FSPEC, spec, locpath, ext, flags, ddb, status
MX_FSPEC (MIAMEX 3) deconstructs a DevPPN filespec 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 DevPPN-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.
Symbol |
Value |
Description |
|---|---|---|
FS_DRV |
1 |
indicates that the drive name and number only are to be processed. When used in conjunction with FS_FMA (2), the device specification given in spec is returned in the ddb structure parameter. |
FS_FMA |
2 |
indicates that the file specification given in the spec parameter is to be used. Otherwise the already processed specification given in its constituent parts in the ddb structure parameter will be used. It only makes sense to omit this bit if the FS_TOH (4) bit is set, indicating that a host machine pathname is to be returned. |
FS_TOH |
4 |
indicates that the host machine path name corresponding either to the file specification in spec or in the ddb structure parameter is to be returned in the locpath parameter. If this bit is not specified then locpath may be given as a null string ("") |
Definition file: ashell.def |
||
ddb (Structure) [in/out]
a structure defined in ashell.sdf as one of the following. The routine will detect which version was passed based on its size.
! original version...
defstruct ST_DDB
map2 DEV,s,6 ! 6 characters AMOS device
map2 FILNAM,s,32 ! 10 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
map2 SPECTYPE,b,2 ! [104] see SPECTYPE_ xxx (optional in 6.5.1613.0+; ignored before)
endstruct
! extended version (see History below)...
defstruct ST_DDBX
map2 DEV,s,6 ! 6 characters AMOS device
map2 FILNAM,s,72 ! 72 characters filename
map2 EXT,s,8 ! 8 characters extension
map2 PRJ,s,3 ! 3 character justified P
map2 PRG,s,3 ! 3 character justified PN
map2 SPECTYPE,b,2 ! see SPECTYPE_ xxx
endstruct
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].
History
2019 June, A-Shell 6.5.1662: The 32.8 FILNAM.EXT limit increased to 72.8 via introduction of ST_DDBX. Function determines which version passed by its size.
