SPFLite - V3.0.24069 2024-03-09

Contents of Article

Dual-use and comparable commands

Fundamentals of the LINE primary command

Applications of the LINE primary command

Specifying the line-command operand

Specifying a block-mode line-command operand

LINE provides access to excluded lines

Using Labels and Tags with the LINE Command

Limitations of T/TT line command and LINE primary command

LINE primary command examples

Introduction

The LINE primary command allows you to apply a line command to one or more lines, based on a standard line-range operand. The command syntax is described in LINE - Apply Line Command.

This is a somewhat unusual concept, not present in ISPF or in SPFLite until now, and is best explained by example - so we provide several to help you to understand it and get most out of this new feature. 

You can go directly to the examples here.

Note: Every effort was made to carefully design and implement it, but because this a novel editing concept (even for us, it must be admitted), the way in which this works may be subject to change if it turns out any of our basic assumptions need to be adjusted. We invite all SPFLite users to try this and give us your suggestions and feedback on how well you do or don't like it. This a very cool and promising feature, but it's also a work in progress, so stay with us as we go through the learning curve together.

For you mathematicians out there, note that the LINE primary command is a function that applies other functions (line-commands) to your data, which could be termed a lambda function. For everyone else, it's just a cool feature, so keep reading.

By the way, since LINE is a primary command, and commands that go into the sequence area of lines are "line commands", the terminology could get a little confusing if we're not careful. To avoid that, we will always refer to LINE as "the LINE primary command" or "the LINE facility" and continue to call commands in the sequence area simply as "line commands". What we won't do is refer to "the LINE command".

Dual-use and comparable commands

Even though the LINE primary command is new, if you are a long-time SPFLite user, you may already have taken advantage of a similar capability. Consider the LC command, to convert data to lower case. This command exists in two forms, as a line-mode LC[n] or block-mode LCC line command, and as a primary command having a syntax of:

LC [ line-control-range ]  [ X | NX | ALL ]  [ MX | DX ]

Because you have the ability to use LC in both line-command form and primary-command form, LC could be thought of as a "dual-use" command. It is as if you had a "primary-command version of a line-command", or vice-versa.

There are only a limited number of commands that are dual-use. (A few of these might be termed "comparable" dual-use commands, like the line command D and the primary command DELETE. Both have the comparable function of deleting lines, but they are spelled differently.)  

These dual-use commands are:

Even though it might seem like the LC line command and the LC primary command are "the same" (because both perform lower-case conversion), they are in fact completely different commands in different parts of SPFLite and were implemented independently. They just happen to be spelled the same.

Fundamentals of the LINE primary command

The LINE facility is different. In effect, the LINE primary command is used to "deposit" line commands into the sequence areas of one or more data lines, at which point those line commands are applied, as if you had typed them in yourself and pressed Enter. When that line command is executed, it's not a "primary-command version of a line-command". It's a real line command, and it works like the real thing.

That is, suppose you have a line labeled .ABC and you want to convert that line to lower case. You have three choices:

• Type an LC line command on the line labeled .ABC and press Enter.
• On the primary command line, type the command LC .ABC and press Enter.
• Use the LINE primary command to apply an LC line command to the line. Referring to the example above, this would this be done with the primary command LINE LC .ABC. 

The difference between LC .ABC and LINE LC .ABC is:

• LC .ABC directs all of its activity from the primary command line, whereas,

• LINE LC .ABC is a request to apply the LC line command on line .ABC. When LINE LC .ABC is executed, a real LC line command is executed.

Note: Just to be clear, this discussion about LC is simply to help you understand the process. Even though you could do it, you wouldn't normally need to say LINE LC, since you already have an LC primary command available.

However, if you were to use any of the extra operands of LINE, like FIRST, LAST, X|NX, and/or a multi-line line range using labels or tags, there are some reasons to consider using a command like LINE LC.

Applications of the LINE primary command

If you read no further, you might conclude that the LINE primary command wasn't all that useful. After all, if it acts just like typing a regular line command, why not just type a real one and be done with it?  What is the advantage to using the LINE facility?  It was created to address the following situations:

• As a way to apply a given line command to a range of lines, including multiple, non-contiguous lines specified by line label ranges, line tags and/or by their X|NX exclusion status. Applying the LINE facility to multiple data lines is its most powerful feature, and is likely to be the most important use for the LINE primary command.

• As a means to apply line-commands to a file from a command macro, which otherwise would have no way to do this.

• To provide additional capability to keyboard macros.

• And, to provide a critical feature needed for the SPFLite programmable macro facility.

Specifying the line-command operand

The line-command operand may be a quoted or unquoted string.

The operands of the LINE primary command may be specified in any order. We show the line-command operand in the examples as immediately following the LINE  primary command keyword just as a matter of style and convention.

When the line-command operand is a simple alphabetic or alphanumeric string, like R or R2, it is not necessary to quote it. Either of these will work:

       LINE R .123

       LINE 'R' .123

You can (surprisingly) even use the "graphic" shift commands without quoting them. Either of these will work:

       LINE )4 .123

       LINE ')4' .123

However, if you try to use a line-command operand that overlaps the remaining syntax of the LINE primary command, you will run into problems. The problem areas are as follows:

• A line-command operand of X will be confused with the X|NX option of the LINE primary command. If you try something like LINE X .123 because you wanted to put an X on line 123, you will get an error message, "Missing/invalid line command". To get around this, you will have to quote the line-command operand as LINE 'X' .123.

• If you attempt to use the LINE primary command to place a label into a line, it will be confused with a label that is part of the line-range operand. If you try something like LINE .ABC .123 because you wanted to put a label .ABC on line 123, you will again get an error message, "Missing/invalid line command". To get around this, you will have to quote the line-command operand as LINE '.ABC' .123.

• If you attempt to use the LINE primary command to place a tag into a line, it will be confused with a tag that is part of the line-range operand. If you try something like LINE :T .123 because you wanted to put a tag :T on line 123, you will get an error message, "Invalid tag operand". To get around this, you will have to quote the line-command operand as LINE ':T' .123.

If you don't want to think about it, you can just quote all line-commands. But, remember to at least quote the X if it's a line-command operand. If you are using and X to select just excluded lines as part of the line-range, then don't quote it.

Note: The LINE primary command operands FIRST, LAST, ALL and NX should never be quoted, because these cannot be line-commands.

Note: Would you ever have an 'X' in quotes and an unquoted X in the same LINE primary command?  You could, but, there's no need for it, because you would be putting X line-commands on lines that were already excluded. While a command like LINE 'X' X .123 .456 is not useful, you could use X with a line count, like LINE 'X3' X .123 .456. 

You can also use the block mode XX line command with LINE primary command. The main thing is, if it makes sense to do it manually, it should make sense to do it with the LINE primary command.

