DEC Text Processing Utility Reference Manual

Document revision date: 19 July 1999

DEC Text Processing Utility Reference Manual

Contents

Index

FAO accepts up to 127 parameters. It can return strings of 65535 characters maximum.

For complete information on the $FAO system service, see the OpenVMS System Services Reference Manual.

To ensure that you get meaningful results, you should use the !AS directive for strings and the !OL, !XL, !ZL, !UL, or !SL directive for integers.

Signaled Errors

TPU$_INVFAOPARAM	WARNING	Argument was not a string or an integer.
TPU$_NEEDTOASSIGN	ERROR	FAO must appear on the right-hand side of an assignment statement.
TPU$_INVPARAM	ERROR	The first argument to FAO must be a string.
TPU$_TOOFEW	ERROR	FAO requires at least one parameter.

Examples

The following example stores the current date and time in the variable date_and_time:

#1
date_and_time := FAO ("!%D",0)

The following example uses the FAO directive !SL in a control string to convert the number equated to the variable count to a string. The converted string is stored in the variable report and then written to the message area.

#2
PROCEDURE user_fao_conversion (count) report := FAO ("number of forms = !SL", count); MESSAGE (report); ENDPROCEDURE;

FILE_PARSE

Format

string3 := FILE_PARSE (filespec [[ , string1
[[, string2
[[, NODE ]]
[[, DEVICE ]]
[[, DIRECTORY ]]
[[, NAME ]] [[, TYPE ]]
[[, VERSION ]]
[[, HEAD ]]
[[, TAIL ]] ]]]])

Parameters

filespec
The file specification to be parsed.
string1
A default file specification. If you fail to specify a field in filespec and that field is present in the default file specification, DECTPU substitutes the field from string1 in the output string.
string2
A related file specification. If you fail to specify a field in filespec and string1 and that field is present in the related file specification and is not the version field, DECTPU substitutes the field from string2 in the output string.
NODE
Keyword specifying that FILE_PARSE should return a file specification, including the node if one of the files specified in filespec, string1, or string2 contains a node field. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section. DECTPU can parse file specifications that contain a node field, but it cannot search, read, or write them. DECTPU parses the node field only for compatibility with OpenVMS file specifications.
DEVICE
VMS keyword specifying that FILE_PARSE should return a file specification, including the device. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
DIRECTORY
Keyword specifying that FILE_PARSE should return a file specification, including the directory. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
NAME
Keyword specifying that FILE_PARSE should return a file specification, including the name. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
TYPE
Keyword specifying that FILE_PARSE should return a file specification, including the type. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
VERSION
Keyword specifying that FILE_PARSE should return a file specification, including the version. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
HEAD
Keyword specifying that FILE_PARSE should return a file specification, including the node, device, and directory fields. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.
TAIL
Keyword specifying that FILE_PARSE should return a file specification, including the file name, type, and version fields. For more information on using the optional keyword parameters to FILE_PARSE, see the Description section.

Return Value

A string that contains an expanded file specification or the file specification field that you specify.

Description

The FILE_PARSE procedure parses a file specification and returns a string that contains the expanded file specification or the field that you specify. If you do not provide a complete file specification, FILE_PARSE supplies defaults in the return string.
If an error occurs during the parse, FILE_PARSE returns a null string. With FILE_PARSE, you can parse file specifications into their individual fields and merge fields from three file specifications into one file specification.
Specify the first three parameters as strings. The remaining parameters are keywords. File specifications that include OpenVMS logical names and device names must terminate with a colon. If you omit optional parameters to the left of a given parameter, you must include null strings as placeholders for the missing parameters.
If you omit any fields from the file specified in filespec, FILE_PARSE supplies defaults, first from string1 and then from string2. The exception to this is that the version field is not supplied from string2.
If you omit the device, directory, type, or version fields from the files specified in filespec, string1, or string2, FILE_PARSE supplies default values. The default values are the current device and directory, the file type delimiter (.), and the file version delimiter (;). (The exception to this is that the current device and directory are not supplied if either string1 or string2 contains a node field.)
You can specify as many of the keywords for field names as you wish as long as you do not specify fields that are duplicates of fields returned by the head or tail keywords. For example, you cannot request the head field along with the node, device, or directory fields; and you cannot request the tail field along with the name, type, or version fields. If valid keyword combinations are present, FILE_PARSE returns a string containing only those fields requested. The fields are returned in normal file specification order. The normal delimiters are included, but there are no other characters separating the fields. For example, suppose you direct DECTPU to execute the following statements:
result := FILE_PARSE ("junk.txt","work::","disk1:",NODE, DEVICE, TYPE); MESSAGE (result);
When the statements execute, DECTPU displays the following string:
WORK::DISK1:.TXT
The FILE_PARSE built-in procedure parses the file specification provided and returns the portions of the resultant file specification requested. It does not check that the file exists.
You can use wildcard directives in supplying file specifications.
Table 2-2 gives an example of the parsing of the following OpenVMS file specification:
node1::usera$:[flamingo.work]eve$section.tpu$section;12
Table 2-2 OpenVMS File Parse Example
Requested Element Returned Information Example

