Guardian Procedure Calls Reference Manual

Returned Value
INT
A file-system error code that indicates the outcome of the call.
Considerations
CAUTION: Passing an invalid file name or file-name pattern to this procedure can result in a
trap, a signal, or data corruption. To verify that a file name or file-name pattern is valid, use the
FILENAME_SCAN_ procedure.
• When the FILENAME_DECOMPOSE_ procedure returns a portion of a file name, it does not
include leading or trailing separators (the characters . :). Internal separators between the parts
of the returned portion are included. Special characters that are part of the name (the characters
$ \ #) are always included.
• The filename parameter can contain a partially qualified file name or file-name pattern.
Unless you specify options.<13> = 1 (no default values), the returned string reflects the
resolution of the file name using the contents of your =_DEFAULTS DEFINE. If you request a
name part that is absent after the file name has been resolved, either because the default
values did not apply or because you specified options.<13> = 1, FILENAME_DECOMPOSE_
returns a value of 0 for piece-length.
Examples
This table shows some possible combinations of input values for calls to FILENAME_DECOMPOSE_
and the resulting output values. Note that "suffix" and "prefix" refer to the "include suffix" and
"include prefix" options, respectively; "name" refers to a subpart value of 4. Assume that the current
default values are "\SYS.$VOL.SUB".
Output piecesubpartoptionslevelInput filename
$a0$a.b.c
$a.b.csuffix0$a.b.c
$VOL0f
$VOL.SUB.fsuffix0f
\SYS.$VOLprefix0f
$p:43210$p:4321.#a
$pname0$p:4321.#a
Related Programming Manual
For programming information about the FILENAME_DECOMPOSE_ procedure, see the Guardian
Programmer's Guide.
568 Guardian Procedure Calls (F)