Syntax


PREPEND

string

[ start-column [ end-column ] ]

[ line-control-range ]

[ color-selection-criteria ]

[ X | NX ]

[ U | NU ]

[ ALL ]

[ TOP ]


Operands


string

The string option is required, and can only be a simple string. i.e. No Picture strings or Regular expression strings. This string will be prepended to the start of every line specified by the other PREPEND operands.

start-column

Left column of a range (with end-column) within which the search-string value must be found. If no end-column operand, then the search-string operand must be found starting in start-col.

end-column

Right column of a range (with start-column) within which the search-string value must be found

line-control-range

The range of lines which are to be processed by the command. Line control ranges provide a powerful tool to customize the range of lines to be processed. The full syntax and allowable operands which make up a line control range are discussed in "Line Control Range Specification". Refer to that section of the documentation for details.

color-selection-criteria

A request for selection based on the highlight color of the search-string. Color requests provide another powerful tool to control search selection. The full syntax and allowable operands which make up a color-selection-criteria  are discussed in "Color Selection Criteria Specification". Refer to that section of the documentation for details.

ALL

All lines in the line range are processed. 

X | NX

Specifies a subset of the line range to be processed. X requests only excluded lines are to be processed, NX requests only non-excluded lines are to be processed. If neither X or NX are specified, all lines in the range will be eligible to be processed.

U | NU

Specifies a subset of the line range to be processed. U requests only User lines are to be examined, NU requests only non-User lines are to be examined. If neither U or NU are specified, all lines in the range will be examined.

TOP

Normally, at the completion of the command, the first, or only, line processed is highlighted (if it is on the current screen) or the screen is scrolled to the 2nd screen line (as ISPF does) if the line is not on the current screen. If TOP is coded, then the line is always positioned as the top line of the screen, regardless of its current location.


Description


PREPEND adds the specified string to the beginning of all lines specified by the line-control-range, X/NX and ALL operands. The string you PREPEND will appear starting in column 1 of every effected line.


Example uses of the PREPEND command


To prepend the string "(." to all excluded lines.


PREPEND '(.' ALL X


To prepend '---' to lines 10 through 20 of the file.


PREPEND '---' .10 .20


To prepend '[135]' to all non-excluded lines in the line range 3 through 200.


PREPEND '[135]' NX .3 .200


Comparison to CHANGE command


You can modify lines using CHANGE with pictures, in a manner similar to PREPEND. 


If you wanted to rewrite the first example of  PREPEND '(.' ALL X   as a CHANGE, it would look like this:


CHANGE P'=' F'(.='(.' ALL 1 1 X


The difference is that the CHANGE command will not work for zero-length lines; the search for  P'='  in column 1 fails on such lines. So, no zero-length lines would get modified. However, PREPEND inserts the string on every line, including zero-length lines. Depending on how you want to handle zero-length lines, both approaches can be useful.


Comparison to Power Typing


You can prepend text to a given line range by using the PTYPE command, setting Insert Mode on, moving the cursor to column 1, and typing the characters to be inserted at column 1. Power Typing has many powerful capabilities, but if you only wish to insert text at the beginning of lines, PREPEND may be simpler to use, and because it is a complete primary command, it can be brought back with the RETRIEVE commands and run again.

Created with the Personal Edition of HelpNDoc: Effortlessly Spot and Fix Problems in Your Documentation with HelpNDoc's Project Analyzer