NODE Node name, including trailing colons NODE1::

DEVICE Device name, including colon USERA$:

DIRECTORY Entire directory string [FLAMINGO.WORK]

NAME File name EVE$SECTION

TYPE File type, including period .TPU$SECTION

VERSION File version, including semicolon ;12

HEAD Node, device, and directory NODE1::USERA$:[FLAMINGO.WORK]

TAIL Name, type, and version EVE$SECTION.TPU$SECTION;12

**Table 2-2 OpenVMS File Parse Example**
Requested Element	Returned Information	Example
NODE	Node name, including trailing colons	NODE1::
DEVICE	Device name, including colon	USERA$:
DIRECTORY	Entire directory string	[FLAMINGO.WORK]
NAME	File name	EVE$SECTION
TYPE	File type, including period	.TPU$SECTION
VERSION	File version, including semicolon	;12
HEAD	Node, device, and directory	NODE1::USERA$:[FLAMINGO.WORK]
TAIL	Name, type, and version	EVE$SECTION.TPU$SECTION;12

Signaled Errors

TPU$_PARSEFAIL	WARNING	FILE_PARSE detected an error while parsing the file specification.
TPU$_NEEDTOASSIGN	ERROR	FILE_PARSE must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	FILE_PARSE requires at least one argument.
TPU$_INVPARAM	ERROR	One of the parameters to FILE_PARSE has the wrong data type.
TPU$_BADKEY	ERROR	You specified an invalid keyword to FILE_PARSE.
TPU$_INCKWDCOM	WARNING	You specified HEAD along with NODE, DEVICE, or DIRECTORY; or TAIL along with NAME, TYPE, or VERSION.

Example

The following example returns a full file specification for the file PROGRAM.PAS. The second parameter provides the name of the directory in which the file can be found. Because the device and version fields are missing from the two parameters, FILE_PARSE includes the current device and the version delimiter (;) in the returned file specification.


spec := FILE_PARSE ("program.pass", "[abbott]")

FILE_SEARCH

Format

string3 := FILE_SEARCH (filespec
[[, string1
[[, string2
[[, NODE ]]
[[, DEVICE ]]
[[, DIRECTORY ]]
[[, NAME ]] [[, TYPE ]]
[[, VERSION]]
[[, HEAD ]]
[[, TAIL ]] ]]]])

Parameters

filespec
The file specification that you want to find.
string1
A default file specification. If you fail to specify a field in filespec and that field is present in the default file specification, DECTPU uses the field from string1 when searching for the file.
string2
A related file specification. If you fail to specify a field in filespec and string1 and that field is present in the related file specification and is not the version field, DECTPU uses the field from string2 when searching for the file.
NODE
Keyword specifying that FILE_SEARCH should return a file specification, including the node. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
DEVICE
Keyword specifying that FILE_SEARCH should return a file specification, including the device. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
DIRECTORY
Keyword specifying that FILE_SEARCH should return a file specification, including the directory. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
NAME
Keyword specifying that FILE_SEARCH should return a file specification, including the name. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
TYPE
Keyword specifying that FILE_SEARCH should return a file specification, including the type. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
VERSION
Keyword specifying that FILE_SEARCH should return a file specification, including the version. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
HEAD
Keyword specifying that FILE_SEARCH should return a file specification, including the node, device, and directory fields. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.
TAIL
Keyword specifying that FILE_SEARCH should return a file specification, including the file name, type, and version fields. For more information on using the optional keyword parameters to FILE_SEARCH, see the Description section.

