SoulEdit: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "'''SoulEdit''' is a code editor, written in SOUL, specifically designed for SOUL application development. '''SoulEdit" features extended editing capability - like split/join,...")
 
m (no mp4 if IE/Edge)
 
(50 intermediate revisions by 7 users not shown)
Line 1: Line 1:
'''SoulEdit''' is a code editor, written in SOUL, specifically designed for SOUL application development. '''SoulEdit" features extended editing capability - like split/join, bookmarks, display filtering and syntax-specific colors - as well as facilities that make running, debugging and testing SOUL code more seamless and intuitive.
'''SoulEdit''' is a code editor, written in [[SOUL]], specifically designed for SOUL application development. SoulEdit features extended editing capability — like split/join, bookmarks, display filtering, and syntax-specific colors — as well as facilities that make running, debugging, and testing SOUL code more seamless and intuitive.
 
SoulEdit runs as an [[Application Subsystem development|application subsystem]], so it needs a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). [[RKTools installation]] contains more information about setting up the environment for SoulEdit.
 
SoulEdit is built into <var class="product">SirPro</var>, one of the [[RKTools]] family of products from Rocket Software, and it is accessible from the <var class="product">SirPro</var> TN3270 interface.
 
SoulEdit can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called <code>SE</code>, so it is executable from the command line. You can get information about setting up your own SoulEdit subsystem from the [[RKTools installation]] instructions for the RKTools subsystems.
 
SoulEdit requires <var class="product">Model&nbsp;204</var> version 7.5 or higher.
 
<p class="warn"><b>Note:</b> A video introduction to SoulEdit is available (for browsers other than IE/Edge): [[Media:SoulEdit2.mp4|Introducing SoulEdit]]. </p>


'''SoulEdit''' runs as an application subsystem, so it needs an apsy definition for it to operate along with a minimum 640K server size - 750K would be safer as that provides room for future enhancements and the addition of user-written macros. See the ULSPF Installation Guide for more information on setting up the environment for SoulEdit. '''SoulEdit''' is also built into <var class="product">SirPro</var>, which is part of the [[ULSPF | UL/SPF]] family of products from '''Rocket Software'''.  It can also be run as a standalone editor by setting up a separate APSY - at '''Rocket''' we run it as an apsy called SE so it's executable from the command line.


==Overview==
==Overview==
<var class="product">[[SirPro]]</var> is a menu-driven application subsystem that provides tools for programmers, database administrators, and application managers inside the Model&nbsp;204 environment. <var class="product">SirPro</var>'s primary feature set is centered on the manipulation of <var class="product">Model&nbsp;204</var> procedures contained in Model&nbsp;204 files. 
You can access SoulEdit to edit a procedure in these ways:
<ul>
<li>From the <var class="product">SirPro</var> 3270 interface, use the <code>E</code> prefix command before a procedure in a [[SirPro procedure-list operations#Overview|procedure list]]. </li>
<li>From the Model&nbsp;204 command line (if SoulEdit is defined as a standalone subsystem, for example, <code>SE</code>), enter the subsystem name with a procedure name: <code>SE MYPROCEDURE</code>, where <code>MYPROCEDURE</code> is a procedure in the current file. </li>
</ul>
<p class="caption" style="width:625px">SoulEdit main editing screen</p>
<p class="figure">[[File:SoulEdit_OverviewS.png|625px]] </p>
The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right is the range of line numbers, beginning with the current top-of-the-screen line number. The lines in the screen may be colored; colors are user-settable via the <var>COLORS</var> command.
Command line and PF key options for the TN3270 interface are described in the tables below.
One of the most useful features of SoulEdit is the ability to run a program with the <var>GO</var> command and immediately view the output in a scrollable [[Stringlist class|Stringlist]]. If errors occurred while running, a series of <var>AUDIT</var> commands is available to display the audit trail output of the procedure you've just run.
==Command line options==       
<table class="thJustBold">
<tr class="head"><th>Command</th><th>Result</th></tr>
<tr><th>T[<i>n</i>] | TOP [<i>n</i>] | M+PF7 </th>
<td>Go to the top of the editor content; optional <i>n</i> scrolls page so line-number <i>n</i> is at the top. </td></tr>
<tr><th>B | BOTTOM | M+PF8 </th>
<td>Go to the bottom of the editor content. </td></tr>
<tr><th>C <i>lineNumber</i> </th>
<td>Center the line specified by <i>lineNumber</i>. <i>lineNumber</i> is absolute, not relative. </td></tr>
<tr><th>+ | -<i>numericValue</i> </th>
<td>Position content relative to the numeric value. </td></tr>
<tr><th>[-]F | Find <i>value</i> </th>
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr>
<tr><th>[-]/<i>value</i> </th>
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr>
<tr><th>R | REPLACE/<i>replaceThis</i>/<i>withThis</i>[[/<i>n</i>] ALL] </th>
<td>Replace, where <i>n</i> specifies replacements per line. The character immediately following the <var>R</var> or <var>REPLACE</var> is used as a delimiter between tokens (cannot be alphanumeric). </td></tr>
<tr><th>A | ALL <i>value</i> </th>
<td>Hide all lines that do not match <i>value</i>. A command without a <i>value</i> performs a <var>SHOW ALL</var> instead. </td></tr>
<tr><th>HIDE <i>value</i> </th>
<td>Hide all lines that match <i>value</i>. </td></tr>
<tr><th>SHOW | HIDE COMMENTS </th>
<td>Show or hide all comment lines. </td></tr>
<tr><th>UNHIDE <i>value</i> </th>
<td>Unhide all lines that match <i>value</i>. </td></tr>
<tr><th>CLEAR HIDDEN | RESET HIDDEN </th>
<td>Clear all hidden lines (unhide). </td></tr>
<tr><th>SHOW ALL | SHOW HIDDEN </th>
<td>Clear all hidden lines (unhide). </td></tr>
<tr><th>GO </th>
<td>Run the program, and capture the output into a scrollable screen. </td></tr>
<tr><th>[IN <i>fileName</i> ]GET <i>procName</i> </th>
<td>Obtain the named procedure and insert into editor. You can use line command targeting. </td></tr>
<tr><th>SAVE [<i>procName</i>] </th>
<td>Save current editor content (optional save into a different named procedure, including temporary procedures). </td></tr>
<tr><th>END </th>
<td>Perform <var>SAVE</var> and exit the editor. </td></tr>
<tr><th>QUIT </th>
<td>Exit the editor without saving or giving a modification warning. </td></tr>
<tr><th>ALIGN <i>value</i> </th>
<td>Requires BB line command range (has issues when crossing "block" statements). </td></tr>
<tr><th>SORT [A | D | ASC | DESC | ASCENDING | DESCENDING]</th>
<td>Requires BB line command range. </td></tr>     
<tr><th>CLEAR </th>
<td>Clear all line commands. </td></tr>
<tr><th>RESET PROC | RELOAD | RELOAD PROC </th>
<td>Discards any changes by reloading the current procedure from file. </td></tr>
<tr><th>REFRESH PAGE </th>
<td>Ignore any changes to this page since last enter. </td></tr>
<tr><th>NUM | NUMS | NUMBERS [ON | OFF] </th>
<td>Show line numbers in prefix field (toggle). </td></tr>
<tr><th>= </th>
<td>Repeat last command (same as PF9). </td></tr>
<tr><th><i>command stack</i> (PF6) </th>
<td>Cycles through the command stack. </td></tr>
   
<tr><th>SET COMMAND STACK <i>n</i> </th>
<td>Defaults to 10; user may increase/decrease. </td></tr>
   
<tr><th>Split/join lines (PF2) </th>
<td>Cursor sensitive: if no data from cursor, a join is performed; else split is performed. </td></tr>
   
<tr><th>FLIP HIDDEN </th>
<td>Flip the hidden state of lines: hidden->shown && shown->hidden. </td></tr>
   
<tr><th>FF | BB+FORMAT - FORMAT [<i>width</i>] [INDENT <i>n</i>] </th>
<td>Format range (indents and alignment). <i>Not fully completed, but mostly functional.</i> </td></tr>
<tr><th>UNDO FORMAT </th>
<td>Reinstate the last <var>FORMAT</var> to its state before the format (does not check if code has changed). </td></tr>
<tr><th>SET FORMAT <i>type</i> </th>
<td>Force the formatting type used by <var>FORMAT/FF</var>. Valid types: M204, XSL. </td></tr>
<tr><th nowrap>RUN  (saves and runs code in a daemon)
RUN TERM (saves and runs code on current thread)
RUN [TERM] [<i>procName</i> [FILE <i>filename</i> [PASS <i>password</i>]]] </th>
<td>Output from the execution is scrollable (lost daemons are trapped and reported). </td></tr>
<tr><th>SHOW [ [RUN | OUTPUT] | RUN OUTPUT] </th>
<td>Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES. </td></tr>
<tr><th>SHOW CHANGES </th>
<td>Compares current content against procedure on file, and display in a scrollable form. </td></tr>
<tr><th>SHOW SEQ CHANGES </th>
<td>Do compare against SEQ version in same procedure file. </td></tr>
<tr><th>SCALE (toggles on/off) </th>
<td><code> |...+....1....+....2....+....3...</code> etc. </td></tr>
<tr><th>PFKEYS (toggles on/off) </th>
<td>Show valid PF keys on the last line of the page. </td></tr>
<tr><th>NEW PROC[EDURE] </th>
<td>Clear current code (essentially a quit), and start with a blank procedure. </td></tr>
<tr><th>Formatting for XSL </th>
<td>Change formatting where procedure name ends with <code>.xsl</code>. </td></tr>
<tr><th>HELP (PF1) </th>
<td>Display Help text. </td></tr>
<tr><th>VAR | VARS | VARIABLES </th>
<td>Show variable usage(counts) within scope. </td></tr>
<tr><th>SETUP | PROFILE </th>
<td>Set user editor preferences. </td></tr>
<tr><th>COLORS </th>
<td>Set user editor-color preferences. </td></tr>
<tr><th>.<i>value</i> </th>
<td>Bookmarks. For example: <code>.foo</code> as a line command bookmarks the line. <code>.foo</code> as a command focuses the bookmark. </td></tr>
<tr><th>CLEAR BOOKMARKS </th>
<td>Clear all bookmarks. </td></tr>
<tr><th>XCOMPARE | XC [EXACT | DEBLANK | COMPRESS] </th>
<td>XCompares current content against procedure on file; displays in a scrollable form. </td></tr>
<tr><th>XCOMPARE SEQ | XCS [EXACT | DEBLANK | COMPRESS] </th>
<td>Do XCompare against SEQ version in same procedure file (only works for SirLib users). </td></tr>
<tr><th>LAYOUT | MAP </th>
<td>List all class/subroutines/functions. PF4 focuses entry from listing. </td></tr>
<tr><th>INCLUDES command </th>
<td>Show hierarchy of all includes referenced within the current procedure. </td></tr>
<tr><th>PROTECT/UNPROTECT </th>
<td>Force the displayed content to be protected/unprotected.</td></tr>
<tr><th>BB | BLOCK WHERE </th>
<td>Add BB markers to the current "where" scope. </td></tr>
<tr><th>AUDIT [<i>minutes</i> | <i>timestamp</i> | LAST[RUN]] </th>
<td>Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied. </td></tr>
<tr><th>SET FILE <i>fileName</i> </th>
<td>Sets the file name for saving procedures; also clears the procedure name. </td></tr>
<tr><th>SNAP | SNAPSHOT </th>
<td>Takes a copy of the code in the current editing session and saves it as snapshot.</td></tr>
<tr><th>XCB [<i>previous-snapshot-offset</i>] </th>
<td>Compare the current code against the last snapshot taken. </td></tr>
</table>                                                                                                                                             
Used in conjunction with the PF12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate the errors in the currently loaded procedure:   
                                                                                     
<table class="thJustBold">
<tr><th>NE | NEXT ERROR </th>
<td>Navigate to the next error. </td></tr>
<tr><th>PE | PREVIOUS ERROR </th>
<td>Navigate to the previous error. </td></tr>
<tr><th>CE | CURRENT ERROR </th>
<td>Navigate to the current error. </td></tr>
<tr><th>CLE | CLEAR ERRORS </th>
<td>Clear the error bookmarks. </td></tr>
</table>                                                                                                                                                                                                                                                 
==Line prefix commands==
===Block prefixes, with repeating ignored===
<table class="thJustBold">
<tr><th>CC</th>
<td>Block copy (requires targeting prefix). </td></tr>
<tr><th>MM</th>
<td>Block move (requires targeting prefix).</td></tr>
<tr><th>DD</th>
<td>Block delete.</td></tr>
<tr><th>HH</th>
<td>Block hide.</td></tr>
<tr><th>**</th>
<td>Block comment (set/clear; first line is used to determine state switch. If first character is <code>*</code>, comments are removed).</td></tr>
<tr><th>BB</th>
<td>Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.</td></tr>
                         
<tr><th>FF</th>
<td>Format the specified block. Sets indenting to the number of spaces specified in the user profile.</td></tr>
</table>
===Block prefixes, with repeating honored===
For example, <code>""3</code> replicates the block three times.
<table class="thJustBold">
<tr><th>RR ""</th>
<td>Block replicate</td></tr>
<tr><th><< ((</th>
<td>Block shift left (with protections to prevent loss of leading text)</td></tr>
<tr><th>>> ))</th>
<td>Block shift right (with protections to prevent loss of trailing text)</td></tr>
</table>
===Targeting prefixes===
<table class="thJustBold">
<tr><th>A</th>
<td>Target after line</td></tr>
<tr><th>F</th>
<td>Target following line </td></tr>
<tr><th>B</th>
<td>Target before line</td></tr>
<tr><th> P</th>
<td>Target previous line</td></tr>
</table>
===Singular prefixes, with repeating ignored===
<table class="thJustBold">
<tr><th>C</th>
<td>Copy (requires targeting prefix).</td></tr>
<tr><th>M</th>
<td>Move (requires targeting prefix).</td></tr>
<tr><th>E</th>
<td>Expand line to 255 bytes (toggles on/off).</td></tr>
<tr><th>/</th>
<td>Center this line.</td></tr>
<tr><th>-</th>
<td>Folding of blocks; hide lines from marked line to closing/opening block. <p>Example: <code>if -> end if... </code></p></td></tr>
<tr><th>X</th>
<td>Expand/collapse <var>INCLUDE</var> inline. Only usable on <var>INCLUDE</var> lines. The expanded <var>INCLUDE</var> lines are protected.</td></tr>
</table>
===Singular prefixes, with repeating honored===
<table class="thJustBold">
<tr><th>H</th>
<td>Hide</td></tr>
                                         
<tr><th>S +</th>
<td>Show</td></tr>
<tr><th>D</th>
<td>Delete</td></tr>
<tr><th>R "</th>
<td>Replicate</td></tr>
<tr><th>*</th>
<td>Comment (set/clear; if first character is <code>*</code>, comments are removed)</td></tr>
<tr><th>< (</th>
<td>Shift line left (with protections to prevent loss of leading text)</td></tr>
<tr><th>> )</th>
<td>Shift line right (with protections to prevent loss of trailing text)</td></tr>   
</table>
==PF keys==
<table class="thJustBold">
<tr><td>PF1</td><td>Help</td></tr>
<tr><td>PF2</td>
<td>Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.</td></tr>
<tr><td>PF3</td>
<td>Quit the editor without saving.</td></tr>
<tr><td>PF4</td>
<td></td></tr>
<tr><td>PF5</td>
<td></td></tr>
<tr><td>PF6</td>
<td>Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET.</td></tr>
<tr><td>PF7</td>
<td>Scroll up / use with M to scroll to top.</td></tr>
<tr><td>PF8</td>
<td>Scroll down / use with M to scroll to bottom.</td></tr>
<tr><td>PF9</td>
<td>Repeat previous command.</td></tr>
<tr><td>PF10</td>
<td>Shift+PF10 performs an ALL for the text under the cursor.</td></tr>
<tr><td>PF11</td>
<td>Creates/appends the value under the cursor to a traceText upon the following line.</td></tr>
<tr><td>PF12</td>
<td>Saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.</td></tr>
</table>
==User-written extensions (SCMDs)==
SoulEdit has a facility that lets you add command-line extensions to the editor.
As an example, <code>INFO</code> is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model&nbsp;204 system method (output from a <var>[[LoadSystemMethodInfo (XmlDoc subroutine)|LoadSystemMethodInfo]]</var> method call). If during an ordinary editing session you type <code>info currenttimestring</code> into the command line of SoulEdit:
<p class="caption" style="width:425px">User-defined command entered on command line</p>
<p class="figure">[[File:SOUL_UserCommands1S.png|425px]]</p>
You see the output of the <var>LoadSystemMethodInfo</var> call displayed in a scrollable screen:
<p class="figure">[[File:SOUL_UserCommands2S.png|600px]]</p>
Pressing the PF3 key returns to the in-progress editing session.
The editor extensions are created via <code>SCMD</code> procedures stored in a user-designated file. You can see how <code>INFO</code> works by looking at procedure <code>SCMD\INFO</code> in the RKTools <code>SIRIUS</code> file.
To create your own commands, specify the procedure file where they will reside using the <var>PROFILE</var> command and ''Custom Macros File''. SoulEdit scans this file for procedures prefixed with <code>SCMD\</code> and loads them into memory at the beginning of the editing session. Copy <code>SCMD\INFO</code> into your Macros file with a new name, and customize the ''run'' method to your liking.
==Timed backups==
SoulEdit can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the <var>PROFILE</var> command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using <var>PROFILE</var>.


<var class="product">SirPro</var> is a menu-driven application subsystem that provides tools for programmers, database administrators and application managers inside the Model 204 environment.  <var class="product">SirPro</var>'s primary feature set is centered on the manipulation of <var class="product">Model 204</var> procedures contained in Model 204 files.  <var class="product">SirPro</var> allows a programmer to search and display lists of procedures, and to Browse, Edit, Copy, Move, Delete and Rename procedures. To access '''SoulEdit''' from <var class="product">SirPro</var>, use the 'E' prefix command from the list of procedure. If '''SoulEdit''' is defined as a standalone apsy (for example, 'SE') simply type the apsy name with a procedure: '''SE MYPROCEDURE''' where MYPROCEDURE is a procedure in the current file.
==Auditing==
SoulEdit has an auditing feature to list entries from the current journal. <var>AUDIT</var> options are:


===Command Line options===                                                                                                                       
<table class="thJustBold">
<tr><th>AUDIT</th>
<td>Lists the previous minute of the current journal.</td></tr>


    T[ n]|TOP[ n]|M+PF7                      - go to the Top of the editor content... optional n (linenum) as top of page                   
<tr><th>AUDIT <i>n</i></th>
    B|BOTTOM|M+PF8                          - go to the Bottom of the editor content                                                       
<td><i>n</i> is a numeric value from 1 to 999 indicating how many minutes of the journal to display.</td></tr>
    C <lineNumber>                           - center the line specified by lineNumber... lineNumber is absolute... not relative             
    +|-<numericValue>                       - position content relative to the numeric value                                               
    [-]F|Find <value>                       - find previous/next value from cursor position (PF5 repeats last find)                         
    [-]/<value>                              - find previous/next value from cursor position (PF5 repeats last find)                         
    R|REPLACE/<replaceThis>/<withThis>[[/n] ALL]  - replace... n = replacements per line                    (verify not implemented yet)     
    for replace... the character immediately following the R or REPLACE is used as a delimiter between tokens(cannot be alphanumeric)       
    A|ALL <value>                           - hide all lines that do not match <value>... command without <value> performs a SHOW ALL instead
    HIDE <value>                             - hide all lines that match <value>                                                            
    SHOW|HIDE COMMENTS                      - show or hide all comment lines                                                               
    UNHIDE <value>                           - unhide all lines that match <value>                                                           
    CLEAR HIDDEN|RESET HIDDEN                - clear all hidden lines (unhide)                                                               
    SHOW ALL|SHOW HIDDEN                    - clear all hidden lines (unhide)                                                               
    [IN <fileName> ]GET <procName>          - obtain the named proc and insert into editor... can use line command targeting               
    SAVE[ <procName>]                        - save current editor content (optional save into a different named proc including temp procs) 
    END                                      - perform SAVE and exit the editor                                                             
    QUIT                                    - exit the editor without saving or giving a modification warning                               
    ALIGN <value>                            - requires BB line command range  (has issues when crossing 'block' statements)                 
    SORT [A|D|ASC|DESC|ASCENDING|DESCENDING] - requires BB line command range                                                               
    CLEAR                                    - clear all line commands                                                                       
    RESET PROC|RELOAD|RELOAD PROC            - discards any changes by reloading the current procedure from file                             
    REFRESH PAGE                            - ignore any changes upon this page since last enter                                           
    NUM|NUMS|NUMBERS [ON|OFF]                - show line numbers in prefix field (toggle)                                                   
    =                                        - Repeat last command (same as PF9)                                                             
    command stack (pf6)                      - cycles thru the command stack                                                                 
    SET COMMAND STACK n                      - defaults to 10... but user may want to increase/decrease.                                     
    split/join lines (pf2)                  - cursor sensitive... if no data from cursor a join is performed else split is performed       
    FLIP HIDDEN                              - flip the hidden state of lines... hidden->shown && shown->hidden                             
    FF|BB+FORMAT - FORMAT [width] [INDENT n] - format range (indents and alignment)... not fully completed... but mostly functional         
    UNDO FORMAT                              - reinstates the last FORMAT to its state before the format (does not check if code has changed)
    SET FORMAT <type>                        - force the formatting type used by FORMAT/FF .. Valid types: M204, XSL                         
    RUN  (saves & runs code in a daemon)    - output from the execution is scrollable (lost daemons are trapped and reported)               
    RUN TERM (saves & runs code on current thread)                                                                                           
    RUN [TERM] [<procName> [FILE <filename> [PASS <password]]]                                                                               
    SHOW [[RUN|OUTPUT]|RUN OUTPUT]          - shows the output from the last executed code or commands line VAR/SHOW [SEQ] CHANGES         
    SHOW CHANGES                            - compares current content against proc on file and is displayed in a scrollable form           
    SHOW SEQ CHANGES                        - do compare against SEQ version in same procfile                                               
    SCALE  (toggles on/off)                  - |...+....1....+....2....+....3...etc                                                         
    PFKEYS (toggles on/off)                  - show valid pfkeys upon the last line of the page                                             
    NEW PROC[EDURE]                          - clear current code (essentially a quit)... and start with a blank proc                       
    Formating for XSL                        - change formating where proc name ends with .xsl                                               
    PF1|HELP                                - yup... right... will get right onto that  (basic atm... this actually)                       
    VAR|VARS|VARIABLES                      - show variable usage(counts) within scope                                                     
    SETUP|PROFILE                            - set user editor preferences                                                                   
    COLORS                                  - set user editor color preferences                                                             
    SET FILE <fileName>                     - sets the filename for saving procedures... also clears the procedure name                     
    bookmarks  .<value>                    - bookmarks...example.  .foo as a line command bookmarks it...  command .foo focuses the bookmark
    CLEAR BOOKMARKS                          - clear all bookmarks                                                                           
    XCOMPARE|XC [EXACT|DEBLANK|COMPRESS]      - XCompares current content against proc on file and is displayed in a scrollable form         
    XCOMPARE SEQ|XCS [EXACT|DEBLANK|COMPRESS] - do XCompare against SEQ version in same procfile                                             
    LAYOUT|MAP                                - list all class/subroutines/functions... can use pf4 to focus entry from listing             
    cursor sensitive FIND                    - PF10      performs a FIND for the text under the cursor                                     
    cursor sensitive ALL                      - shift+PF10 performs an ALL for the text under the cursor                                     
    cursor sensitive TraceText                - PF11      creates/appends the value under the cursor to a traceText upon the following line 
    open INCLUDE code specified by cursor    - PF12      when a cursor is on a line with an include statement will save current and -     
                                                          open(for edit) the include                                                       
    INCLUDES command                          - show heirarchy of all includes referenced within the current procedure                       
    PROTECT/UNPROTECT                        - force the displayed content to be protected/unprotected                                     
    BB¦BLOCK WHERE                            - Used to add BB markers to the current 'where' scope                                         
    AUDIT [minutes¦timestamp¦LAST[RUN]]      - This command shows the journal lines for the user... defaults to the last minute unless an   
                                                optional time is supplied                                                                   
    SNAP¦SNAPSHOT                            - Takes a copy of the code in the current editing session and saves it as snapshot             
    XCB [previous snapshot offset]            - Compare the current code against the last snapshot taken                                     
                                                                                                                                             
Used in conjunction with the pf12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate
thru the errors in the currently loaded procedure:-                                                                                         
                                                                                                                                             
    NE¦NEXT ERROR                            - Navigate to the next error                                                                   
    PE¦PREVIOUS ERROR                        - Navigate to the previous error                                                               
    CE¦CURRENT ERROR                          - Navigate to the current error                                                               
    CLE¦CLEAR ERRORS                          - Clear the error bookmarks                                                                   
                                                                                                                                                                                                                                                 
===Line Prefix Commands===


====Block Prefixes====
<tr><th style="white-space:nowrap;">AUDIT HH:MI[:SS.XX]</th>
(with repeating ignored)... so CC3 ignores the 3
<td>Lists the journal entries from the specified time. The colon (<tt>:</tt>) and period (<tt>.</tt>) are optional.</td></tr>
    CC = Block Copy                    (requires targeting prefix)                                                                        
    MM = Block Move                    (requires targeting prefix)                                                                        
    DD = Block Delete                                                                                                                       
    HH = Block Hide                                                                                                                         
    ** = Block Comment (set/clear - first line is used to determine state switch... if first char is * then comments are removed)
    BB = Block Boundaries.. used with editor commands: SORT, ALIGN, FORMAT.    Optional for R, REPLACE                         
    FF = Format specified block                                                                                                 
                                                                                                                                 
====Block Prefixs (with repeating honored)====


... so ""3 replicates the block 3 times
<tr><th style="white-space:nowrap;">AUDIT LAST[ RUN]</th>
  RR "" = Block Replicate                                                                                                       
<td>After a <var>GO</var> or <var>RUN</var> command runs a procedure from inside SoulEdit, <var>AUDIT LAST</var> shows all the journal entries pertaining to the job run. It excludes anything not associated with the <var>GO</var> or <var>RUN</var>. In addition to the journal entries for the thread, it also includes all child threads spawned by the <var>GO</var> or <var>RUN</var> thread.</td></tr>
  << (( = Block Shift Left  (with protections to prevent loss of leading text)                                                   
</table>
  >> )) = Block Shift Right (with protections to prevent loss of trailing text)                                                 
                                                                                                                                 
====Targeting Prefixs====
      A = Target After Line                                                                                                     
      F = Target Following Line                                                                                                 
      B = Target Before Line                                                                                                     
      P = Target Previous Line                                                                                                   
                                                                                                                                 
====Singular Prefixs====
(with repeating ignored)
      C = copy                          (requires targeting prefix)                                                             
      M = Move                          (requires targeting prefix)                                                             
      E = Expand line to 255 bytes  (toggles on/off)                                                                             
      / = center this line                                                                                                       
      - = folding of blocks... hide lines from marked line to closing/opening block... example: if -> end if... etc             
      X = Expand/collapse INCLUDE inline... only usable on INCLUDE lines... the expanded INCLUDE lines are protected             
                                                                                                                                 
====Singular Prefixes====
(with repeating honored)                 
      H = Hide                                                                                                                   
    S + = Show                                                                                                                   
      D = Delete                                                                                                                 
    R " = Replicate                                                                                                             
      * = Comment (set/clear - if first char is * then comments are removed)                                                     
    < ( = Shift Line Left  (with protections to prevent loss of leading text)                                                   
    > ) = Shift Line Right (with protections to prevent loss of trailing text)                                                   


The colors used by SoulEdit for displaying journal entries are taken from your <var>SIRSCAN</var> profile. If you do not have a <var>SIRSCAN</var> profile, <var>SIRSCAN</var> default colors are used.


==See also==
==See also==
<ul>
<li>[[SirPro]] </li>


[[SirPro]]
<li>[[SirLib]] </li>


[[SirLib]]
<li>[[Model 204 full-screen editor]] </li>
</ul>


[[Category:Sirius Software products]]
[[Category:RKTools]]

Latest revision as of 22:56, 20 December 2017

SoulEdit is a code editor, written in SOUL, specifically designed for SOUL application development. SoulEdit features extended editing capability — like split/join, bookmarks, display filtering, and syntax-specific colors — as well as facilities that make running, debugging, and testing SOUL code more seamless and intuitive.

SoulEdit runs as an application subsystem, so it needs a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). RKTools installation contains more information about setting up the environment for SoulEdit.

SoulEdit is built into SirPro, one of the RKTools family of products from Rocket Software, and it is accessible from the SirPro TN3270 interface.

SoulEdit can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called SE, so it is executable from the command line. You can get information about setting up your own SoulEdit subsystem from the RKTools installation instructions for the RKTools subsystems.

SoulEdit requires Model 204 version 7.5 or higher.

Note: A video introduction to SoulEdit is available (for browsers other than IE/Edge): Introducing SoulEdit.


Overview

SirPro is a menu-driven application subsystem that provides tools for programmers, database administrators, and application managers inside the Model 204 environment. SirPro's primary feature set is centered on the manipulation of Model 204 procedures contained in Model 204 files.

You can access SoulEdit to edit a procedure in these ways:

  • From the SirPro 3270 interface, use the E prefix command before a procedure in a procedure list.
  • From the Model 204 command line (if SoulEdit is defined as a standalone subsystem, for example, SE), enter the subsystem name with a procedure name: SE MYPROCEDURE, where MYPROCEDURE is a procedure in the current file.

SoulEdit main editing screen

The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right is the range of line numbers, beginning with the current top-of-the-screen line number. The lines in the screen may be colored; colors are user-settable via the COLORS command.

Command line and PF key options for the TN3270 interface are described in the tables below.

One of the most useful features of SoulEdit is the ability to run a program with the GO command and immediately view the output in a scrollable Stringlist. If errors occurred while running, a series of AUDIT commands is available to display the audit trail output of the procedure you've just run.

Command line options

CommandResult
T[n] | TOP [n] | M+PF7 Go to the top of the editor content; optional n scrolls page so line-number n is at the top.
B | BOTTOM | M+PF8 Go to the bottom of the editor content.
C lineNumber Center the line specified by lineNumber. lineNumber is absolute, not relative.
+ | -numericValue Position content relative to the numeric value.
[-]F | Find value Find previous/next value from cursor position (PF5 repeats last find).
[-]/value Find previous/next value from cursor position (PF5 repeats last find).
R | REPLACE/replaceThis/withThis[[/n] ALL] Replace, where n specifies replacements per line. The character immediately following the R or REPLACE is used as a delimiter between tokens (cannot be alphanumeric).
A | ALL value Hide all lines that do not match value. A command without a value performs a SHOW ALL instead.
HIDE value Hide all lines that match value.
SHOW | HIDE COMMENTS Show or hide all comment lines.
UNHIDE value Unhide all lines that match value.
CLEAR HIDDEN | RESET HIDDEN Clear all hidden lines (unhide).
SHOW ALL | SHOW HIDDEN Clear all hidden lines (unhide).
GO Run the program, and capture the output into a scrollable screen.
[IN fileName ]GET procName Obtain the named procedure and insert into editor. You can use line command targeting.
SAVE [procName] Save current editor content (optional save into a different named procedure, including temporary procedures).
END Perform SAVE and exit the editor.
QUIT Exit the editor without saving or giving a modification warning.
ALIGN value Requires BB line command range (has issues when crossing "block" statements).
SORT [A | D | ASC | DESC | ASCENDING | DESCENDING] Requires BB line command range.
CLEAR Clear all line commands.
RESET PROC | RELOAD | RELOAD PROC Discards any changes by reloading the current procedure from file.
REFRESH PAGE Ignore any changes to this page since last enter.
NUM | NUMS | NUMBERS [ON | OFF] Show line numbers in prefix field (toggle).
= Repeat last command (same as PF9).
command stack (PF6) Cycles through the command stack.
SET COMMAND STACK n Defaults to 10; user may increase/decrease.
Split/join lines (PF2) Cursor sensitive: if no data from cursor, a join is performed; else split is performed.
FLIP HIDDEN Flip the hidden state of lines: hidden->shown && shown->hidden.
FF | BB+FORMAT - FORMAT [width] [INDENT n] Format range (indents and alignment). Not fully completed, but mostly functional.
UNDO FORMAT Reinstate the last FORMAT to its state before the format (does not check if code has changed).
SET FORMAT type Force the formatting type used by FORMAT/FF. Valid types: M204, XSL.
RUN (saves and runs code in a daemon)

RUN TERM (saves and runs code on current thread)

RUN [TERM] [procName [FILE filename [PASS password]]]
Output from the execution is scrollable (lost daemons are trapped and reported).
SHOW [ [RUN | OUTPUT] | RUN OUTPUT] Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES.
SHOW CHANGES Compares current content against procedure on file, and display in a scrollable form.
SHOW SEQ CHANGES Do compare against SEQ version in same procedure file.
SCALE (toggles on/off) |...+....1....+....2....+....3... etc.
PFKEYS (toggles on/off) Show valid PF keys on the last line of the page.
NEW PROC[EDURE] Clear current code (essentially a quit), and start with a blank procedure.
Formatting for XSL Change formatting where procedure name ends with .xsl.
HELP (PF1) Display Help text.
VAR | VARS | VARIABLES Show variable usage(counts) within scope.
SETUP | PROFILE Set user editor preferences.
COLORS Set user editor-color preferences.
.value Bookmarks. For example: .foo as a line command bookmarks the line. .foo as a command focuses the bookmark.
CLEAR BOOKMARKS Clear all bookmarks.
XCOMPARE | XC [EXACT | DEBLANK | COMPRESS] XCompares current content against procedure on file; displays in a scrollable form.
XCOMPARE SEQ | XCS [EXACT | DEBLANK | COMPRESS] Do XCompare against SEQ version in same procedure file (only works for SirLib users).
LAYOUT | MAP List all class/subroutines/functions. PF4 focuses entry from listing.
INCLUDES command Show hierarchy of all includes referenced within the current procedure.
PROTECT/UNPROTECT Force the displayed content to be protected/unprotected.
BB | BLOCK WHERE Add BB markers to the current "where" scope.
AUDIT [minutes | timestamp | LAST[RUN]] Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied.
SET FILE fileName Sets the file name for saving procedures; also clears the procedure name.
SNAP | SNAPSHOT Takes a copy of the code in the current editing session and saves it as snapshot.
XCB [previous-snapshot-offset] Compare the current code against the last snapshot taken.

Used in conjunction with the PF12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate the errors in the currently loaded procedure:

NE | NEXT ERROR Navigate to the next error.
PE | PREVIOUS ERROR Navigate to the previous error.
CE | CURRENT ERROR Navigate to the current error.
CLE | CLEAR ERRORS Clear the error bookmarks.

Line prefix commands

Block prefixes, with repeating ignored

CC Block copy (requires targeting prefix).
MM Block move (requires targeting prefix).
DD Block delete.
HH Block hide.
** Block comment (set/clear; first line is used to determine state switch. If first character is *, comments are removed).
BB Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.
FF Format the specified block. Sets indenting to the number of spaces specified in the user profile.

Block prefixes, with repeating honored

For example, ""3 replicates the block three times.

RR "" Block replicate
<< (( Block shift left (with protections to prevent loss of leading text)
>> )) Block shift right (with protections to prevent loss of trailing text)

Targeting prefixes

A Target after line
F Target following line
B Target before line
P Target previous line

Singular prefixes, with repeating ignored

C Copy (requires targeting prefix).
M Move (requires targeting prefix).
E Expand line to 255 bytes (toggles on/off).
/ Center this line.
- Folding of blocks; hide lines from marked line to closing/opening block.

Example: if -> end if...

X Expand/collapse INCLUDE inline. Only usable on INCLUDE lines. The expanded INCLUDE lines are protected.

Singular prefixes, with repeating honored

H Hide
S + Show
D Delete
R " Replicate
* Comment (set/clear; if first character is *, comments are removed)
< ( Shift line left (with protections to prevent loss of leading text)
> ) Shift line right (with protections to prevent loss of trailing text)

PF keys

PF1Help
PF2 Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.
PF3 Quit the editor without saving.
PF4
PF5
PF6 Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET.
PF7 Scroll up / use with M to scroll to top.
PF8 Scroll down / use with M to scroll to bottom.
PF9 Repeat previous command.
PF10 Shift+PF10 performs an ALL for the text under the cursor.
PF11 Creates/appends the value under the cursor to a traceText upon the following line.
PF12 Saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.

User-written extensions (SCMDs)

SoulEdit has a facility that lets you add command-line extensions to the editor.

As an example, INFO is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model 204 system method (output from a LoadSystemMethodInfo method call). If during an ordinary editing session you type info currenttimestring into the command line of SoulEdit:

User-defined command entered on command line

You see the output of the LoadSystemMethodInfo call displayed in a scrollable screen:

Pressing the PF3 key returns to the in-progress editing session.

The editor extensions are created via SCMD procedures stored in a user-designated file. You can see how INFO works by looking at procedure SCMD\INFO in the RKTools SIRIUS file.

To create your own commands, specify the procedure file where they will reside using the PROFILE command and Custom Macros File. SoulEdit scans this file for procedures prefixed with SCMD\ and loads them into memory at the beginning of the editing session. Copy SCMD\INFO into your Macros file with a new name, and customize the run method to your liking.

Timed backups

SoulEdit can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the PROFILE command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using PROFILE.

Auditing

SoulEdit has an auditing feature to list entries from the current journal. AUDIT options are:

AUDIT Lists the previous minute of the current journal.
AUDIT n n is a numeric value from 1 to 999 indicating how many minutes of the journal to display.
AUDIT HH:MI[:SS.XX] Lists the journal entries from the specified time. The colon (:) and period (.) are optional.
AUDIT LAST[ RUN] After a GO or RUN command runs a procedure from inside SoulEdit, AUDIT LAST shows all the journal entries pertaining to the job run. It excludes anything not associated with the GO or RUN. In addition to the journal entries for the thread, it also includes all child threads spawned by the GO or RUN thread.

The colors used by SoulEdit for displaying journal entries are taken from your SIRSCAN profile. If you do not have a SIRSCAN profile, SIRSCAN default colors are used.

See also