SPFLite - V3.0.24069 2024-03-09

Contents of Article

Why use User Lines ?

Primary command usage of User Lines

Setting the User Line status is repeatable, and what that means

Comparison of features: Excluded Lines vs. User Lines

Special handling of RESET when resetting User Line status

Special handling of co-located label, tag and User state on same line

Examples of USER Lines

Introduction

Conceptually, all data lines exist in one of two states: either they are "U lines" or they are "V lines", where U lines are simply a set of one or more lines of special interest to the user at some given time, and V lines are everything else. 

Essentially, the U/V state of a line is like a bit:  It's on if it's a U line, and off if it's not a U line. 

Not being a U line is the same as being a V line.

Note:  While "U Line" is short for "User line", what does "V line" stand for?  To be honest, not much. The V doesn't have any especially clever meaning, other than simply "not being a U line". The letter "V" was chosen for practical reasons, because the line command V wasn't being used for anything else at the time. We tried to tie-in V with the "V" in the primary command names REVERT and NREVERT, which have abbreviations of VV and NV respectively. That's about as clever as it gets.

A file will ordinarily consist entirely of V lines, which is the default state of a file when no lines have been marked as U lines. You will see the expression "ordinary V lines" throughout this Help documentation, to describe lines that are not marked as U lines. Other that being in one or the other of these U/V states, there is no difference between U and V lines and the data lines you have always worked with. 

When a data line becomes a U line, a | vertical bar character appears in the "gap column" just after the line number. This vertical bar marks the line as being a U line.

The U/V state of a file is persistent if STATE ON is in effect. If STATE OFF is in effect for a file you're working on, and you set any lines in the file to be U lines, they will all revert back to V lines once the file is closed and reopened.

Note:  Because the U/V state of a file affects the state but not the data, just marking and unmarking User Lines does not count as a "change" to the file, and so during an edit, you will not see the modified-marker like Edit * in the lower-left part of the screen. See Saving the Edit STATE for more information.

Why use User Lines ?

Using U lines can make it convenient to perform extended editing tasks that repeatedly target the same given area of interest within a file, in a way that can be easier than using labels, tags or line exclusion.

As seen below, there is a fairly close comparison between User Lines and excluded lines. If you wanted, you could also compare User Lines to tagged lines. Suppose you used a tag of :U for user lines; much of what User Lines offers could also be done with tags. However, there are drawbacks to both these techniques.

Drawbacks of excluded lines

• When lines are excluded, you can't see them. That can be a good thing at times, but not always.
• FIND and CHANGE make excluded lines "pop out". If you don't like that, there are the MX and DX keywords, but that adds complexity, and not all commands support MX and DX, either.
• If an excluded line "pops out" it's not excluded any more, and so if you used excluded/unexcluded to segregate lines into two groups, lines that "popped out" are now "in the other group". Again, that can be a good thing at times, but not always.
• There are SORT issues to consider

Drawbacks of tagged lines

• Tagged lines are powerful, but more complex than excluded lines.
• The TAG command contains many options, and may be intimidating for some.
• When a tag is present in a line (as with labels) it obscures the line number sequence field. If you have many tags on many lines, this could be a bit distracting.
• The tag notation is a little lengthy and hard to type, requiring a : colon as a shifted key to enter it.

Does this mean that User Lines are the answer to everything?  No. Excluded and tagged lines are still needed:

• Excluding lines get lines of lesser interest "out of the way". Often times, that is a good thing.
• The "pop out" action in FIND and CHANGE can reveal strings of special interest; that can be very important when you're trying to find something and you don't know if, or where, it might be.
• Some complex "data mining" actions using TAG and ASSERT can't be easily done any other way.

The User line status is independent of other line characteristics. Because of that, User Lines don't have to be the answer to everything. You can combine User Lines and other techniques, for even more powerful methods of referencing lines. That means that any of these attributes may be applied to a line independently of each other:

• a line can be excluded, or not excluded
• a line can have a label, or not
• a line can have a tag, or not
• a line can be designated as a User line, or not

For example, you may set a group of lines as User Lines, and work on them for a while. Then, when you're done with a particular aspect of your work, you can exclude those User Lines and "get them out of the way", but they are still User Lines, and will remain so if you unexclude them later with a RESET, SHOW or other command.

As with all tools, you have to pick the right one for the right job.

Primary command usage of User Lines

