Syntax


CUT can be used in a normal Edit session, as well as in File Manager. The operands are similar, but there are some differences


CUT 

(File Manager)

[ CB-name ]

[ REPLACE/REP | NEW ]

[ APPEND/ADD ]

[ RAW ]

CUT

(Edit session)

[ CB-name ]

[ line-control-range ]

[ ALL ]

[ search-string ]     (See special Note below)

[ start-column [ end-column ] ]

[ color-selection-criteria ]

[ PREFIX | SUFFIX | WORD | CHAR ]

[ C ] [ Q ] [ T ]

[ X | NX ]

[ U | NU ]

[ DELETE | DEL ]

[ REPLACE/REP | NEW ]

[ APPEND/ADD ]

[ RAW ]


Operands


CB-name

The name of a Named Private Clipboard. If omitted, the standard Windows clipboard is used. If you use a private name beginning with an Underscore "_", the clipboard will be treated as a temporary clipboard and will be deleted from the CLIP folder after two days.   Using temporary clipboard names helps prevent the \CLIP folder from storing Clip data long after it is still useful.

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.

ALL

Note: When optional search criteria are specified,  ALL is assumed, but you may optionally code it anyway.  ALL is only required when NO operands are specified AND no line-range has been marked.

search-string

A string to further filter what lines you desire to be CUT. You may use any of the available string types (normal, Picture, RegEx etc) that are avalable in a FIND command.


Special Note: the search string, even if a simple string like ABC MUST be enclosed in quotes.  e.g. "ABC" This is to prevent it being treated as the CB-Name operand.

start-col 

end-col

These column numbers can be used to further restrict where search-string is allowed to occur.

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.

PREFIX

Locates search-string at the beginning of a word.

SUFFIX

Locates search-string at the end of a word.

WORD

Locates search-string when it is delimited on both sides by blanks or other non-Word characters

CHAR

Locates search-string regardless of what precedes or follows it

C

Q

T

C         - Locate the search string within a defined Comment string.

Q        - Locate the search string within a defined Quoted literal string.

T        - Locate the search string within plain text (i.e. Not in a Comment or Quoted string.

You may enter more than 1 of C Q or T to customize the selection. They are tested in an OR relationship.


These operands require a valid Profile with Colorization active.

X | NX

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

U | NU

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

DELETE | DEL

Requests that the lines selected for CUT be deleted following the operation.

REPLACE | REP

The data selected by CUT will be placed in the clipboard and will replace any existing data already present. As noted, REPLACE is the default, and is provided for ISPF compatibility. Most users will simply omit REPLACE.

NEW

If NEW is specified and the CUT is directed to a named clipboard, it requests a verification that the named clipboard does not already exist.  If it does exist, you will be prompted for permission to over-write the existing file.

APPEND | ADD

The data selected by CUT will be added to the end of any existing data already in the clipboard.


Description


CUT command in File Manager Differences


The CUT command in File Manager has many similarities to the Edit mode CUT command, but also some significant differences.

      • The Line-Control range, ALL, X/NX, U/NU and DELETE options are not supported.
      • The data copied to the clipboard is the full file path, enclosed in Double-Quotes. (Not the contents of the file)
      • Selected lines must be specified via C / CC / Cnn line commands, there are no selection criteria available as operands to the CUT command


In an EDIT session, CUT saves copies of lines from an edit session to the Windows clipboard, or to a Named Private Clipboard, for later retrieval by the PASTE command or any other Windows application which handles Text-formatted clipboard entries. 


The optional APPEND operand indicates that you wish the selected data to be appended to the current clipboard contents. Without the APPEND operand the clipboard is cleared of any current contents before adding the selected lines. 


See also information on CLIP mode, and Named Private Clipboards, in Windows Clipboard, Cut and Paste.


Note: The CUT command normally copies data to the clipboard (except when M/MM blocks are used, or the DELETE operand; see below). In general, there is no subsequent deletion of text, as is commonly done in the "cut" function of many word-processing programs. The command name CUT adheres to the IBM ISPF naming convention for this command, even if it is a bit "inaccurate" of a term. IBM decided on the command name CUT for ISPF a long time ago, before "cut" and "copy" had the more precise, commonly understood meanings they have today.


The CUT command will do both cutting and copying actions. If the line range is defined by a C/CC block, or by any type of line-control-range operand on the primary command line, a copy operation takes place. If the line range is defined by an M/MM block, or the DELETE/DEL operand is specified, a cut operation takes place. 

Bear in mind that the COPY primary command is used for copying outside files into the current edit session, and has nothing to do with the clipboard. To copy from the clipboard, the PASTE command is required.


Specifying the Data to CUT


Two methods of specifying the line range of the selected data are possible.


    • The first is the 'classic' SPF method of specifying line numbers as operands to the CUT command. You have the full range of options allowed by SPFLite's extended line-control-range operands. 


    • Or, the lines may be marked by C/CC or M/MM  line commands. Depending on whether the X or NX operands are specified, the data CUT will be the entire contents of the specified line range if these operands are omitted, or the specified subset (X or NX) if the operands are specified.


The CUT command also provides for selection based on the contents of the data line. This search ability is similar to what is provided by FIND/CHANGE.  It can be used in conjunction with a specified lne range, or if no line-range is specified it assumes all lines are to be searched.


The lines are copied from the edit session to the clipboard when the C or CC line commands are used, and are "moved" from the edit session to the clipboard when the M or MM line commands are used (or the DELETE operand). Moving the lines means that the data on those lines is copied to the clipboard, and then those lines are deleted. 


As noted above, using M/MM automatically performs a true "cut" operation that deletes data afterwards, while defining your line range any other way, such as by using a C/CC block or a line-control-range command-line operand, performs a "copy to the clipboard" operation, analogous to how a Ctrl-C key works in most text editors. A DELETE operand will however always cause the selected lines to be deleted.


Using Raw Mode Copying


You can copy data in what is termed Raw Mode. Raw mode copy means that there are no End of Line terminators inserted into the copied text. So, when you copy text that encompasses more than one line, all the text from all of the lines are effectively glued together in one long character string. This action happens under the following cases:


    • CUT primary command with RAW keyword




When you copy text in Raw Mode, you can then go outside of SPFLite and paste the text thus copied as if were a single line, for example, into a Notepad session. By doing this, you would be able to perform a type of conversion from the kind of individual lines that SPFLite edits to text that may wrap across multiple lines, as editors such as Notepad commonly deal with.


Mapping the CUT and PASTE primary commands


Because the CUT and PASTE primary commands perform a line-oriented copying and pasting of data, similar to how Ctrl-C and Ctrl-V perform a text-oriented copying and pasting of data, many users will want to create key mappings for the CUT and PASTE commands.


In order to be of the most benefit, you may wish to define these mappings so that the current cursor location is saved and restored, so that its location doesn't "jump around" as SPFLite processes these commands.


Here are some suggested key mappings using Alt-C and Alt-V you may wish to try:


Copying lines of text to the clipboard: Use C/CC or M/MM to define the line range first:


Map Alt-C to:        (SaveCursor)(Home)[CUT](Enter)(RestoreCursor)


Pasting lines of text from the keyboard: The key mapping inserts an A line command for you on the current line:


Map Alt-V to:        (SaveCursor)(LineNo)[A](Home)[Paste](Enter)(RestoreCursor)

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation