FPARSE

Syntax

          CA           I16A    U16A  I32A
  FPARSE (formaldesig, result, item, vector);

Parameters

formaldesig

character array (required)

Passes the file reference string to be parsed. Terminate the string with any nonalphanumeric character except a slash (/), period (.), or colon (:).

If an error occurs, the first element of the vector array returns the byte offset of the invalid item in formaldesig.

result

16-bit signed integer array (required)

Returns two elements; the first element is the error number, the second element is reserved and always returns 0.

A positive value indicates the syntax of the specified file reference is correct and what type of file reference is being made. A negative value indicates a syntax error in the file reference.

The possible error number values are:

Value	Meaning
0	Regular file designator
1	Backreference (* is the first character in formaldesig)
2	System file ($ is the first character in formaldesig) The default designator numbers for system files, as defined for FOPEN foption, are: 0 File name 1 $STDLIST 2 $NEWPASS 3 $OLDPASS 4 $STDIN 5 $STDINX 6 $NULL
-1	Invalid item values
-2	Parameter bounds violation
-3	Illegal delimiter; misuse of ., /, or :
-4	Item specified without specifying vector
-5	Illegal value in item
-6	Item list not terminated by 0
-7	Undefined system file
-8	Lockword not allowed in backreferenced (*) file
-9	NS 3000/XL not present; envidname was specified
-101	First character of the file name not alphabetic
-102	File name expected in the string
-103	File name identifier too long
-104	First character of lockword not alphabetic
-105	Lockword expected in string
-106	Lockword identifier too long
-107	First character of group name not alphabetic
-108	Group name expected in string
-109	Group name identifier too long
-110	First character of the account name not alphabetic
-111	Account name expected in string
-112	Account name identifier too long
-113	First character of envidname not alphabetic
-114	Expected envidname in string
-115	Identifier for envidname too long

NOTE: Up to three identifiers can be specified, separated by a period (.), in an envidname; errors -113 through -115 can reference one of the three identifiers. The error pointer indicates the location. If NS 3000/XL is not installed on the system, FPARSE returns a -9 for file designators with an envidname after the file name. This error indicates that everything up to envidname was valid, but a parsed vector array is not returned.

items

16-bit unsigned integer array (optional)

Passes an item code, one value per element, indicating what the corresponding vector parameter points to:

vector

32-bit signed integer array (optional)

Returns vectors, one per element, for the requested item.

NOTE: A vector cannot be passed without a corresponding item value.

Information is returned as follows:

Bits	Value/Meaning
16:16	Return the length of the string specified by the corresponding items parameter. If zero is returned, the requested item in formaldesig was not specified.
0:16	Return the offset, in bytes, from the base of the formaldesig parameter to the first element of the string segment specified by the corresponding item parameter.

The last element returns the file designator length passed in formaldesig (bits (16:16)) and the default type (bits (0:16)) if the result parameter indicates a system file.

NOTE: It is not recommended that applications parse file names on their own. Instead, use the FPARSE intrinsic to do so.

Related Information