Contents of Article


Selecting a set of files for the multi-edit session

Working with SPFLite's representation of multiple files in a single edit tab

Storing data during SAVE and END processing

Simulating a multi-browse with SAVEAS

Adding and removing files from a multi-edit session

Line commands permitted on =FILE> lines

The (ClipName) and (ClipPath) keyboard primitive functions in Multi-Edit

Creating and using orphaned lines

Navigating from one file to another

Dealing with external changes while an edit is in progress

Treatment of unqualified file names on primary commands

Read Only files and MEDIT

What else can you do in a multi-edit session ?


Introduction


Multi-Edit is a new editing technology, not present in IBM ISPF. A multi-edit is an edit session containing multiple files under a single SPFLite edit tab.


Why use Multi-Edit sessions?  


The main reason is increased productivity in quickly making large-scale, synchronized changes to multiple files at one time. 


Suppose you have several text files that are interrelated, containing common names and values that are defined and referenced throughout every file. (Program source files, containing the names of functions and variables, are one example of this.)  Now, what if you wanted to make a new version of these files that involved changing these common names and values everywhere in every file. How would you go about doing it?


You might have an existing list of files you need to work on, in a directory list or File List. Or, you could use a Find in Files command FF to search for all files containing some string, which produces a Found Files File List. Even with the Find in Files command FF, now part of SPFLite, you would still have to manually apply the changes to each file, one file at a time. When there are many changes and many files involved, that could be a long, tedious process. 


Let's say you wanted to change the word ABC to DEF in every file:  You would have open “file 1” from your list, issue a command like CHANGE ABC DEF WORD ALL, close the file, open “file 2”, and repeat the process, over and over again. Now, picture lots of changes to lots of files. You can see how labor-intensive this could get.


Ideally, you would like to be able to say, CHANGE ABC DEF WORD ALL and have that change applied to every file containing the word ABC, all at the same time. With multi-edit, now you can!


