SCAF - convert ASCII pathname to BCD catfile stack.

Alternate Entry Name: .SCAF

Usage:

B:
   status = scaf( string, buffer [, catflag, size] );

C:
   int scaf(const char *string, void *buffer,
            [int catflag, int size] );

Where:

string: is a pointer to an ASCII string which contains a valid pathname.
buffer: is a pointer to an area of storage where the converted string is to be placed. SCAF will use four words per catalog or file, plus one for fence, plus three for an altname (so the altname will be aligned the same as "buffer").
catflag: indicates to SCAF whether or not "string" is a catalog description. If "catflag" is non-zero, "string" is a catalog description; if "catflag" is zero, "string" is not. Thus if "catflag" is non-zero and "string" contains no '/', "string" will be taken as a user name rather than a quick access file name. If "catflag" is not specified, the default value is zero.
size: is the offset to the last word in "buffer". This size cannot be exceeded. The default for "size" is 43, allowing 10 levels of catalogs.

Description:

SCAF takes the pathname in "string" and converts it into a format suitable for GCOS/TSS file system calls. The converted pathname is placed in "buffer". SCAF stops scanning "string" when it encounters any one of the characters "*n*r*t*e " and possibly "+".

If an altname is specified (cat/file"alt"), it is put into "buffer" in lower case. In order to make alignment easy, the word immediately after the fence is ignored, and the altname is placed in the next two words. If no explicit altname is given, the file name is used.

If "catflag" is zero or not present and if no errors occur in the scan, a pointer is returned to the altname (two words of ASCII) within "buffer". Bit 17 (1,du) is set if a "quick access" name was found, and bit 16 (2,du) is set if an altname was specified. Bit 17 will not be set if bit 16 is set. A "+" will be considered a normal filename terminator.

If "catflag" is present and non-zero, neither bit 16 nor bit 17 will be set and no altname is generated if none is supplied. However, the "status" returned is a pointer to the place reserved for the altname. A "+" character will be considered illegal if encountered.

In case of error, SCAF returns a status of -28, indicating "bad pathname". Possible causes for error include

illegal character in filename
too many catalog levels
name longer than 12 characters
altname longer than eight characters

Use of a name that looks like a quick access name (i.e. no '/', '$', or altname) but is longer than eight characters will also be treated as an error.

SCAF now makes use of the standard .EPOST facilities for posting error messages, so you may use .STRER to obtain messages for errors detected by SCAF.