HP OpenVMS Systems Documentation

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

Examples

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

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.

PROCEDURE user_fao_conversion (count)

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

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

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

Signaled Errors

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]")
      

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

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

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.

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.

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;
      

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

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.

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.

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.

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

Format

string := GET_CLIPBOARD

Parameters

None.

Return Value

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

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