If the line-command operand is a quoted string of a blank, it will erase a label or tag that exists on that line. (You can't use a '' zero-length string to do this; there must be at least one blank character in the string.) For example,

       LINE '.ABC' .123

will place label .ABC on line 123, and

       LINE ' ' .123

will remove that label. You may use the forms

 

       LINE '..ABC' .123

       LINE '::DEF' .123

 

to 'toggle' a line label or line tag on a line, and you may use the forms

 

       LINE '.' .123

       LINE ':' .123

 

to specifically remove either a line label or line tag on a line, in cases where both coexist on the same line. In other words, it works just like you could do with a keyboard macro.

When you apply the LINE facility to a line that already has a label or tag, the label or tag will not be disturbed. But if you have a pending command, the label or tag will be 'concealed' until the operation is completed, and then it will be redisplayed. This is the same as what happens manually.

Specifying a block-mode line-command operand

You are allowed to use the LINE primary command to place a block-mode line-command into a line. For example, the following is valid:

       LINE CC .123

What happens when you do this?  Basically, the same thing that would happen if you did this manually. You will see the CC line command sitting in the sequence area of line 123 when this is performed.

Depending on whether there is another CC and/or A/B command somewhere in the file, SPFLite will report the situation with a message like Pending command(s), or it will perform the command and then clear any messages if "all the pieces are in place". If you tried to put too many block-mode line-commands into the file, such as with a command like,

       LINE CC .1 .10 ALL

you will get a message, Illogical line command grouping, because it wouldn't make sense to have ten pending CC commands at the same time. The point is, SPFLite will do the same thing it would if you were typing everything in manually.

LINE provides access to excluded lines

Normally, when a block of lines are excluded, you are limited as to what you can do to those lines using line commands. You can do things like delete, repeat, shift, and copy, using a line-mode command on the excluded-line placeholder, but these actions are applied to every line in the excluded region. You can't pick and choose which lines within that region are affected.

With the LINE primary command, this changes. Suppose you have lines 1 to 100 excluded, and you want to delete line 40, then repeat line 20, but you also want the rest of the lines to remain excluded. How would you do it?  The LINE primary command provides you line-command access to those excluded lines. Here's an example of how you could do it.

EXCLUDE .1 .100 ALL

LINE D .40

LINE R .20

At this point, you will still have 100 excluded lines, and you have modified some of the data within the excluded region without anything 'popping out'. Try this test yourself - then, unexclude the file with a RESET primary command and see what you have. 

This kind of capability never existing in SPFLite before, and it opens up many intriguing possibilities. Feel free to experiment. If you happen upon some novel application of the LINE primary command, we invite your feedback on the SPFLite web site. If you have a good idea, we could include it in upcoming revisions to the Help document.

Using Labels and Tags with the LINE Command

You can manage line labels and line tags using the LINE primary command. For example, to put a label of .ABC on line 10, you can issue the command:

 

LINE '.ABC' .10 

 

Remember to quote the label, because in this example, the first operand '.ABC' is what goes into the sequence area, and the second operand .10 is where the first operand is placed.

When doing a normal edit, there is usually no need to do such a thing; you would just put the label on the line directly. However, when run a programmable macro the LINE primary command is the only way to do this. You would need to 'wrap' the LINE primary command in an SPF_CMD function call in your .MACRO file, like this:

 

SPF_CMD ("LINE '.ABC' .10") 

It is possible to set, clear and toggle both line labels and line tags from the LINE primary command. The possible options are as follows:

LINE '.label'           -- Enter label into sequence area

LINE '..label'          -- Toggle label; enter label if no label present, 

                        -- else clear any label that is present

LINE '.'                -- Clear any label that may be present

LINE '..'               -- Clear any label that may be present; same as LINE '.'

LINE ':tag'             -- Enter tag into sequence area

LINE '::tag'            -- Toggle tag; enter tag if no tag present,  

                        -- else clear any tag that is present

LINE ':'                -- Clear any tag that may be present

LINE '::'               -- Clear any tag that may be present; same as LINE ':'

See Special Line Commands in Using the KEYMAP Dialog for more information on performing these same actions within a KEYMAP definition.

 

Limitations of T/TT line command and LINE primary command

The T/TT line command can be used by the LINE primary command, to apply T/TT to one or more lines. However, when T is applied to more than one line, each individual T is applied to each line one at a time. The way that T/TT operates, only a single, contiguous block of highlighted data may exist as any given time,  So, if you attempted to issue a command like LINE T .11 .13 ALL, only line 13 will be highlighted. If you try to manually highlight line 11 with a T, then line 12, then line 13, you will see how and why it works this way.

 

LINE Command Examples

 

 

LINE Example 1: Insert blanks lines

LINE N .1 .3 is used to insert a blank line after the first 3 lines of the file.

Result:

  

  

LINE Example 2: Repeating lines

LINE R .4 .6  is used to individually repeat 3 lines of the file. Note that this could not be done with a conventional RR block-mode line command.

Result:

 

 

LINE Example 3: Shifting tagged lines

LINE ] :M ALL is used to shift all lines with line tag :M on them.

Result:

 

 

Created with the Personal Edition of HelpNDoc: Effortlessly Convert Your Word Doc to an eBook: A Step-by-Step Guide