Format

Parameters

string

The command string that you want to be executed in the context of the
subprocess that is created with SPAWN.

ON, 1

A keyword that indicates that control is to be returned to DECTPU after
the command has been executed. This is the default unless the value
specified for the first parameter is the null string.

OFF, 0

A keyword that indicates that you are to be prompted for additional
operating system commands after the specified command has been
executed. If the value specified for the first parameter is the null
string, the default value for the second parameter is OFF.

Description

The SPAWN procedure creates a subprocess that runs the command line
interpreter. SPAWN suspends your DECTPU process and starts a
subprocess. This built-in procedure is especially useful for running
programs and utilities that take control of the screen (these programs
cannot be run in a subprocess created with the CREATE_PROCESS) built-in
procedure. See the Guide to the DEC Text Processing Utility
for a list of restrictions for subprocesses.

If you are using DCL, you can return to your DECTPU session after
finishing in a subprocess by using either the DCL ATTACH command or the
DCL LOGOUT command. If you use the DCL ATTACH command, the subprocess
is available for future use. If you use the DCL LOGOUT command, the
subprocess is deleted. When you return to the DECTPU session, the
screen is repainted.

If you specify a DCL command as the parameter for SPAWN, the command is
executed after the subprocess is created. When the command completes,
the subprocess terminates and control is returned to the DECTPU
process. If you want to remain at the system prompt, add the OFF
keyword as the second parameter.

Subprocesses created with SPAWN give you direct access to the command
line interpreter. These subprocesses are different from the
subprocesses created with the CREATE_PROCESS built-in procedure.
CREATE_PROCESS creates a subprocess within a DECTPU session, and all of
the output from the subprocess goes into a buffer.

SPAWN is not a valid built-in in DECwindows DECTPU. However, if you are
running non-DECwindows DECTPU in a DECwindows terminal emulator, SPAWN
works as described in this section.

SPAWN fails if you are running in an OpenVMS account with the CAPTIVE
flag set in the authorization file.

See the description of the ATTACH built-in procedure for information on
moving control from one subprocess to another. See the OpenVMS DCL Dictionary for
more information on the characteristics of an OpenVMS spawned
subprocess.

If the current buffer is mapped to a visible window, the SPAWN built-in
procedure causes the screen manager to synchronize the editing point
(which is a buffer location) with the cursor position (which is a
window location). This may result in the insertion of padding spaces or
lines into the buffer if the cursor position is before the beginning of
a line, in the middle of a tab, beyond the end of a line, or after the
last line in the buffer.

Signaled Errors

TPU$_TOOMANY

ERROR

Too many arguments passed to the SPAWN built-in.

TPU$_INVPARAM

ERROR

Wrong type of data sent to the SPAWN built-in.

TPU$_REQUIRESTERM

ERROR

SPAWN is not a valid built-in in DECwindows DECTPU.

TPU$_UNKKEYWORD

ERROR

An unknown keyword was used as an argument. Only ON or OFF is allowed.

TPU$_BADKEY

ERROR

An unknown keyword was used as an argument. Only ON or OFF is allowed.

TPU$_CAPTIVE

WARNING

Unable to create a subprocess in a captive account.

TPU$_CREATEFAIL

WARNING

Unable to activate the subprocess.

Example

The following example spawns a subprocess and puts your DECTPU process
on hold. The DCL command is executed in the subprocess to show the
translation of the logical name SYS$LOGIN, and you are left at the DCL
prompt. After completing work in the subprocess, you can return to your
DECTPU session by using the DCL ATTACH command or the DCL LOGOUT
command.

Format

SPLIT_LINE

Parameters

None.

Description

The SPLIT_LINE procedure breaks the current line before the editing
point and creates two lines. The relative screen position of the line
you are splitting may change as a result of this procedure. The first
line contains any characters to the left of the editing point. The
second line contains the rest of the characters. The new line that is
created is inserted directly after the former current line.

When you use SPLIT_LINE, the editing point remains on the same
character, but that character is now the first character on the newly
created line.

If the editing point is not the first character in the line being
split, the left margin of the old line is not changed. The new line,
which contains the editing point and the characters to the right of the
editing point, takes the buffer's left margin as its own left margin.

If the editing point is the first character of a line, SPLIT_LINE
creates a blank line where the original line was. The left margin of
this blank line is the buffer's left margin. SPLIT_LINE moves the
original line, including the editing point, to the line below the blank
line. If the original line had a left margin different from the
buffer's current left margin, SPLIT_LINE preserves the original line's
left margin when it moves the line down.

If the editing point is on a blank line, SPLIT_LINE creates a new blank
line below the existing line. The editing point moves to the new blank
line. The new blank line receives the buffer's left margin value. If
the original blank line had a left margin different from the buffer's
current left margin, the original blank line retains its margin.