Return Value

A string that contains the partial or full file specification that you request from $SEARCH.

Description

The FILE_SEARCH procedure searches one or more directories and returns the partial or full file specification that matches your request. You must use this built-in procedure multiple times with the same parameter to get all of the occurrences of a file name in the directories.
Specify the first three parameters as strings. The remaining parameters are keywords. File specifications that include OpenVMS logical names and device names must terminate with a colon. If you omit optional parameters to the left of a given parameter, you must include null strings as placeholders for the missing parameters.
Unlike the FILE_PARSE built-in, FILE_SEARCH verifies that the file you specify exists.
If FILE_SEARCH does not find a matching file, or if the built-in finds one or more matches but is invoked again and does not find another match, FILE SEARCH returns a null string but not an error status. Thus, the null string can act as an "end of matching files" indicator. When FILE_SEARCH returns the status TPU$_SEARCHFAIL, look in the message buffer to see why the search was unsuccessful.
Refer to the description of the FILE_PARSE built-in for more information on using the optional parameters to FILE_SEARCH.

Signaled Errors

TPU$_SEARCHFAIL	WARNING	FILE_SEARCH detected an error while searching for the file.
TPU$_TOOFEW	ERROR	FILE_SEARCH requires at least one parameter.
TPU$_NEEDTOASSIGN	ERROR	FILE_SEARCH must be on the right-hand side of an assignment statement.
TPU$_INVPARAM	ERROR	One of the arguments you passed to FILE_SEARCH has the wrong type.
TPU$_BADKEY	WARNING	One of the keyword arguments you specified is not one of those FILE_SEARCH accepts.
TPU$_INCKWDCOM	WARNING	You specified HEAD along with NODE, DEVICE, or DIRECTORY; or TAIL along with NAME, TYPE, or VERSION.

Examples

In the following example, each time this assignment statement is executed on OpenVMS systems, it returns a string that contains the resulting file specification of a file of type .EXE in SYS$SYSTEM. Because no version number is specified, only the latest version is returned. When executing the statement returns a null string, there are no more .EXE files in the directory.

#1
fil := FILE_SEARCH ("SYS$SYSTEM:*.EXE")

The following example is similar to the previous example. It makes use of the fact that you are looking for files in the current OpenVMS directory and that FILE_SEARCH can return parts of the file specification to eliminate the call to FILE_PARSE.

#2
PROCEDURE user_collect_rnos LOCAL filename; ! Reset the file_search context filename := FILE_SEARCH (""); LOOP filename := FILE_SEARCH ("*.RNO", "", "", NAME, TYPE); EXITIF filespec = ""; CREATE_BUFFER (filename, filename); ENDLOOP; ENDPROCEDURE;

PROCEDURE user_collect_rnos 
 
   LOCAL filename; 
 
   ! Reset the file_search context 
 
   filename := FILE_SEARCH (""); 
   
   LOOP 
      filename := FILE_SEARCH ("*.RNO", "", "", NAME, TYPE); 
      EXITIF filespec = ""; 
      CREATE_BUFFER (filename, filename); 
   ENDLOOP; 
ENDPROCEDURE;

FILL

Format

FILL ({buffer|range} [[, string [[, integer1 [[, integer2
[[, integer3 ]] ]] ]] ]])

Parameters

buffer
The buffer whose text you want to fill.
range
The range whose text you want to fill.
string
The list of additional word separators. The space character is always a word separator.
integer1
The value for the left margin. The left margin value must be at least 1 and must be less than the right margin value. This value defaults to the same value as the buffer's left margin.
integer2
The value for the right margin. This value defaults to the same value as the buffer's right margin. Integer2 must be greater than the left margin and cannot exceed the maximum record size for the buffer.
integer3
The value for the first line indent. This value modifies the left margin of the first filled line. It can be positive or negative. The result of adding the first line indent to the left margin must be greater than 1 and less than the right margin. This value defaults to 0.