Some users of Windows GUI-type editors and software developers that use Integrated Development Environments (IDE's) are familiar with the powerful concept of a "refactoring editor". Our Multi-Edit facility is not exactly a refactoring editor, but it's pretty close. One advantage of SPFLite's Multi-Edit is that it's a general facility, one that can be used on any data, and is not dependent on a software development environment or any programming language. And, it fits within an ISPF like architecture, something ISPF itself doesn't offer.


Bear in mind that you could have several multi-edit sessions open at the same time, as long as no file is involved in more than one edit session (whether a regular edit session or multi-edit session).


We'll take this one step at a time.


Selecting a set of files for the Multi-Edit session


In the File Manager, start with a displayed list of files, and for each one that you want to be part of your Multi-Edit session, place an M line command on that line. The list of files can be a directory list, where you set the File Path and File Patterns fields, or it can be a File List display.


Note: You can apply selected File Manager line commands to a File List, and the commands will be applied, not to the File List itself, but to all the files named within the File List. In particular, to start a Multi-Edit all of the files named in a File List, you can issue the File Manager line command ALL M for that File List. See File Manager ALL command and FILELISTS for more information.


Let's say you have placed the files of interest into the Favorite Files File List. Here is what the list might look like (the display is a little simplified here). We are going to select three files from this list, the AAA, BBB and JJJ files. To do this, place the Multi-Edit line command M on each of these files, and after all of the M codes are in place, then press Enter. If you have to, you can scroll up and down in the list, but don't press Enter until you are done putting M codes on every file you want to edit.



Once you press Enter, you are about to begin your first multi-edit session. (This is something you've never seen before in an ISPF style editor, and probably not anywhere else, either.)


Working with SPFLite's representation of multiple files in a single Edit tab


Once you have selected your files with the M command and pressed Enter, you will have a new file tab opened. Since there are multiple files involved, and no single name would be appropriate for the file tab label, you will instead see (Multi-Edit) in the Windows title bar, and (M-Edit) in the file tab label. The edit session display will look like this:



Each of the files in the Multi-Edit session are separated by a =FILE> separator line. This separator line cannot be moved or modified. As you will notice the =FILE> separator does not have a line number. This is because it is not ‘data' but merely denotes the start of a new file. You will also see that each =FILE> line contains the fully-qualified name of the file that follows it. The actual characters =FILE> are called the =FILE> marker.


It is possible to remove the =FILE> marker from the display, if you desire to do so.  See the HIDE primary command.


Take note of the line numbers. You will see that even though there are three files in this multi-edit session, the line numbers are consecutive from 1 up, but they represent three different files. Just to make this clear,


Line 000001 is line 1 of file AAA.TXT

Line 000002 is line 2 of file AAA.TXT

Line 000003 is line 3 of file AAA.TXT


Line 000004 is line 1 of file BBB.TXT

Line 000005 is line 2 of file BBB.TXT

Line 000006 is line 3 of file BBB.TXT


Line 000007 is line 1 of file JJJ.TXT

Line 000008 is line 2 of file JJJ.TXT

Line 000009 is line 3 of file TJJJ.TXT


The reason the line numbers are consecutive is that, internally, SPFLite treats the entire edit session as though it were a single file.  That is because it has read-in every file into memory in a single location. By doing this, it makes it possible to issue ordinary SPFLite editing commands that end up affecting multiple files.


If you are following the example and look closely, you will see that the file names in each =FILE> line are in the same order as they were in the File List they were selected from using the M line command. This means that if you want or need the files in your multi-edit session to be in some particular order, you must sort the directory list or File List as you need it to be, prior to starting the multi-edit session. 


The color of the multi-edit tab label is handled the same as regular file tab labels are, and if anything is updated, the color will change, if you have set up your color scheme to do this. Let's say that unmodified files will have a tab that looks like (M-Edit) in blue. You will also notice on the Status line, where it would normally say Edit, instead it shows 3 Edit. This means you have 3 files involved in this edit session.


Notice in the display above, on line 3, the word THREE is misspelled as THRE. Let's correct it, by typing over it and pressing Enter:



What changes?

    • The first =FILE> marker changes to =FILE* to show that this file has been modified.


    • The file tab will change color (depending on your color setup); let us say it now shows (M-Edit) in red; that means that this multi-edit session has changed. 


    • The Status line will change from 3 Edit to 3 Edit 1*. The notation 3 Edit 1* means, you have 3 files involved in the multi-edit session, and 1 of them has been modified.


Note: When the sequence area width is set to 5, the =FILE> and =FILE* markers are displayed as FILE> and FILE*, respectively.


Suppose you wanted to change the word FILE to DATASET in all these files. How would you do it?  Here is where the power of multi-edit comes into play. Within this edit session, you see 9 lines of data. To SPFLite, these 9 lines are treated internally as if they were a single file, rather than three. Because the =FILE> markers are not data, the editing commands you normally use in SPFLite (with very few exceptions) simply ignore these marker lines. This means that you can change the data for every file (or, as many of them as you'd like to) with a single command.  Here's how you change the word:


Command > CHANGE FILE DATASET ALL


It's just that simple!


Here is what your edit session will look like after you do this:



Again, what changes?

    • Now, all =FILE> markers have changed to =FILE* because every file has been modified


    • The file tab continues to show (M-Edit) in red to reflect that at least one file was modified. 


    • The Status line will change from 3 Edit 1* to 3 Edit 3*. The notation 3 Edit 3* means, you have 3 files involved in the edit session, and all 3 of them have been modified.


You can get rid of the ==CHG> markers by issuing a RESET command, just as you would in a regular file.


Storing data during SAVE and END processing


Now that we have changed the data in all these files, let's save them. What do you need to do to save every one of these files?  Just say SAVE like you do for a regular file. You can type in the SAVE command, or issue it from a mapped key. When you do this, SPFLite is aware that it's inside a multi-edit session, and it saves every file to the file location you see on each =FILE> line. 


When you say SAVE in our example, you will see the message:  3 files saved. All of the *FILE> markers revert back to =FILE> to show each file no longer has unsaved changes.


Will SAVE always save all files?  Yes, just as a SAVE command on a single-file Edit will save the file regardless of its modified status, so does SAVE in a multi-edit session.


When you END a multi-edit session and there are unsaved changes in any file, these will get saved according to the AUTOSAVE options in effect individually by file. END will only save modified files.


Note:  When you END a multi-edit session, the file type, and thus the PROFILE, for each individual file, is individually respected. That means some files might have different AUTOSAVE options. It's up to you how you want to handle this in cases where you do a multi-edit of files having different PROFILE settings.


You can also CANCEL a multi-edit session, discarding any unsaved changes that may exist across all the files you have open, just as you could for a regular edit session.


Simulating a multi-browse with SAVEAS


There is no Browse equivalent of multi-edit; that is, there is no "multi-browse" command. However, there may be times when you might wish to temporarily work with a set of files (the way multi-edit does) without risking changes to any of the files (the way a Browse session does).


To accomplish this, you can begin a multi-edit session as normal, and then issue a SAVEAS command with no operands. This will bring up a directory-browse dialog, where you choose a directory (or create one) where all the files in your multi-edit session are saved. Once you do this, you will begin a new multi-edit session in which each =FILE> line will have the same file name and the (new) directory you have chosen.


You can do the SAVEAS selecting an existing, non-empty directory, but if any files within that directory have the same basic file names as the ones you are trying to save, the SAVEAS operation will not be performed and no files will be saved. (SAVEAS will not write over existing files.)  Thus, the normal and preferred procedure is to create a new empty directory (or take steps to ensure that the SAVEAS target directory is empty ahead of time) as part of your SAVEAS process.


When you begin a multi-edit session from a File List using files originating from more than one directory, SPFLite permits you to have files in different directories that have the same basic file name in the same multi-edit session. However, if you intend to do a SAVEAS command, all of the basic file names involved must be unique, since the SAVEAS command will save all of the files from your multi-edit session into the same directory. If they are not unique, you can continue to use your multi-edit session, but you will not be able to issue a SAVEAS command.


When you do a SAVEAS command, every file currently in the multi-edit session is saved to the new location, even files not currently in a modified state.


Adding and removing files from a multi-edit session


If you issue a D line command on a =FILE> marker, the marker line and all lines associated with that file will disappear. This does NOT delete the file itself, but it removes the file from the multi-edit session. Any unsaved changes that may exist for that file will be discarded, the same as when a CANCEL command is issued. Because a D line command on a =FILE> marker removes the file from the multi-edit session but does not delete it, you can think of using a D line command this way as if it meant “detach” instead of “delete”.


(When you use a D line command on ordinary data lines that follow the =FILE> line, the D will delete the data, just as it does in a regular file.)


If you wish to bring in another file to an existing multi-edit session, issue an MEDIT primary command. This will create a new =FILE> separator line after the last data line in the last file, and then the data lines from the newly added file will appear after that. If you started editing a single file as an ordinary edit session, MEDIT will convert the edit session to a multi-edit session and then add the file to the end.


Line commands permitted on =FILE> lines


As mentioned, you can use the D line to remove a file from the multi-edit session. The following line commands are also available on the =FILE> separator line:

    • X will exclude all the lines belonging to the file. It will not exclude the =FILE> separator line itself. You will see the excluded-line placeholder in place of the data lines for that file, but the =FILE> separator line will always be visible and cannot be excluded.


    • S will unexclude all the lines belonging to the file, undoing what an X line command on a =FILE> line did.


    • A and B can be put on this line if you are moving data lines after or before this point. 


    • M will allow you to move a file's data to a different position within the MEdit session. The A/B destination must be located before another =FILE> line or the ** Bottom ** line


Note that a =FILE> line itself cannot be typed on, nor can it be changed manually or through primary or line commands.



The (ClipName) and (ClipPath) keyboard primitive functions in Multi-Edit


These functions normally return the file name or full path name of the edit file. In a multi-edit session, there are multiple files and thus multiple names. In this case, the (ClipName) and (ClipPath) keyboard primitive functions will place into the clipboard the name of the particular file where the cursor is located at the moment, whether it is on a =FILE> line or is on any data line associated with that =FILE> line. If the cursor is not in a “file area” when you use these functions, such as on the primary command line, it is an error, and the clipboard will not get anything stored into it.


The (ClipName) and (ClipPath) keyboard primitive functions have also been enhanced to return the file name of a file that the cursor is on if you are in the File Manager.


Creating and using orphaned lines


Normally, the Top of Data line in a multi-edit session is immediately followed by a =FILE> separator line and then line 1 of the first file. If you copy one or more data lines after the Top of Data line, these lines will have no =FILE> separator preceding them. These lines do not belong to any file at all, but are “orphaned” lines. During a SAVE or END command, orphaned lines are not saved.


You can use orphaned lines as temporary data, perhaps data that you wish to edit and then copy or move to other parts of the multi-edit session. Having orphaned lines is not an error; you just need to be aware of how SPFLite treats these lines.


Navigating from one file to another


The LOCATE command has been extended with a locate line-type of FILE. You can LOCATE to the FIRST, LAST, PREV or NEXT =FILE> line using this command, by specifying LOCATE FILE FIRST, etc.


As you do, you will see a message such as,  File 1 of 3 found. You can use this information to help keep track of where you are in the multi-edit session, which may be useful if you have many files involved.


If you need to find a certain file number and you have many files (let's say, 100 of them) there is no command to directly find the sixty-third file, for example. However, let's say you have the F5 key mapped to RLOCFIND, which will repeat the last LOCATE or FIND, whichever has happened most recently, and the auto-repeat checkbox for that key is checked. You can first issue a LOCATE FILE FIRST, and you will see the message (in this example),  File 1 of 100 found. To find file 63, just hold down the F5 key until you (eventually) see the File 63 of 100 found message. 


(In case you pass it up, you could also have Shift-F5 mapped to RLOCFIND REVERSE (for example). Then, just hold down the Shift key and press F5 to go backwards until the right file number shows up in the message, and there you are. If you don't have a key for RLOCFIND REVERSE set up, just slow down when you get near the right file number so you don't pass it up.)


The command LOCATE FILE must not be combined with ALL or MX.


Dealing with external changes while an edit is in progress


SPFLite will keep track of every file involved in a multi-edit session, so that you are protected from, or notified about, external changes to any file in your multi-edit session, the same as you would for an individual edit file in the same situation.


Treatment of unqualified file names on primary commands


When an unqualified file name appears in a primary command issued from a multi-edit session, SPFLite must determine the directory to look at when resolving the file name.


The method it uses is the take the file path of the last loaded file as the assumed directory. This means that commands like MEDIT, COPY, etc. that take file names will look in the directory where the last-loaded file was found to find files that are not fully-qualified on the command line.


This should be taken into account when you have multi-edit sessions that involve files from more than one directory, which can only happen if you started your multi-edit session from a File List display instead of from a directory list display.


Read Only files and MEDIT


SPFLite does not currently support Read Only files participating in Multi-Edit sessions. If you want to use a Read Only file within MEDIT, you must remove the Read Only attribute, or copy the file to another name, and ensure that the copy of the file is not Read Only.


What else can you do in a multi-edit session ?


Basically, anything that you could do in a regular edit session, multiplied by the power of acting on multiple files at once. 


The possibilities are intriguing:


    • Exclude, Flip, and Show to manage the exclusion status of the lines
    • SORT across multiple files at a time (this will work, but the results may surprise you; be certain this is what you intended)
    • Use tags to identify and edit lines across multiple files
    • Use Power Typing to interactively update data lines in parallel, across multiple files
    • SUBMIT jobs consisting of multiple files
    • Print multiple files at one time with a single PRINT command


Maybe you can come with interesting techniques of your own. If you do, please let us know!

Created with the Personal Edition of HelpNDoc: Streamline Your Documentation Process with HelpNDoc's Project Analyzer