[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

DEC Text Processing Utility Reference Manual


Previous Contents Index

This assignment statement returns the following DECTPU keyword names in the string full_name:


ON UP DO E5 F6 E4 F7 F4 F5 E6 E1 F2 F3 E3 F1 E2 F8 F9 

The following example uses the string that you enter as the parameter, and puts the expanded form of a valid DECTPU procedure name that matches the string in the message area. If the initial string matches multiple procedure names, or if it is not a valid DECTPU procedure name, an explanatory message is written to the message area.
#2

PROCEDURE user_quick_parse (abbreviated_name) 
 
   ON_ERROR 
       IF ERROR = TPU$_NONAMES 
       THEN 
           MESSAGE ("No such procedure."); 
       ELSE 
          IF ERROR = TPU$_MULTIPLENAMES 
          THEN 
              MESSAGE ("Ambiguous abbreviation."); 
          ENDIF; 
       ENDIF; 
       RETURN; 
   ENDON_ERROR; 
 
   expanded_name := EXPAND_NAME (abbreviated_name, PROCEDURES); 
   MESSAGE ("The procedure is " + expanded_name + "."); 
ENDPROCEDURE; 
      


FAO


Format

string2 := FAO (string1 [[, [[, ... ]]]])


Parameters

string1

A string that consists of the fixed text of the output string and Formatted ASCII Output (FAO) directives.

Some FAO directives that you can use as part of the string are the following:
!AS Inserts a string as is
!OL Converts a longword to octal notation
!XL Converts a longword to hexadecimal notation
!ZL Converts a longword to decimal notation
!UL Converts a longword to decimal notation without adjusting for negative numbers
!SL Converts a longword to decimal notation with negative numbers converted
!/ Inserts a new line (carriage return/line feed)
!_ Inserts a tab
!} Inserts a form feed
!! Inserts an exclamation mark
!%S Inserts an s if the most recently converted number is not 1
!%T Inserts the current time if you enter 0 as the parameter (you cannot pass a specific time because DECTPU does not use quadwords)
!%D Inserts the current date and time if you enter 0 as the parameter (you cannot pass a specific date because DECTPU does not use quadwords)

integer1 ... integer_n

An expression that evaluates to an integer. $FAO uses these integers as arguments to the FAO directives in string2 to form string1.

string3 ... string_n

An expression that evaluates to a string. $FAO uses these strings as arguments to the FAO directives in string2 to form string1.

Return Value


A string that contains the output you specify in ASCII format.

Description

The FAO procedure invokes the Formatted ASCII Output ($FAO) system service to convert a control string to a formatted ASCII output string. By specifying arguments for FAO directives in the control string, you can control the processing performed by the $FAO system service. The FAO procedure returns a string that contains the formatted ASCII output, constructed according to the rules of the $FAO system service. The control string directs the formatting process, and the optional arguments are values to be substituted into the control string.

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:
#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

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


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


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; 
      


FILL


Format

FILL ( [[, 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:

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.
#1

FILL (current_buffer) 
      


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
6020PRO_009.HTML