Working with User lines

Contents of Article


Introduction

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



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



Drawbacks of tagged lines



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



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:



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:




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:



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/SS 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:



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.



By the way, if that CREATE command seems a little long, it's because U doesn't imply a line range by itself, so we have to give it one.  If you do this frequently, you may want to create a SET symbol to shorten it:


       SET ALL = ".ZFIRST .ZLAST"


Then the command becomes (also using the short form of the command itself):


       CRE TEMP.TXT =ALL U


If it turns out that dealing with "all U lines" is something you do a lot, you could make this even shorter:


       SET U = ".ZFIRST .ZLAST U"


and then


       CRE TEMP.TXT =U


Creating SET symbols can be useful, but it's best to limit them to things you do all the time, to avoid creating so many you start forgetting what you have defined or how to use them.




Comparison of features:  Excluded Lines vs. User Lines


Feature of Excluded Lines

Feature of User Lines



Primary command EXCLUDE (X)

Primary command ULINE (UU)

Primary command NEXCLUDE (NX)

Primary command NULINE (NU)

Primary command SHOW

Primary command REVERT (VV)

Primary command NSHOW

Primary command NREVERT (NV)



Primary command HIDE

No corresponding primary command for User Lines



Primary command option X

Primary command option U

Primary command option NX

Primary command option NU

Primary command options MX and DX

No corresponding primary command options for User Lines



Line command X

Line command U

Block-mode line command XX

Block-mode line command UU

Line command S

Line command V

Block-mode line command SS

Block-mode line command VV

Line command TX

Line command TU

Block-mode line command TXX

Block-mode line command TUU



LOCATE ALL type will unexclude lines

LOCATE ALL U will unexclude User Lines.

There is presently no corresponding LOCATE option to find lines of a certain type and then alter their U/V state.

LOCATE ALL type MX will exclude lines

LOCATE ALL U MX will exclude User Lines.

There is presently no corresponding LOCATE option to find lines of a certain type and then alter their U/V state.



Line command F shows first n excluded lines

Line command of Vn is comparable to Fn, provided that the next n lines are not excluded

Line command L shows last n excluded lines

No corresponding line command

Line command SI shows indentation level

No corresponding line command



Post-exclude modifier -

No corresponding line command option for User Lines

Post-unexclude modifier +

No corresponding line command option for User Lines



STATE ON retains excluded lines

STATE ON retains User Lines

HIDE conceals excluded lines

No corresponding feature, unless also excluded

Excluded lines disappear

User Lines remain visible unless also excluded

Excluded lines represented by a "placeholder" line

User Lines represented by a | vertical mark in gap column

Excluded areas vary in size; affect line commands

No corresponding issues

FIND and CHANGE will make excluded lines appear

FIND and CHANGE do not alter User Line status



FIND X DX can position cursor on hidden lines

No corresponding issue for User Lines

CHANGE X DX can position cursor on hidden lines

No corresponding issue for User Lines

SORT X requires DX for ISPF compatibility

No corresponding issue for User Lines; SORT U allowed

Plain RESET implies RESET X

Plain RESET implies RESET U but only if enabled (see below)



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


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:



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: Easily create EPub books