Using SPLIT_LINE may cause DECTPU to insert padding spaces or blank
lines in the buffer. SPLIT_LINE causes the screen manager to place the
editing point at the cursor position if the current buffer is mapped to
a visible window. For more information on the distinction between the
cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is
before the beginning of a line, beyond the end of a line, in the middle
of a tab, or below the end of the buffer), DECTPU inserts padding
spaces or blank lines into the buffer to fill the space between the
cursor position and the nearest text.

Signaled Errors

TPU$_NOCURRENTBUF

WARNING

You are not positioned in a buffer.

TPU$_NOCACHE

ERROR

There is not enough memory to allocate a new cache.

TPU$_NOTMODIFIABLE

WARNING

You cannot modify an unmodifiable buffer.

TPU$_TOOMANY

ERROR

SPLIT_LINE takes no arguments.

Example

The following example splits a line at the editing point. If the
editing point is row 1, column 1, the procedure causes the screen to
scroll.

Parameters

integer1

integer2

The radix (base) you want DECTPU to use when converting the first
integer parameter to a string. The default radix is 10. The other
allowable values are 8 and 16.

keyword

The keyword whose string representation you want.

string1

Any string. STR now accepts a parameter of type string, so you need not
check the type of the parameter you supply to the built-in.

buffer

The buffer whose contents you want returned as a string.

range

The range whose contents you want returned as a string.

string2

A string that specifies how you want line ends represented. The default
is the null string. You can use string2 only if you specify a
range or buffer as the first parameter. If you want to specify the ON
or OFF keyword but do not want to specify string2, you must
use a comma before the keyword as a placeholder, as follows:

new_string := STR (old_buffer, , ON);

ON, 1

A keyword that directs DECTPU to insert spaces, thus preserving the
white space created by the left margin of each record in the specified
buffer or range. If you specify a buffer or range with a left margin
greater than 1, the ON keyword directs DECTPU to insert a corresponding
number of spaces after the line ends in the resulting string. For
example, if the left margin of the specified lines is 10 and you use
the ON keyword, DECTPU inserts 9 spaces after each line end in the
resulting string. DECTPU does not insert any spaces after line
beginnings that do not contain characters. If the first line of a
buffer or range starts at the left margin, DECTPU inserts spaces before
the text in the first line.

You can use this keyword only if you specify a buffer or range as a
parameter.

OFF, 0

A keyword that directs DECTPU to ignore the left margin setting of the
records in the specified buffer or range. This is the default. For
example, if the left margin of the specified lines is 10 and you use
the OFF keyword, DECTPU does not insert any spaces after the line ends
in the resulting string.

You can use this keyword only if you specify a buffer or range as a
parameter.

Return Value

A string that is the equivalent of the parameter you specify.

Description

The STR procedure returns a string equivalent for an integer, a
keyword, a string, or the contents of a range or buffer. If you use the
first format, STR returns a string representation of an integer or a
keyword. You can then use the variable that contains the returned
string in operations that require string data types. For another method
of generating a string representation of an integer, see the
description of the FAO built-in procedure.

If you use the second format, STR returns a string equivalent for any
string or for the contents of a range or buffer.

Signaled Errors

TPU$_TRUNCATE

WARNING

You specified a buffer or range so large that converting it would
exceed the maximum length for a string. DECTPU has truncated characters
from the returned string.

TPU$_NEEDTOASSIGN

ERROR

STR must appear on the right-hand side of an assignment statement.

TPU$_TOOFEW

ERROR

STR requires at least one argument.

TPU$_TOOMANY

ERROR

STR accepts only two arguments.

TPU$_INVPARAM

ERROR

The argument to STR must be an integer, buffer, string, or range.

TPU$_BADVALUE

ERROR

You specified a value other than 8, 10, or 16 for the radix parameter.

Examples

The following example creates a string that uses the text in the select
range. Line breaks are marked with the string CRLF. The white
space created by the margin is preserved by inserting spaces after the
line breaks.

#1

return_string := STR (SELECT_RANGE, "<CRLF>", ON);

The following example uses the STR built-in procedure to convert the
integer variables v1 and v2 to strings so that your
row and column position can be displayed in the message area:

Parameters

buffer

range

string

integer1

The character position at which the substring starts. The first
character position is 1.

integer2

The number of characters to include in the substring. If you do not
specify this parameter, DECTPU sets the returned string's end point to
the end of the first parameter.

Return Value

A string that represents a substring of a string or range.

Description

The SUBSTR procedure returns a string that represents a substring of a
buffer, range, or string. If you specify a larger number of characters
for integer2 than are present in the substring, only the
characters present are returned in string2. No error is
signaled.

Signaled Errors

TPU$_NEEDTOASSIGN

ERROR

SUBSTR must appear on the right-hand side of an assignment statement.

TPU$_TOOFEW

ERROR

SUBSTR requires three arguments.

TPU$_TOOMANY

ERROR

SUBSTR accepts only three arguments.

TPU$_INVPARAM

ERROR

One of the arguments to SUBSTR is of the wrong type.

TPU$_ARGMISMATCH

ERROR

One of the arguments to SUBSTR is of the wrong type.

TPU$_TRUNCATE