The ULINE, REVERT, NULINE and NREVERT commands allow the "U/V state" of a line to be set, based on the presence or absence of a search string. Reverting a line means to revert its U/V state back to V, the default state of ordinary data lines.

These four commands may be thought of as follows:

• ULINE is like FIND or EXCLUDE
• REVERT is like SHOW 
• NULINE is like NFIND or  NEXCLUDE
• NREVERT is like NSHOW 

Using U and NU is very similar to operating on lines that either are, or are not, excluded, using the keywords X or NX. User lines can be combined with line exclusion, line labels and line tags, if desired. During the design phase, we patterned the U|NU usage on the existing X|NX usage that ISPF and SPFLite users are familiar with. If you'd like an easy-to-remember rule, then just remember that essentially any primary command that takes X or NX will take U or NU. The exceptions to this rule are as follows:

• the commands EXCLUDE, SHOW, NEXCLUDE and NSHOW don't allow X|NX on the command line but do allow U|NU
• the commands ULINE, REVERT, NULINE and NREVERT don't allow U|NU on the command line but do allow X|NX

Why didn't we make the primary command keywords U and V, instead of U and NU, since we just got through saying there are U and V lines, and there are U/UU and V/VV line commands?  That was possible, and we did discuss it, but it wouldn't have followed the X|NX pattern. So, we have the keywords as U and NU because it is the more consistent approach.

It's sort of the same reason why we stuck with X and NX, even though there is a SHOW primary command and an S line command. Why not introduce an S keyword instead of continuing to use NX?  Because that's not how ISPF does it. Same here. We are trying to follow the "spirit" of how ISPF would have done this, if IBM had designed it.

The syntax of the commands ULINE, REVERT, NULINE and NREVERT were patterned after the FIND command. This includes the string search argument, CHAR/WORD/PREFIX/SUFFIX options, color keywords, X|NX and MX|DX. If you are modifying several different sections of your file to be U lines (or reverting them back to V lines), you can exclude them afterwards by using the MX keyword, or keep them excluded if they already are, by using the DX keyword. This can help you organize your work, by getting lines you just marked as U lines "out of the way," so that you can concentrate on other parts of your file. Once you have set all the desired lines, you can unexclude them and begin working on them. See Special handling of RESET when resetting User Line status below, and Working with Excluded Lines for more information.

In addition, primary commands can be restricted to operating on lines that either are, or are not, U lines, using the keywords U or NU.

The commands where U and NU can be specified are as follows:

APPEND, CHANGE (C), COMPRESS (CP), CREATE (CRE), CUT, DELETE (DEL), EXCLUDE (X), FIND (F, FF), FLIP, JOIN, LC, LINE, LOCATE (LOC, L), NDELETE (NDEL), NFIND (NF), NEXCLUDE (NX), NFLIP, NSHOW, PREPEND, PRINT, PTYPE (PT), REPLACE (REP), SC, SHOW, SORT, SPLIT, SUBMIT (SUB), TAG, TC and UC.

See also the U/UU, V/VV and TU/TUU line commands for more information.

Setting the User Line status is repeatable, and what that means

If you use a command like ULINE (UU) or REVERT (VV) over a range of lines, that command is repeatable. That is, if you were to retrieve the command (probably with F12) and run the same command again, it would re-mark, or re-unmark, the same set of lines the same way. That is because the same set of conditions (like search strings) would still hold, and unlike the EXCLUDE and SHOW primary commands, ULINE and REVERT don't change the visibility of those lines. (Recall that these commands are like FIND, which doesn't change the data.)

This property, where you can do the same thing over again, has the peculiar mathematical name of "idempotent", a word which signifies an operation that produces the same results no matter how many additional times you perform it. It is like setting a bit on using in OR operator; if you set on a bit that was already on, it will still have the same value it had before.

In some ways, line exclusion is also repeatable, but not to the extent that User Lines are. For example, you can issue a primary command of EXCLUDE .A .B ALL, and if you re-issue it, the same line range will be excluded (again). This corresponds to a command like ULINE .A .B ALL, which can also be repeated. However, suppose you issue a line command like X3 on line 1; it will exclude lines 1 to 3. If you issue X3 again where line 1 used to be, it now has a placeholder representing 3 lines, so putting X3 there will (again) exclude lines 1 to 3 as a unit and then also exclude lines 4 and 5. So, you get more lines excluded the second time, and thus the action is not repeatable. In contrast, if you put a U3 command on line 1, no matter how many times you do it, it will still only mark lines 1 to 3 as User Lines.

