NOTE and xNOTE Lines
Contents of Article
Line commands that can be used on =NOTE> lines
Line commands that cannot be used on =NOTE> lines
Managing the exclusion status of NOTE or xNOTE lines
Deletion of NOTE or xNOTE lines
Introduction
SPFLite has the ability to insert NOTE lines into data files. A note line is a line of text containing any desired user comments. NOTE lines are not part of the data file per se, and do not have line numbers. Other applications that read the data file will see only the data, and not the note lines.
You can also insert xNOTE lines. An xNOTE is basically the same as a NOTE, but you can use any letter from A to Y to add any of these additional note types into your file, from ANOTE to YNOTE. The last three xNOTE lines (WNOTE, XNOTE and YNOTE) are treated as temporary, and will not be saved and restored by STATE processing.
It is expected that a primary use of xNOTE lines may be in concert with user-written programmable macros, to insert diagnostic lines into an edit file. For example, various xNOTE types could be used for varying levels of error severity (such as Advisory, Information, Warning, Error, Severe and Fatal), where a suitable letter like A, I, W, E, S or F would replace the "x" in xNOTE. SPFLite does not provide or distribute such macros; you would have to write them yourself.
What can notes be used for? A user could embed notes in a large file to help them keep track of the progress of an extensive editing task. A library of ‘models' or ‘prototypes' could be created to document common programming tasks. For example, a library of Windows API calls could contain prototypes of calling sequences that included instructions on how to use them; the instructions would be stored as notes. A NOTE line could be used as a bookmark, somewhat like a label or tag could be used, but a NOTE can provide more information that a label or tag does.
Users of IBM ISPF should be aware the its use of notes is different than in SPFLite. ISPF can have note lines in Dialog Development Models, and can use NOTE ON and NOTE OFF as primary commands. SPFLite does not implement the NOTE primary command, nor Dialog Development Models. However, in SPFLite, if you COPY a file containing persistent NOTE lines into another file, the NOTE lines will be copied as well, an action comparable to copying a Model file in ISPF that contained notes.
See the discussion NOTE lines and the clipboard below for the considerations that must be taken into account if you want to attempt such a thing.
Notes are stored in the same area that STATE information is held (like labels and tags). This means that STATE ON must be in effect to store notes. Remember, WNOTE, XNOTE and YNOTE are temporary and are not saved by STATE. You can create notes with STATE OFF, but they will not be retained between sessions.
See Saving the Edit STATE for more information about STATE processing.
A NOTE line is marked by a =NOTE> marker in the sequence area.
An xNOTE line is marked by an XNOTE> marker in the sequence area, where "X" is some letter from A to Y.
If the sequence area width has been reduced to 5, there is not enough room for the full-size =NOTE>/xNOTE> markers. Instead, shorter markers are displayed, where =NOTE> becomes =##=> and XNOTE> becomes =X#=>.
Any number of note lines may be placed into a file, and they may appear at any desired location(s) within the file.
Types of NOTE lines
SPFLite supports the creation of different types of NOTE lines. Creation of different NOTE lines is accomplished by prefixing the NOTE command with a letter from A to Y, such as CNOTE, MNOTE or XNOTE.
The xNOTE type ZNOTE is reserved; you cannot enter ZNOTE as a line command. Instead, ZNOTE is used only on the primary command line, to generically reference xNOTE lines of any type (from ANOTE to YNOTE). ZNOTE never refers to "plain" NOTE lines, but only the "extended" xNOTE types. You can use the ZNOTE keyword on LOCATE and DELETE primary commands.
New, blank NOTE or xNOTE lines may be created by the NOTE or xNOTE line commands, which have the following command syntax:
NOTEn
or
xNOTEn
The n value is used to insert from 1 to 99 blank note lines for NOTE, and 1 to 9 blank note lines for xNOTE. If omitted or specified as 0 or 00, one line is inserted. The note line(s) are inserted after the point the NOTE or xNOTE command is entered on.
If you need more NOTE or xNOTE lines than the n value allows, you can insert one NOTE/xNOTE line, and then use the R line command on the NOTE/xNOTE line with a suitable n value to create as many of these lines as you need. Line commands like R don't always apply to "special" lines, but for R it is permitted.
After the NOTE or xNOTE line(s) are inserted, they are initially blank. You can move the cursor or mouse into any NOTE or xNOTE line and edit its content as desired.
NOTE or xNOTE lines can be moved, copied and deleted within the edit file. They are ignored for nearly all other purposes.
Because NOTE or xNOTE lines are not data lines, most primary commands are not applied to NOTE or xNOTE lines. For example, FIND and CHANGE do not apply to NOTE or xNOTE lines.
If it is necessary to find some specific text in a NOTE or xNOTE line, one approach would be to save the file under a different name, convert all the NOTE or xNOTE lines into data lines using MD/MDD, then do a search of the file for the desired text.
(before):
000010 line ten
NOTE line eleven
000012 line twelve
After NOTE line is inserted:
000010 line ten
000011 line eleven
=NOTE>
000012 line twelve
After NOTE line is updated by user:
000010 line ten
000011 line eleven
=NOTE> THIS IS A USER-ENTERED COMMENT LINE
000012 line twelve
For special NOTE lines
(before):
000010 line ten
MNOTE line eleven
000012 line twelve
After MNOTE line is inserted:
000010 line ten
000011 line eleven
MNOTE>
000012 line twelve
After MNOTE line is updated by user:
000010 line ten
000011 line eleven
MNOTE> THIS IS A USER-ENTERED COMMENT LINE
000012 line twelve
The MD line command (MDD or MDMD for blocks) will convert a =NOTE> or xNOTE> line into a data line.
The MN line command (MNN or MNMN for blocks) will convert a data line into a =NOTE> line. In addition, ‘special' lines that are displayed by the PROFILE command can also be converted into a normal data line. Such lines include =PROF>, =WORD>, =MARK>, =TABS>, =COLS> and =BNDS>.
Note that the MN command always converts lines into "plain" NOTE> lines There is no provision for MN to create any type of extended xNOTE> lines.
The usual n line count and / and \ modifiers are permitted.
Example:
Before:
000010 line ten
000011 line eleven
=NOTE> THIS IS A USER-ENTERED COMMENT LINE
000012 line twelve
MD and MN commands applied:
MN line ten
000011 line eleven
MD THIS IS A USER-ENTERED COMMENT LINE
000012 line twelve
After:
=NOTE> line ten
000010 line eleven
000011 THIS IS A USER-ENTERED COMMENT LINE
000012 line twelve
Line commands that can be used on =NOTE> or =xNOTE> lines
A
B
BNDS
C/CC
COLS
D/DD
F
H/HH
I
L
LC/LCC, UC/UCC, SC/SCC, TC/TCC
M/MM
MARK
N
R/RR
S
Shift commands
W/WW
WORD
X/XX
Line commands that cannot be used on =NOTE> or =xNOTE> lines
AA
BB
G/GG
J/JJ
O
OR
PL/PLL
T/TT
TB/TBB
TF/TFF
TG/TGG
TJ/TJJ
TL/TLL
TM/TMM
TR/TRR
TS
The LOCATE command has been extended to locate lines of type NOTE, so now the command LOCATE NOTE is available. The NOT option is allowed as well, so non-note lines can be found with LOCATE NOT NOTE. All other LOCATE features are available as well.
If you are using extended xNOTE lines, they can be searched for specifically. e.g. LOCATE MNOTE or LOCATE TNOTE.
When you use a LOCATE command in the form of LOCATE ZNOTE it means to generically find any xNOTE line of any kind, from ANOTE to YNOTE. You cannot locate xNOTE lines of type Z using a keyword of ZNOTE because you are not allowed to define such lines. The keyword ZNOTE is allowed only on the primary command line, not as a line command.
When a file (or any portion thereof) containing note lines is written to disk using SAVE, CREATE or REPLACE, the notes are written as well. For this to happen, the file type of the file being saved must be known to SPFLite; there must be an existing PROFILE for that file type, and that PROFILE must have STATE ON enabled. If that is not the case, the file will be saved without the notes; that is, the NOTE or xNOTE lines will be discarded. When a file has a profile with STATE ON in effect, such a file is a note-enabled file type. When a file with notes is saved to a note-enabled file type, any note lines are exported to the saved file.
When an external file that has a note-enabled file type is copied into a file that is also noted-enabled, and the external file contains NOTE or xNOTE lines, those NOTE or xNOTE lines are imported into the edit file. The imported NOTE or xNOTE line(s) retain the same relative position(s) they have in the external file.
Managing the exclusion status of NOTE or xNOTE lines
NOTE and xNOTE lines may be made individually excluded or unexcluded using the X/XX and S line commands. Additionally, you can unexclude all excluded NOTE and xNOTE lines by using RESET or RESET X.
Deletion of NOTE or xNOTE lines
A special extension to the DELETE command allows for mass-deletion of all note lines. The syntax is:
DELETE NOTE
Note that DELETE NOTE does not permit other DELETE keywords to be used. In particular, you cannot issue a command like DELETE NOTE ALL or DELETE xNOTE ALL. Within the specified line-control range, or within the entire edit file, all notes are deleted; the "ALL" is implied but cannot be used on these commands.
The keyword NOTE cannot be specified as NOTES.
If using special xNOTE lines, you may specify a unique note type, like DELETE CNOTE, to delete just one type of note, or you can user the reserved ZNOTE name. A command of the form DELETE ZNOTE will delete all xNOTE lines of any kind, from ANOTE to YNOTE, but will not delete "plain" NOTE lines. As noted elsewhere, the keyword ZNOTE is a generic reference to all xNOTE lines; you cannot literally use a line command of ZNOTE on a data line.
Note lines may be made individually deleted using the D/DD line commands. Presently, there is no means to perform a deletion of NOTE lines between line labels, or based on whether they are excluded or not.
It is possible to map a key to find the next NOTE line and then delete it. Doing so may help address some of the limitations for NOTE deletion. Such a mapped key would be set so that it auto-repeated. For sake of discussion, suppose we map this function to Ctrl-Shift N. A definition that would accomplish this is:
(home)[LOC NOTE](Enter)(txthome){D}(Enter)
To use this macro to delete a span of NOTE lines, the procedure would be:
- Scroll to the first NOTE line you want to delete.
- Press and hold Ctrl-Shift N until all desired NOTE lines are deleted.
The SPFLite primary command CUT is used to copy data lines into the clipboard, and PASTE is used to copy data lines from the clipboard into the edit file. Presently, CUT and PASTE do not support NOTE lines, since there is no portable way to represent NOTE lines in the Windows clipboard area while keeping the Windows clipboard in a standard format that is recognized by other application programs.
Still, users may wish to have the ability to copy and paste blocks of lines that have embedded NOTE lines. What follows is a suggested approach that may prove useful.
First, establish a temporary file that will be used for copying and pasting lines with embedded notes.
Let us call this file C:\TEMP\CLIPBOARD.NOTE for the sake of discussion. The actual file name and file type you use are up to you; this is just an example to explain things.
Next, let us map two keys to copy data to this temporary file and to copy from this file. Some version of the C and V keys could be used, of course, since Ctrl-C and Ctrl-V are used in text editors for a similar purpose. However, in this example, we will use the - minus key for copy and the = equal key for paste, with a modifier key of Ctrl. The mapping will look like this:
Ctrl – will contain REP C:\TEMP\CLIPBOARD.NOTE
Ctrl = will contain COPY C:\TEMP\CLIPBOARD.NOTE
When mapping these keys, the check-box for these keys to auto-repeat is cleared, so that they don't unexpectedly repeat themselves.
There MUST be an existing PROFILE for files of type NOTE which has STATE ON enabled. If you have not yet created a profile for files of type NOTE, you will have to make one, and then set its STATE value to ON. That will make the C:\TEMP\CLIPBOARD.NOTE temporary file note-enabled. If you omit this step, the technique discussed here WILL NOT WORK. Bear in mind that having the Profile name be NOTE is just a naming convention; you could use any file name or extension you wanted for this Temp file, as long as its Profile has STATE set to ON.
Once this setup is done, these keys will be sufficient for most purposes. This approach may not work in special cases, such as non-standard files types, fixed-length files or EBCDIC, but for typical ASCII text files, it should work well.
Even though the discussion above references NOTE lines, it will also work for xNOTE lines. The same technique will work for all types of notes.
Created with the Personal Edition of HelpNDoc: Full-featured EPub generator