Description

The FILL procedure reformats the text in the specified buffer or range so that the lines of text are approximately the same length. FILL recognizes two classes of characters: text characters and word separators. Any character can be a word separator, and any character other than the space character can be a text character. The space character is always a word separator, even if it is not present in the second parameter passed to FILL.
A word is a contiguous sequence of text characters, all of which are included on the same line, immediately preceded by a word separator or a line break, and immediately followed by a word separator or line break. If the first or last character in the specified range is a text character, that character marks the beginning or end of a word, regardless of any characters outside the range. Filling a range that starts or ends in the middle of a word may result in the insertion of a line break between that part of the word inside the filled range and that part of the word outside the range.
When filling a range or buffer, FILL does the following to each line:

Removes any spaces at the beginning of the line
Sets the left margin of the line
Moves text up to the previous line if it fits
Deletes the line if it contains no text
Splits the line if it is too long

FILL sets the line's left margin to the default left margin unless that line is the first line of the buffer or range being filled. In this case, FILL sets the line's left margin to the fill left margin plus the first line indent. However, if you are filling a range and the range does not start at the beginning of a line, FILL does not change the left margin of that line.
FILL moves a word up to the previous line if the previous line is in the range to be filled and if the word fits on the previous line without extending beyond the fill right margin. Before moving the word up, FILL appends a space to the end of the previous line if that line ends in a space or a text character. It does not append a space if the previous line ends in a word separator other than the space character.
When moving a word up, FILL also moves up any word separators that follow the word, even if these word separators extend beyond the default right margin. Fill does not move up any word separator that would cause the length of the previous line to exceed the buffer's maximum record size. If the previous line now ends in a space, FILL deletes that space. FILL does not delete more than one such space.
FILL moves any word separators at the beginning of a line up to the previous line. It does this even if the word separators extend beyond the fill right margin.
FILL splits a line into two lines whenever the line contains two or more words and one of the words extends beyond the fill right margin. FILL splits the line at the first character of the first word that contains characters to the right of the fill right margin, unless that word starts at the beginning of the line. In this case, FILL does not split the line.
When operating on a range that does not begin at the first character of a line but does begin left of the fill left margin, FILL splits the line at the first character of the range.
FILL places the cursor at the end of the filled text after completing the previously described tasks.

Signaled Errors

TPU$_INVRANGE	WARNING	You specified an invalid range enclosure.
TPU$_TOOFEW	ERROR	FILL requires at least one argument.
TPU$_TOOMANY	ERROR	FILL accepts no more than five arguments.
TPU$_ARGMISMATCH	ERROR	One of the parameters to FILL is of the wrong type.
TPU$_BADMARGINS	WARNING	You specified one of the fill margins incorrectly.
TPU$_INVPARAM	ERROR	One of the parameters to FILL is of the wrong type.
TPU$_NOTMODIFIABLE	WARNING	You cannot fill text in an unmodifiable buffer.
TPU$_NOCACHE	ERROR	FILL could not create a new line because there was no memory allocated for it.
TPU$_CONTROLC	ERROR	FILL terminated because you pressed Ctrl/C.

Examples

The following example fills the current buffer. It uses the buffer's left and right margins for the fill left and right margins. The space character is the only word separator. Upon completion, the current buffer contains no blank lines. All lines begin with a word. Unless the buffer contains a word too long to fit between the left and right margins, all text is between the buffer's left and right margins. Spaces may appear beyond the buffer's right margin.

#1
FILL (current_buffer)

In the following example, if paragraph_range references a range that contains a paragraph, this statement fills a paragraph. FILL uses a left margin of 5 and a right margin of 65. It indents the first line of the paragraph an additional five characters. The space character and the hyphen are the two word separators. If the paragraph contains a hyphenated word, FILL breaks the word after the hyphen if necessary.

#2
FILL (paragraph_range, "-", 5, 65, 5)