Why bring up this bit of trivia?  Recall the beginning of this article, where we said that the U/V status is like a bit?  If it is, and if setting the "bit" using ULINE is like OR-ing the bit, then you could set various ranges of lines using any combination of ULINE, NULINE and UU line commands, and when you were done, the set of lines marked as U lines would be in an OR relationship.

For example, assuming the file had no existing U lines, if you did this:

ULINE ABC ALL

NULINE DEF ALL

line command U\ on line 10

where would U lines be found?  They would be:

• all line containing ABC
• OR all lines not containing DEF
• OR the first 10 lines of the file

Once you have described this OR relationship, you can use the U or NU keywords to work with those lines from the primary command line. For example, suppose you now want to convert all those lines to upper case:

UC U ALL

Or, suppose you want only those lines written to a a temporary file:

CREATE TEMP.TXT .ZFIRST .ZLAST U

Remember, essentially any command that takes X or NX will also take U or NU. So, you can use the U or non-U status to selectively act on a set of (possibly non-adjacent) lines.

Comparison of features:  Excluded Lines vs. User Lines

Special handling of RESET when resetting User Line status

Long-time ISPF users are accustomed to RESET performing a number of default reset-actions when no options are specified. A plain RESET is commonly used to reset excluded lines, as if RESET X were specified. These default actions can be extended to the new User Line feature. That is, a plain RESET can also revert any User Lines back to ordinary non-User Lines, as if RESET U were specified.

However, since User Lines are a new editing concept, there is no prior experience to form a consensus about how this should best be handled. Some people may want User Lines implicitly reverted, and others might not.

To address this, a plain RESET will revert any existing User Lines back to ordinary non-User Lines, but only if you enable the checkbox on the General Options dialog that says, "Default RESET will revert user line status". As with other settings on this dialog, it is global and applies to all SPFLite edit sessions.

This checkbox is initially disabled.

Special handling of co-located label, tag and User state on same line

When a label and a tag exist on the same line, the "gap column" will display a : colon to remind you of this situation, and there is also a special status line display whenever the cursor is on that line. See Line label and line tag co-location for more information.

It is possible for such a label/tag co-location line to also be a User Line. When this occurs, the : colon in the gap column is replaced by the | vertical bar character. The special notation on the status line remains as in previous versions, displaying the tag name for that line. 

If you revert this line back to a non-User line, using REVERT, NREVERT, RESET U or the V/VV line commands, and make no other changes to this line, the : colon in the gap column will reappear.

Examples of USER Lines

Let's start with a simple test file. Notice there is a missing right parenthesis on line 2.

The goal will be to mark the first three lines as User Lines. There are a number of ways this could be done:

• U3 line command on line 1
• U\ line command on line 3
• UU .1 .3 primary command

But suppose we are looking for some particular condition to mark. In this case, 'words' of three letters that start with a left parenthesis, where the words are in lower case. We can do this with a UU command using a Picture. 

(Note that parentheses are not special Picture characters, and don't need to be escaped. If you needed to use some special characters, you can always put a \ backslash in front of them, to have them treated as ordinary data.)

This will mark the desired lines, and then report on the number of lines affected:

Now, noting that 3 lines were marked, suppose we knew (or suspected) that there might be some unmatched parentheses somewhere in the file. We could see if that condition existed in the marked User Lines by doing a FIND with a U keyword:

The U keyword directs the FIND command to only look at lines marked as User Lines, which in this case are lines 1-3, as seen by the | vertical bar on those lines. Result:

The FIND message confirms that the unmatched parentheses are somewhere in the User Line area. If you wanted to successively look at every U line that had a left parenthesis, to visually inspect which didn't have a right parenthesis, you could issue a FIND '(' U and then repeat that manually with F5.

But, suppose you're in a hurry, and don't want to do all that manual inspection. You could exclude all the lines, and then find all User Lines which did not have a right parenthesis:

Sure enough, once you do that, the only line left displayed is the one with the missing right parenthesis on line 2:

What's nice about User Lines is that, since they act independently of line exclusion, you can RESET the file and unexclude (or re-exclude) everything, and perform these tests all over again, or run other ones. When you do, all of your User Line marks remain undisturbed.

Remember that a plain RESET command either will, or will not, clear the User Line marks from your file, depending on the General Options RESET checkbox described above.

Created with the Personal Edition of HelpNDoc: Make Documentation a Breeze with HelpNDoc's Clean and Efficient User Interface