WARNING

You specified a buffer or range so large that returning the requested
substring would exceed the maximum length for a string. DECTPU has
truncated characters from the returned string.

Examples

The following example returns the string "com" in the variable
file_type. The substring starts at the seventh character
position (c) and contains three characters (com). If you use a larger
number for integer2, for example, 7, the variable
file_type still contains "com" and no error is signaled.

#1

file_type := SUBSTR ("login.com", 7, 3)

The following example capitalizes the first character in a string. It
does not affect any other characters in the string. It makes use of the
fact that SUBSTR returns a null string if the second parameter points
past the end of the string.

Format

Parameters

buffer2

A buffer in which one or more characters are to be replaced. You cannot
use the NOT_IN_PLACE keyword if you specify a buffer for the first
parameter.

range2

A range in which one or more characters are to be replaced. You cannot
use the NOT_IN_PLACE keyword if you specify a range for the first
parameter.

string2

A string in which one or more characters are to be replaced. If a
return value is specified, the substitution is performed in the
returned string. If you specify IN_PLACE for the third parameter,
TRANSLATE makes the specified change to the string specified in the
first parameter. If string2 is a constant, IN_PLACE has no
effect.

string3

The string of replacement characters.

string4

The literal characters within the text specified by parameter 1 that
are to be replaced.

IN_PLACE

A keyword that directs DECTPU to make the indicated change in the
buffer, range, or string specified. This is the default.

NOT_IN_PLACE

A keyword that directs DECTPU to leave the specified string unchanged
and return a string that is the result of the specified translation.
You cannot use NOT_IN_PLACE if the first parameter is specified as a
range or buffer. To use NOT_IN_PLACE, you must specify a return value
for TRANSLATE.

Return Values

buffer1

A variable of type buffer that points to the buffer that contains the
modified text, if you specify a buffer for the first parameter. The
variable returned_buffer points to the same buffer pointed to
by the buffer variable specified as the first parameter.

range1

A range that contains the modified text, if you specify a range for the
first parameter. The returned range spans the same text as the range
specified as a parameter, but they are two separate ranges. If you
subsequently change or delete one of the ranges, this has no effect on
the other range.

string1

A string that contains the modified text, when you specify a string for
the first parameter. TRANSLATE can return a string even if you specify
IN_PLACE.

Description

The TRANSLATE procedure substitutes one set of specified characters for
another set. TRANSLATE returns a value for the translated range or
buffer or for the string representation of the translated text.
TRANSLATE is based on the Run-Time Library (RTL) routine STR$TRANSLATE.
For complete information on STR$TRANSLATE, see the OpenVMS RTL String Manipulation (STR$) Manual.

TRANSLATE searches the text specified by the first parameter for the
characters contained in the third parameter. When DECTPU finds the
sequence specified by string3, DECTPU substitutes the first
character in string2 for the first character in
string3, and so forth.

If the translate string, string2, is shorter than the match
string, string3, and the number of matched character positions
is greater than the number of character positions in the translate
string, the translation character is a space.

The IN_PLACE and NOT_IN_PLACE keywords specify whether the source is to
be changed. IN_PLACE means that the source is modified; NOT_IN_PLACE
indicates that the source is not changed.

Signaled Errors

TPU$_TOOFEW

ERROR

TRANSLATE requires three arguments.

TPU$_TOOMANY

ERROR

TRANSLATE accepts no more than three arguments.

TPU$_ARGMISMATCH

ERROR

One of your arguments to TRANSLATE is of the wrong data type.

TPU$_INVPARAM

ERROR

One of your arguments to TRANSLATE is of the wrong data type.

TPU$_NOTMODIFIABLE

WARNING

You cannot translate text in an unmodifiable buffer.

TPU$_CONTROLC

ERROR

You pressed Ctrl/C during the execution of TRANSLATE.

Examples

The following example replaces any lowercase "i" in
second_buffer with an uppercase "I":

#1

TRANSLATE (second_buffer, "I","i")

The following example strips the eighth bit from all characters in the
current buffer. You can use this kind of procedure for reading files
from systems like TOPS--20 (on which the eighth bit is set) without
using the DEC Multinational Character Set.

Format

UNANCHOR

Parameters

None.

Description

The UNANCHOR procedure specifies that the next pattern element may
match anywhere after the previous pattern element. Usually, when a
pattern contains several concatenated or linked pattern elements, the
pattern matches only when the text that matches one particular pattern
element immediately follows the text that matches the previous pattern
element. If UNANCHOR appears between two pattern elements, the text
that matches the second pattern element may appear anywhere after the
text that matches the first pattern element.

Although UNANCHOR behaves much like a built-in, it is actually a
keyword.

For more information on patterns or pattern searching, see the
Guide to the DEC Text Processing Utility.

Signaled Errors

UNANCHOR is a keyword and has no
completion codes.

Examples

The following example creates a pattern that matches any text beginning
with the letter a and ending with the digits 123. Any
amount of text may appear between the a and the 123.