# MX\_FSPEC
> [HTML Version](mx_fspec.htm)
_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](string.md)) \[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](string.md)) \[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](string.md)) \[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](num.md)) \[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](ashell_def.md).
| **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](ashell_def.md)** | |
_ddb_ ([Structure](structure.md)) \[in/out\]
a structure defined in [ashell.sdf](https://bitbucket.org/microsabio/soslib/src/master/907016/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 DevPPN 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](num.md)) \[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.