The next example is like the previous one except that FILL unindents the first line of the paragraph by three characters. This is useful for filling numbered paragraphs.

#3
FILL (paragraph_range, "-", 10, 65, -3)

GET_CLIPBOARD

Format

string := GET_CLIPBOARD

Parameters

None.

Return Value

A string that consists of the data read from the clipboard. Line breaks are indicated by a line-feed character (ASCII (10)).

Description

The GET_CLIPBOARD procedure reads STRING format data from the clipboard and returns a string that contains this data. DECwindows provides a clipboard that lets you move data between applications. Applications can write to the clipboard to replace previous data, and can read from the clipboard to get a copy of existing data. The data in the clipboard can be in multiple formats, but all the information in the clipboard must be written at the same time.
DECTPU provides no clipboard support for applications not written for DECwindows.

Signaled Errors

TPU$_NEEDTOASSIGN	ERROR	GET_CLIPBOARD must return a value.
TPU$_TOOMANY	ERROR	Too many arguments passed to GET_CLIPBOARD.
TPU$_CLIPBOARDFAIL	WARNING	The clipboard did not return any data.
TPU$_CLIPBOARDLOCKED	WARNING	DECTPU cannot read from the clipboard because some other application has locked it.
TPU$_CLIPBOARDNODATA	WARNING	There is no string format data in the clipboard.
TPU$_TRUNCATE	WARNING	Characters were truncated because you tried to add text that would exceed the maximum line length.
TPU$_STRTOOLARGE	ERROR	The amount of data in the clipboard exceeds 65535 characters.
TPU$_REQUIRESDECW	ERROR	You can use GET_CLIPBOARD only if you are using DECwindows DECTPU.

Example

The following statement reads what is currently in the clipboard and assigns it to new_string:


new_string := GET_CLIPBOARD;

Previous Next Contents Index

privacy and legal statement

6020PRO_009.HTML

DEC Text Processing Utility Reference Manual

Signaled Errors

Examples

FILE_PARSE

Format

string3 := FILE_PARSE (filespec [[ , string1 [[, string2 [[, NODE ]] [[, DEVICE ]] [[, DIRECTORY ]] [[, NAME ]] [[, TYPE ]] [[, VERSION ]] [[, HEAD ]] [[, TAIL ]] ]]]])

Parameters

filespec

string1

string2

NODE

DEVICE

DIRECTORY

NAME

TYPE

VERSION

HEAD

TAIL

Return Value

Description

Signaled Errors

Example

FILE_SEARCH

Format

string3 := FILE_SEARCH (filespec [[, string1 [[, string2 [[, NODE ]] [[, DEVICE ]] [[, DIRECTORY ]] [[, NAME ]] [[, TYPE ]] [[, VERSION]] [[, HEAD ]] [[, TAIL ]] ]]]])

Parameters

filespec

string1

string2

NODE

DEVICE

DIRECTORY

NAME

TYPE

VERSION

HEAD

TAIL

Return Value

Description

Signaled Errors

Examples

FILL

Format

FILL ({buffer|range} [[, string [[, integer1 [[, integer2 [[, integer3 ]] ]] ]] ]])

Parameters

buffer

range

string

integer1

integer2

integer3

Description

Signaled Errors

Examples

GET_CLIPBOARD

Format

string := GET_CLIPBOARD

Parameters

Return Value

Description

Signaled Errors

Example

string3 := FILE_PARSE (filespec [[ , string1
[[, string2
[[, NODE ]]
[[, DEVICE ]]
[[, DIRECTORY ]]
[[, NAME ]] [[, TYPE ]]
[[, VERSION ]]
[[, HEAD ]]
[[, TAIL ]] ]]]])

string3 := FILE_SEARCH (filespec
[[, string1
[[, string2
[[, NODE ]]
[[, DEVICE ]]
[[, DIRECTORY ]]
[[, NAME ]] [[, TYPE ]]
[[, VERSION]]
[[, HEAD ]]
[[, TAIL ]] ]]]])

FILL ({buffer|range} [[, string [[, integer1 [[, integer2
[[, integer3 ]] ]] ]] ]])