#  1. {Graphical User Interface}

   SPF/Pro differs from previous versions in a number of ways.  One of the
   more obvious is the  Graphical User Interface (GUI). The use of modern
   graphical user interface techniques enhances the SPF/Pro experience and
   contributes to increased user productivity.

   The basic display mechanism of the GUI is the Window. All functions of
   SPF/Pro are rendered in native mode windows of the operating system
   platform in use.

   The basic method of interaction with windows is the mouse. Keyboard
   equivalents are provided for all mouse operations.  See page     for
   further details on mouse operations.

   SPF/Pro is a Multiple Document Interface application.  In this
   architecture, you have a parent window and one or more child windows.  The
   child windows are displayed within the parent client space.

   Child windows within the parent client space may be maximized, normal, or
   minimized:

   *  In maximized state, the child window fully occupies the parent client
      space and the child title bar overlays the parent title bar.

      When using low resolution display monitors (e.g. VGA on notebook PC),
      this mode provides the greatest number of display lines and columns.

   *  In normal state, the child window may reside anywhere within the parent
      client space and be of any size equal or less than the parent.  In this
      case, the child window has its own title bar.

   *  In minimized state, the child window is reduced to an icon and
      positioned in the lower left corner of the parent client space.

   The default display mode for child windows is NORMAL.

   All windows are comprised of the following components:

   Window Frame

      The Window Frame is the outer border of the window.  The functional
      value of the frame is that it can be "grabbed" with the mouse and
      "stretched" or "shrunk" to alter the window size.  To resize the
      window:

      -  position the mouse cursor over any part of the window frame

      -  press and hold down the left mouse button

      -  move the mouse to achieve the desired size

      -  let the left mouse button up to finalize the new window size

      -  "pulling" or "pushing" on the left or right frame alters the width

      -  "pulling" or "pushing" on the top or bottom frame alters the depth

      -  "pulling" or "pushing" on any corner alters the width and depth
         simultaneously

   Task Control Button

      In the upper left corner of the window, there is a button which
      controls the SPF task. You can use this button to:

      -  Close the task and exit.

         Note: If you close from the main window, all SPF tasks are
         terminated.

      -  Restore, Move, Size, Minimize, and Maximize. These functions are
         accessible through alternate methods so we won't discuss them here.

   Title Bar

      At the top of the window is the Title Bar. It provides information
      about the task context.  For example, if you are in Edit, the title bar
      displays the Task ID (an integer number starting with one) and the name
      of the file being edited.

      In addition to providing information, the Title Bar is used to:

      -  Move the window:

         -- Position the mouse cursor over any portion of the Title Bar.

         -- Press and hold down the left mouse button while moving the mouse
            to move the window.

         -- Let the left mouse button up to finalize the new window position.

      -  Maximize the window

         -- double click on the title bar with the left mouse button.

   Min/Max Buttons

      On the upper right corner of the window:

      -  The MINIMIZE Button "shrinks" the window to the size of the SPF/Pro
         icon. You can use this button to keep SPF/Pro on the desktop for
         instant recall.  To recall SPF/Pro click on the "shrunken" icon.

      -  The MAXIMIZE Button increases the size of the window to occupy the
         full available space. Use this button when you want to display the
         maximum number of rows and columns of text possible.

         After maximizing, the MAXIMIZE button takes on a new form; this form
         is called NORMAL.  To return to normal window size from maximized
         size, click on the NORMAL (formerly MAX) button.

   Client Space

      The client space is where SPF panels are displayed. These panels
      contain text and graphical elements.

      -  Text fields defined in your panel definition are rendered as text.

      -  Input fields defined in your panel definition are rendered as
         concave three dimensional areas.

      -  Attention fields defined in your panel definition are rendered as
         three dimensional buttons. Text content of attention fields is
         rendered as the button legend.

   Scroll Bars

      To view data outside the viewable frame, scroll bars are provided:

      -  In tables and select lists, vertical scroll bars are provided.

      -  In Edit and Browse, both vertical and horizontal scroll bars are
         provided.

      -  In all other panel types, no scroll bars are provided.

      Note: Scroll bars may be enabled/disabled via Option 0.1.

   PFSHOW Bar

      PF keys are displayed at the bottom or top of the parent frame.  The
      number, display position, and starting key may be set via Option 0.1 or
      the PFSHOW primary command.

   Status Bar

      The status bar provides current information about the operating
      environment:

      -  Whether the system is busy.

      -  Whether you are in "macro recording" mode.

      -  The day of week, date, and time.

      -  The state of the SHIFT key.

      -  The state of the CAPS LOCK key.

      -  The state of the INSERT key.

      -  In tables, the current table row and column.

      -  In edit, the current file line and data column.

   Popup Menus

      Popup menus are available via right mouse button in various contexts
      during normal SPF/Pro operation. These menus provide a point and shoot
      activation scheme for frequently used commands.

      -  In file select lists, verbs that apply to the current selection

      -  In edit line command field, line commands that apply to the current
         selection

      -  In edit text area, primary commands that apply to the current
         selection

      -  In any other panel type, useful general commands

      Note:  You can add or modify popup menus on a per panel basis or
      reconfigure dynamically within a panel.

#  1.1 {Menu Bar}

   The menu bar provides native GUI operational mode.  You can perform many
   mainline SPF tasks directly off the menu without using SPF dialogs. The
   following menu commands are supported:

   FILE

      Perform file operations:

      New

         Open a new file in Edit.  The default name for new file is "*.*".
         Supply the desired name for your new file in the "File name" field
         of the dialog.  If you want a different directory, use the "Look in"
         navigator of the dialog to set the desired directory.

      Open for Edit

         Open an existing file in Edit.  The open file dialog is initialized
         with the name of the last file edited. If you want to edit a
         different file, supply the name in the "File name" field of the
         dialog.  If you want a different directory, use the "Look in"
         navigator of the dialog to set the desired directory.

      Open for Browse

         Open an existing file in Browse.  The open file dialog is
         initialized with the name of the last file Browsed or Edited.  If
         you want to edit a different file, supply the name in the "File
         name" field of the dialog.  If you want a different directory, use
         the "Look in" navigator of the dialog to set the desired directory.

      Save

         Saves the current edit file and continues in edit. Same as primary
         command SAVE.

      Save as

         Brings up the Windows common open dialog. Specify the new "File
         name" and press "SAVE". This creates the new file and a new edit
         session to edit it.

      End

         End the edit session and return to the previous panel.  If the file
         was modified, it is automatically saved.  Same as END primary
         command.

      End without Save

         Exit the edit session without saving the file. Same as CANCEL
         primary command.

      Print Setup

         This item invokes the Windows common printer setup dialog.  This
         dialog allows you to set a wide variety of printer properties. When
         you commit the settings via OK, the setup values are bound to the
         current SPF logical printer.

      Print Selection

         Prints the current selection. Same as SPRINT primary command.

      Print All

         Prints the entire file. Same as PRINT ALL primary command.

      MRU Edit List

         This is a list of the last 5 files Edited.  You can click on any one
         of them with the left mouse button to launch an Edit on the file.

      Exit

         Completely terminate SPF. Same as "=x" primary command.

   EDIT

      Perform edit operations:

      Undo

         Undo the last edit operation. Same as UNDO primary command.

      Redo

         Redo the last Undo operation. Same as REDO primary command.

      Cut

         Copy the current selection to the clipboard, then delete it from the
         edit file.  Same as SCUT primary command.

      Copy

         Copy the current selection to the clipboard. Same as SCOPY primary
         command.

      Paste

         Paste the current clipboard contents into the current edit file at
         the cursor. Same as SPASTE primary command.

      Delete

         Delete the current selection from the edit file. Same as SDELETE
         primary command.

      Find

         Find a string in the current edit file. Same as FIND primary
         command.

      Find next

         Repeat the last Find command. Same as RFIND primary command.

      Change

         Change one string to another in the current edit file. Same as
         CHANGE primary command.

      Change next

         Repeat the last change command. Same as RCHANGE primary command.

   WINDOW

      Organize windows and tasks:

      FSplit

         Start a new SPF task.

         -- In maximized state, the new task replaces the current task
            display.

         -- In normal state, the new task is created using the size of the
            current task and is displayed in cascaded stair-step fashion.

      Swap

         If more than one SPF task is active, swap to the next SPF task in
         the task ring.  If only one SPF task is active, process the command
         as an FSplit.

      Tile

         If more than one SPF task is active, arrange the SPF task windows
         side by side in a non-overlapped manner sharing the parent display
         space equally.

      Cascade

         If more than one SPF task is active, arrange the SPF task windows in
         an overlapped stair-step fashion in the parent display space.

      MRU Task List

         This is a list of all active SPF tasks.  You can click on any one of
         them with the left mouse button to activate it.

   HELP

      Access SPF/Pro online HELP:

      Help...

         Invoke the SPF Help dialog. This dialog lets you select help by
         topic and also allows dynamic searches.

      About

         Display information about SPF/Pro.

#  2. {Quickstart}

   While it is helpful, you do not need prior knowledge of IBM's mainframe
   based ISPF to use SPF/Pro. Reading this manual from front to back will
   give you an in depth understanding of all the facilities available to you
   but will also consume a lot of your valuable time.  A more effective
   approach for the uninitiated is to acquire a minimum working knowledge in
   a short time that will enable you to perform simple file editing tasks.
   This chapter will get you up and running in under one hour. As you use
   SPF/Pro in this minimal way you can explore the full range of functional
   capabilities described in the remainder of this manual at your leisure.

#  2.1 {Edit a New Empty File}

   You can now execute SPF/Pro to edit a file. For this exercise let's edit
   file TEST.TXT:

   *  Click on the SPF program group icon and/or the SPF program item icon to
      launch SPF/Pro.

      You are now in the Primary Option Panel.

   *  Type 2 in the "Option" field.

   *  Press [SPF-Enter] (the right [CTRL] key).

      You are now in the Edit Entry Panel.

   *  Use the mouse or the [TAB] key to position to the "System File
      Specification" field.

   *  Type TEST.TXT in the "System File Specification" field.

   *  Press [SPF-Enter].

   The top line of the client space displays the SPF Title Line. The Title
   Line is the first line of the body of each SPF Dialog. In the Edit Dialog,
   the name of the file you are editing is displayed on the left.  On the
   right are the starting and ending columns of the displayed portion of the
   file's records (usually 1 and 72). If you have records longer than 72
   characters, the characters from column 73 to the end of each record are
   not presently visible; we will talk about how to reveal them in another
   section.

   The second line is the Command Line. The first input field on the Command
   Line is the Primary Command Field where edit primary commands are entered.
   The second input field is the Scroll Field where scroll amounts are
   entered.  We will not modify the scroll field.

   The third and subsequent lines to the bottom of the client space are data
   lines.  The first six columns of each data line are the Line Command Field
   where edit line commands are entered.  The Line Command Field normally
   displays a six digit line number.  Column 7 is a boundary between the Line
   Command Field and the data area and is always blank.  Columns 8 through 79
   display columns 1 through 72 of each data record.

   The first and last data lines are not part of your file.  They are created
   by the editor to indicate that you are at the top or bottom of the file
   and are called the Top of Data and Bottom of Data lines respectively.

   You are currently editing new empty file TEST.TXT.  The cursor is setting
   in the Primary Command Field.  The top display line shows "TOP OF DATA".

   The bottom display line shows "BOTTOM OF DATA".  The intermediate display
   lines are empty.  Empty lines in SPF/Pro are called Null Lines and are
   indicated by six apostrophes in the Line Command Field.

   *  Press the [ENTER] key to get to the top line (TOP OF DATA).

   *  Press the [ENTER] key a second time to get to the first data line.

   *  Press the [TAB] key to get to the first data column (8).

   *  Type "This is a line of text."

   *  Press the [SPF-Enter] key to commit the text to the file.

      All the empty data lines were "closed up" when you pressed [SPF-Enter].

   *  Press [SHIFT][TAB] twice to position to the start of the display line
      (the Line Command Field of line 000001).

   *  Type "r99" in the Line Command Field.

   *  Press the [SPF-Enter] key to "replicate the current line 99 times".

      The file now contains 100 lines of "This is a line of text.".  We will
      use this sample file for the remaining exercises.

#  2.2 {Moving Around the Screen}

   The MOUSE can be used to position the cursor anywhere on the screen.
   Simply move the mouse pointer to the desired location and click the left
   mouse button one time. More advanced mouse capabilities and techniques are
   described elsewhere.

   You can also use the cursor keys to move left, right, up and down by one
   position. When you reach the edge of the display in any direction, the
   cursor leaves that edge and reappears at the opposite edge.

   The [ENTER] key moves you down one line and to the left edge of the screen
   in a single step.

   The [TAB] key moves you from screen column 1 (line command area) to screen
   column 8 (data area) in a single step.

#  2.3 {Executing Primary Commands}

   This section explains how to enter and execute primary commands which will
   be discussed in later sections.

   Move the mouse pointer on the Primary Command Field and click the left
   mouse button one time, or press the [HOME] key. Your are now in the
   Primary Command Field.

   *  Enter the primary command in the Primary Command Field.

   *  To execute:

      -  If you have an enhanced keyboard (101 keys), press the right [CTRL]
         key.  Hereafter this key is represented as [SPF-Enter].

      -  If you have a standard keyboard, press the ENTER key on the numeric
         keypad.  Hereafter this key is represented as [SPF-Enter].

      -  On any other keyboard type press [CTRL][ENTER].  Hereafter this key
         sequence is represented as [SPF-Enter].

#  2.4 {Executing Line Commands}

   This section explains how to enter and execute line commands which will be
   discussed in later sections.

   *  Use the mouse or the [ENTER] key and/or cursor keys to move the cursor
      to the Line Command Field of the line you want to operate on.

   *  Enter the line command in the Line Command Field.

   *  To execute press [SPF-Enter].

#  2.5 {Scrolling}

   To move up or down one full frame in the file use the [PG-UP] and [PG-DN]
   keys respectively.

   Function keys [F7] and [F8] are pre-programmed with the UP and DOWN
   primary commands respectively.

   To go to the top of the file in a single step enter and execute primary
   command:

   top

   To go to the bottom of the file in a single step enter and execute primary
   command:

   bot

   To reveal text not visible on the right enter and execute primary command:

   right

   To reveal text not visible on the left enter and execute primary command:

   left

   Function keys [F10] and [F11] are pre-programmed with the LEFT and RIGHT
   primary commands respectively.

#  2.6 {Summary 1}

   You now know how to:

   *  Edit a file.

   *  Travel around the screen using the mouse or cursor keys.

   *  Enter and execute primary and line commands.

   *  Scroll the file vertically using the [PG-UP] and [PG-DN] keys.

   *  Go to the top or bottom of the file in a single step using the "top"
      and "bot" primary commands.

   *  Go to the left or right edge of the data using the "left" and "right"
      primary commands.

#  2.7 {Overtyping Text in Existing Line}

   The default text entry mode is overtype. In overtype mode the cursor is
   shaped like a box. Simply move the cursor to the data portion of the
   record you want to change and type over the text you want replaced.

#  2.8 {Inserting Text in Existing Line}

   To insert text you must first put the editor into insert mode by pressing
   the [INS] key. In insert mode the cursor is a thin vertical line.  Now
   move the cursor to the data portion of the record you want to change and
   type the text you want inserted.

#  2.9 {Insert New Lines in Existing File}

   To insert a new line:

   *  Type "i" line command in the line above where you want a new line
      inserted.

   *  Press [SPF-Enter].

   *  A new line is inserted immediately below the "i" line.  The cursor is
      placed in the first data column.

   *  Type the desired data in the new line.

   If you would like more new lines immediately following the first:

   *  After entering text on the first new line and without any other
      intervening keystrokes, press [SPF-Enter].

   *  Another new line is inserted and the cursor is positioned at the first
      data column.

   *  Continue entering text. Repeat this process as required.

   After all data is entered, press [SPF-Enter] one more time to eliminate
   unused empty lines.

#  2.10 {Deleting Lines in Existing File}

   To delete a single line:

   *  Type "d" line command in the line you want deleted.

   *  Press [SPF-Enter].

   *  The line is deleted.

   To delete multiple lines:

   *  Type "dd" line command in the first line of the block of lines you want
      deleted.

   *  Type "dd" line command in the last line of the block of lines you want
      deleted.

   *  Press [SPF-Enter].

   *  The block of lines between the first "dd" and last "dd" inclusive is
      deleted.

#  2.11 {Summary 2}

   In the last information set you learned how to:

   *  Overtype existing lines.

   *  Insert text in existing lines.

   *  Insert new lines.

   *  Enter text in an empty file.

   *  Delete existing lines.

#  2.12 {Finding Text}

   If you don't want to manually search an entire file looking for a
   particular record, you can use the FIND primary command to get there in a
   single step.  For example,

   find line

   finds the first occurrence of the string "line" in upper, lower, or mixed
   case.

   If you want to find the next occurence of the same string press [F5].

#  2.13 {Changing Text}

   You can change the first occurrence of a string to another value with the
   CHANGE primary command. For example,

   change line bit

   changes the first occurrence of string "line" to "bit".

   To change the next occurence of the same string press [F6].

   change this bit all

   changes all occurrences of string "this" to "bit".

#  2.14 {Summary 3}

   In the last information set you learned how to:

   *  Find the first occurence of a string of text.

   *  Find the next occurence of the same string.

   *  Change the first occurrence of a string to another value.

   *  Change the next occurence of the same string.

   *  Change all occurrences of a string to another value.

#  2.15 {Copy Lines}

   To copy a single line:

   *  Type "c" line command in line to be copied.

   *  Type "a" line command in line preceding desired destination.

   *  Press [SPF-Enter]. Line with "c" is copied after line with "a".

   To copy multiple lines:

   *  Type "cc" line command in first line of block of lines to be copied.

   *  Type "cc" line command in last line of block of lines to be copied.

   *  Type "a" line command in line preceding desired destination.

   *  Press [SPF-Enter]. Block of lines between first line with "cc" and last
      line with "cc" inclusive is copied after line with "a".

#  2.16 {Move Lines}

   To move a single line:

   *  Type "m" line command in line to be moved.

   *  Type "a" line command in line preceding desired destination.

   *  Press [SPF-Enter]. Line with "m" is moved after line with "a".

   To move multiple lines:

   *  Type "mm" line command in first line of block of lines to be moved.

   *  Type "mm" line command in last line of block of lines to be moved.

   *  Type "a" line command in line preceding desired destination.

   *  Press [SPF-Enter]. Block of lines between first line with "mm" and last
      line with "mm" inclusive is moved after line with "a".

#  2.17 {Summary 4}

   In the last information set you learned how to:

   *  Copy a single line from one location in the file to any other location.

   *  Copy a block of lines from one location in the file to any other
      location.

   *  Move a single line from one location in the file to any other location.

   *  Move a block of lines from one location in the file to any other
      location.

#  2.18 {Saving Modified File}

   To save the file in its modified form, enter and execute primary command:

   save

   After the file is saved, editing can resume.

#  2.19 {Exit With Save}

   To save the file in its modified form and exit SPF/Pro, enter and execute
   primary command:

   =x

#  2.20 {Exit Without Save}

   To exit SPF/Pro without saving the file, enter and execute primary
   command:

   cancel

   At this point a panel is presented with a number of options; enter and
   execute primary command:

   =x

#  2.21 {Summary 5}

   In the last information set you learned how to:

   *  Save a modified file and continue editing.

   *  Exit a modified file saving all changes.

   *  Exit a modified file without saving changes.

#  2.22 {Epilogue}

   This chapter illustrates a minute portion of the functional capability of
   the Edit component of SPF/Pro.  After you become familiar with what you
   have learned here, examine the remainder of the book at your leisure.

   This chapter describes only the most orthodox methods. Frequently there
   are shortcuts to doing many of the operations discussed which you will
   learn over time.


#  3. {Introduction}

#  3.1 {Feature Summary}

   SPF/Pro is a complete integrated applications development environment for
   MVS legacy applications programs.  It is typically used for editing source
   code, invoking compilers, linkers, and debuggers, in a variety of
   programming languages, such as COBOL, FORTRAN, and C++. Of course SPF/Pro
   can be used with other programming languages and source files.

   SPF/Pro has many features designed to make managing and authoring source
   code easier, such as:

   *  Custom Dialogs interfacing to:

      -  Micro Focus

      -  XDB

   *  Fully graphical user interface

   *  PC based Partitioned Dataset support

   *  FIND/CHANGE in select lists

   *  FIND/CHANGE string highlighting

   *  MODEL support

   *  SUPERC file compare

   *  Undo/Redo

   *  Program source colorization

   *  Horizontal or Vertical screen SPLIT

   *  Multiple full screen SPLITs

   *  Multi-way select list file management

   *  Multiple-file search and replace

   *  Run Time Macro support via REXX

   *  Unlimited file size

   *  Programmable keyboard and keyboard macros

   *  Multiple character set and file format support

   *  Several tabbing modes, several line numbering modes

   *  Full integration with popular COBOL workbenches

   *  Extended, expanded, and virtual memory support

   *  CUT/PASTE via clipboard

#  3.2 {SPF/Pro Files}

   SPF/Pro uses several files during its processing:

   SPFPRO.EXE  (in SPFPRO)

      This is the main executable file for Windows-95, and Windows-NT.

   SPFPC50.GBL  (in SPFPRO\PROFILES)

      If not already present, this file is created at installation time.  It
      is updated whenever you change global profile variables. SPFPC50.GBL
      can load from:

      -  the default location

      -  the location specified in environment variable SPF5PATH

      -  the location specified in command option /G

         Note: If SPF/Pro can't find SPFPC50.GBL, it creates it with default
         parameters.

   *.PRF  (in SPFPRO\PROFILES)

      These files are not installation files.  They are created as you edit
      files, to record information about file formats.  Each .PRF file
      contains file format information which applies to all files with a
      particular type. For example, the file profile for program source file
      EDITCMD.CPP would be CPP.PRF.

      The *.PRF files are found and loaded in the same manner as SPFPC50.GBL.

   *.SPF  (in SPFPRO\REXX and SPFPRO\REXX\USER)

      These files are SPF/Pro edit macros which use ISREDIT macro commands.
      Edit macros included on the installation diskette are documented in
      README.MAC.  Edit macros you create must be located in in one of the
      following:

      -  SPFPRO\REXX

      -  SPFPRO\REXX\USER

      -  The directory specified in the MACRO SEARCH PATH field of the 0.8
         OPTIONS Menu. If multiple directories are specified, they must be
         separated by semicolons.

      -  The current directory.

      For more information on sample macros, see README.MAC in directory
      SPFPRO.

      Note:  Edit macros that have been precompiled, have the file type
      ".SP2" and reside in the same directories.

   *.ISP  (in SPFPRO\REXX and SPFPRO\REXX\USER)

      Dialog procedures are developed using ISPEXEC dialog services.  They
      follow the same rules for directory residence as the edit macro files.

      Note:  Dialog procedures that have been precompiled, have the file type
      ".IS2" and reside in the same directories.

   *.CLR  (in SPFPRO\PROFILES)

      These are program source colorization definition files.

   SPFCOLR.TBF  (in SPFPRO\PROFILES)

      When you create a named color setup using Option 0.4 it is stored in
      this file.

   SPFMRU.TBF  (in SPFPRO\PROFILES)

      When you edit files, the Most Recent Edits list is stored in this file
      and accessed via Panel 3.H.

   SPFUSER.TBF  (in SPFPRO\PROFILES)

      When you create a named user program using Option 4 it is stored in
      this file.

   SPFLIST.TBF  (in SPFPRO\PROFILES)

      When you save a select list via primary command SAVELIST, the name of
      the list is saved in this file.

   list-name.TBF  (in SPFPRO\PROFILES)

      When you save a select list via primary command SAVELIST, the list is
      saved in a file with the specified name. For example, if you "SAVELIST
      PROJECT1", the list is saved in file PROJECT1.TBF.

   *.TBF  (in SPFPRO\PROFILES)

      Tables created dynamicly with dialog services are kept in files of this
      type.

   *.KEY  (in SPFPRO\PROFILES)

      All named keyboard mappings created via 0.K are kept in files of this
      type.

   *.MAC  (in SPFPRO\PROFILES)

      When you create a named keyboard macro within a named keyboard via 0.M,
      the macro is saved in files of this type.

   *.PDS  (in SPFPRO\PAN)

      Panel definitions are normally stored in Partitioned Datasets.  Access
      to PDS files is through the special REXX API which we provide.

   *.PAN  (in SPFPRO\PAN and SPFPRO\PAN\USER)

      Panel definitions that are in development or frequently modified, are
      stored as individual PC files of this type.

   SPFPRO.MSG  (in SPFPRO\PAN)

      Base message definition file.

   SPFUSER.MSG  (in SPFPRO\PAN)

      User message definition file.

   README.DOC  (in SPFPRO)

      A text file on the distribution diskette which contains documentation
      developed after this document went to print.

   README.WIN  (in SPFPRO)

      Information specific to running SPF/Pro in the Windows environment.

   README.MAC  (in SPFPRO)

      Information specific to *.SPF macros supplied with SPF/Pro.


#  3.3 {Starting an SPF/Pro Session}

   Click on the SPF program group icon and/or the SPF program item.  This
   action loads SPF/Pro and puts you into the Primary Option Panel.

#  3.3.1 {Start-up Parameters}

   You can invoke SPF/Pro via "FILE" menu "RUN" or Command Window, with
   parameters which allow you to bypass the Primary Option Panel and go
   directly to a specific option:

   SPFPRO  [filename]
            [/Bfilename]
            [/E]
            [/Gglobal-profile-path]
            [/Iimacro-name]
            [/Kkeyboard-macro-name]
            [/L(line-number,col-number)]
            [/Pedit-profile-name]
            [/Rfile-name]
            [/Sdialog-function]
            [/T]
            [/n.n]

   The startup parameters are defined below:

   filename

      The name of a file to edit.  If wild-card characters are specified, a
      select list is presented for file selection.

      Note: filename may not be specified if "/B" or "n.n" is specified.

   /B

      The name of a file to browse.  If wild-card characters are specified, a
      select list is presented for file selection.

      Note: /B may not be specified if "filename" or "n.n" is specified.

   /E

      Exit directly to command prompt after edit.

   /G

      Specifies the path where the global profile will be found.  This
      overrides the value set in environment variable SPF5PATH.

   /I

      The name of an initial macro.  Can only be used with a specific
      filename.

   /K

      Specifies the keyboard macro name to execute on entry to SPF/Pro:
      /Kkeyboard-macro-name.

   /L

      Specifies line and column numbers in the following form:
      /L(line-number,col-number).

   /P

      The name of an edit profile.  Can only be used with a specific
      filename.

   /R

      The name of a compiler error message file.  This file is merged as
      NOTES into the edit file.  The compiler messages must be in what is
      generally known as "The Microsoft Format".  Among the compilers that
      support this format are the following:

         Micro Focus COBOL
         CA-Realia-II COBOL
         Borland C++
         Zortech C++
         Microsoft (all languages)

   /S

      The name of a dialog function to be used in place of the primary option
      panel.  The dialog function can take one of the following forms:

         /SPANEL(panel-id)[PARM(parameter-values)]
         /SCMD(REXX-procedure-name)[PARM(parameter-values)]
         /SCTC(internal-function-name)[PARM(parameter-values)]
         /SPGM(external-program-name)[PARM(parameter-values)]

      As an alternative to the /S startup command option you can set
      environment variable SPFSTART with a value identical to that which you
      would specify for /S and you would get the same result.  For example,
      issuing command

      SPFPRO  /SPANEL(MYPRIME)

      and setting

      SET SPFSTART=PANEL(MYPRIME)

      would have the same effect.  If /S is specified on the command line, it
      overrides the SPFSTART environment variable.

   /T

      Activates the profile trace for diagnostic purposes.

   /n[.n]

      The specific id of a panel you want to enter directly.

      Note: n.n may not be specified if "filename" or "/B" is specified.

      Note:  The older form  =n.n is still supported but its use is
      discouraged because if you use it in a command file (.BAT or .CMD) the
      equal sign is stripped off by the batch command processor yielding a
      syntax error.

   A few examples of the startup command follow:

   SPFPRO CONFIG.SYS [ENTER]

   SPFPRO C:\SRC\MAIN.C [ENTER]

   SPFPRO NEXNAME.COB /PDAT [ENTER]

   SPFPRO CKDATE.COB /ICOBINIT [ENTER]

   SPFPRO /BAUTOEXEC.BAT [ENTER]

   SPFPRO /3.4 [ENTER]

#  3.4 {Ending an SPF/Pro Session}

   When you have finished using SPF/Pro and are ready to end your session,
   you can:

   *  Press [F3] (END command) repeatedly, backing up through previous panels
      to the system prompt.

   *  Press [HOME], then type in the exit command, as follows:

      COMMAND ===> =X [SPF-Enter]

   *  Double click with the left mouse button on the close box for the SPF
      task you want to end.

   *  Select the FILE menu EXIT item with the mouse.

#  4. {Using the Mouse}

   This chapter describes how to use the mouse to:

   *  select a menu item

   *  select a PF key

   *  select a list entry

   *  operate on multiple list entries

   *  activate a popup menu

   *  scroll select list

   *  position the cursor

   *  select a group of lines

   *  select a stream of characters

   *  select a block (rectangular area)

   *  extend the selection

   *  perform [SPF-Enter] processing

   *  cancel selection

   *  delete the selection from the file

   *  cut the selection from the file to the clipboard

   *  copy the selection from the file to the clipboard

   *  paste the selection from the clipboard to the file

   *  create/replace an external file from the selection

   *  convert the selection to all uppercase letters

   *  convert the selection to all lowercase letters

   *  print the selection

   *  exclude the selection (applies to lines only)

   *  move the split separator

   *  sort file select list

   Using the mouse is most efficient when the primary commands that relate to
   the mouse are mapped to function keys or control keys. In the following
   discussion, we use function keys to describe how to do various operations
   in conjunction with the mouse. For our examples, the following mapping is
   used:

   [SHIFT][F1] = SCUT
   [SHIFT][F2] = SCOPY
   [SHIFT][F3] = SPASTE
   [SHIFT][F4] = SCREATE
   [SHIFT][F5] = SREPLACE
   [SHIFT][F6] = STOUPPER
   [SHIFT][F7] = STOLOWER
   [SHIFT][F8] = SXCLUDE
   [SHIFT][F9] = SDELETE

   See Keys Option 0.K for a description of how to map the keyboard.  You can
   map the mouse related primary commands in a manner which best suits your
   style.

#  4.1 {Select a Menu Item}

   Any time you are in an SPF/Pro menu, you can select a menu item by
   clicking on it with the left mouse button.

#  4.2 {Select a PF Key}

   Any time the PF keys are visible, you can select a PF key by clicking on
   it with the left mouse button.  Use the PFSHOW primary command to make PF
   keys visible.

#  4.3 {Select a List Entry}

   Any time you are in an SPF/Pro select list, you can invoke SELECT on a
   single entry by double-clicking on it with the left mouse button.

#  4.4 {Operate on Multiple List Entries}

   To operate on multiple list entries (e.g. a group of files):

   *  click on the line command field of the first entry in the block with
      the left mouse button

   *  enter the desired operation (e.g. S, E, etc.)

   *  press the shift key then click on the last entry in the block with the
      left mouse button

   *  press [SPF-Enter] to apply the line command you entered on the first
      entry to all the entries between and including first and last

#  4.5 {Activate Popup Menus}

   Popup menus are available in file select lists and edit to provide a
   convenient point and shoot activation scheme for frequently used commands.

   Click the right mouse button to activate the popup menu. Use the mouse to
   select the desired entry. Click the left or right mouse button to activate
   the command.

#  4.6 {Scroll Select List}

   Scroll the select list by clicking on the vertical scroll bar when
   present.

#  4.7 {Position the Cursor}

   You can position the character cursor anywhere on the screen by moving the
   mouse cursor to that position and clicking the left mouse button.

#  4.8 {Select a Group of Lines}

   A group of lines is one or more complete lines.  This is the most common
   form of selection when dealing with program source.  In EDIT or BROWSE to
   select a group of one or more lines:

   *  Use the mouse to position the cursor to the line command field of the
      first line in the block.

      Note: If line commands are turned off (see LCMD primary command),
      position to the first character in the line.

   *  Press down the left mouse button.

   *  With the left button still pressed and staying in the line command
      field, drag the mouse to the last line in the block. As you drag the
      mouse, the lines which become selected are highlighted.

      Note:  When you drag to the top or bottom edge of the display, EDIT (or
      BROWSE) automatically scrolls to extend the selection in the direction
      of travel.

   *  When you have reached the end of the selection, let the left mouse
      button up. The selection is now complete.

#  4.9 {Select a Stream of Characters}

   A stream is all the characters between the first character of the
   selection, in a continuous stream (including line ends), to the last
   character of the selection.  This is the most common form of selection
   when dealing with textual material.  In EDIT or BROWSE to select a stream
   of one or more characters:

   *  Use the mouse to position the cursor to the first character in the
      stream.

   *  Press down the left mouse button.

   *  With the left button still pressed, drag the mouse to the last
      character in the stream. As you drag the mouse, the characters which
      become selected are highlighted.

      Note:  When you drag to the top, bottom, left or right edge of the
      display, EDIT (or BROWSE) automatically scrolls to extend the selection
      in the direction of travel.

   *  When you have reached the end of the selection, let the left mouse
      button up. The selection is now complete.

      Note: Unlike word processors, SPF/Pro preserves line ends within stream
      selections.

#  4.10 {Select a Block}

   A block is a rectangular area.  This form of selection is used for special
   cases.  In EDIT or BROWSE to select a block:

   *  Holding the ALT key, click the left mouse button and drag to select the
      block.

   *  Use the mouse to position the cursor to the upper left corner of the
      block.

   *  Press down the right mouse button.

   *  With the right button still pressed, drag the mouse to the lower right
      corner of the block.  As you drag the mouse, the area which becomes
      selected is highlighted.

      Note:  You can also select from lower right to upper left.

   *  When you have reached the end of the selection, let the right mouse
      button up. The selection is now complete.

#  4.11 {Extend Selection}

   To extend the current selection without dragging, reposition the mouse,
   press the [SHIFT] key, then click the left mouse button. The selection is
   extended from the end of the current selection to the current mouse
   position.  This technique also works with a null selection.  (To extend a
   block selection, click on the right mouse button.)

#  4.12 {Cancel Selection}

   To cancel the selection, press any non-function key except [HOME] or click
   the left mouse button.

#  4.13 {Delete Selection}

   To delete the selection, press the [DEL] key or press the [SHIFT][F9] key
   (=SDELETE).  The deleted text is removed from the file but is not put into
   the clipboard.

#  4.14 {Cut Selection}

   To cut the selection, press the [SHIFT][F1] key, or [CTRL][X] (both are
   mapped to SCUT).  The selected text is copied into the clipboard; it is
   then removed from the file.

#  4.15 {Copy Selection}

   To copy the selection, press the [SHIFT][F2] key, or [CTRL][C] (both are
   mapped to SCOPY).  The selected text is copied into the clipboard; it is
   not removed from the file.

#  4.16 {Paste Selection}

   *  For line selections - place the cursor anywhere on the target line,

   *  For stream selections - place the cursor at the target character within
      the target line,

   *  For block selections - place the cursor at the upper left corner of the
      target area

   then press the [SHIFT][F3] key, or [CTRL][V] (both are mapped to SPASTE).

   After the paste operation, the cursor is positioned at the end of the
   pasted selection.  The contents of the clipboard are not altered.  To get
   multiple copies of the selection, repeat the paste operation.  This is
   essentially the same as the SPF/Pro replicate function.

#  4.17 {Create/Replace File}

   To create an external file from the selection press either [SHIFT][F4] key
   (=SCREATE) to create an original file or [SHIFT][F5] key (=SREPLACE) to
   replace an existing file.  A panel is presented in which you specify the
   name of the file that is being created.

#  4.18 {Convert to Uppercase}

   To convert the entire selection to all uppercase letters press the
   [SHIFT][F6] key (=STOUPPER).

#  4.19 {Convert to Lowercase}

   To convert the entire selection to all lowercase letters press the
   [SHIFT][F7] key (=STOLOWER).

#  4.20 {Print Selection}

   To print the selection, press the [SHIFT][F10] key (=SPRINT).  SPRINT
   prints only the selected characters.

#  4.21 {Exclude Selection}

   To exclude the selection, press the [SHIFT][F8] key (=SXCLUDE).  Exclude
   operates on whole lines regardless of the mode of selection.  If the
   selection is a stream or block, the exclude is applied to all characters
   of each line touched by the selection.

#  4.22 {Extend a Selection}

   As noted above, selections are normally extended by dragging the mouse
   while holding down the left mouse button. An alternative method of
   extending the selection is to:

   *  establish the origin of the selection by clicking the mouse at the
      desired start point.

   *  position the mouse to the desired end point of a selection (no drag
      required), then press [SHIFT] and click the left mouse button. The
      complete selection is now highlighted.

   *  You can append to an existing selection using this same technique.
      Position the mouse the the new desired end point. Press [SHIFT] and
      click the left mouse button. All text between the origin of the
      original selection and the new end point is now selected.

#  4.23 {Perform [SPF-Enter] Processing}

   At any time, double-clicking the left mouse button on a text entry panel
   (e.g. panel 2) produces the same effect as pressing [SPF-Enter].

#  4.24 {Move SPLIT Separator}

   If you have split the screen into multiple SPF/Pro sessions via SPLIT,
   SPLITV, or VSPLIT primary commands, you can move the split separator by:

   *  place the mouse cursor on the separator

   *  hold down the left mouse button

   *  drag the separator to the desired position

   When dragging the separator, SPF/Pro maintains a five line buffer zone
   from the top or bottom in the vertical direction, and a ten character
   buffer zone from the left or right in the horizontal direction.

#  4.25 {Sort File Select List}

   Above each column in file select lists is a labeled column sort button.
   To sort the file select list by that property (Name, Size, Date, etc.)
   click on the desired column sort button.

#  5. {Interacting With SPF/Pro}

   SPF/Pro functions are available to:

   *  Have full operation control of all elements of Micro Focus Workbench
      via custom SPF dialogs.

   *  Access XDB via extensive custom dialog.

   *  Browse or edit files.

   *  Manipulate files or directories.

   *  Set profile options.

   *  Launch foreground and background tasks.

   *  Issue operating system commands on PC.

   All SPF/Pro functions are performed via Graphical User Interface through
   SPF dialogs comprised of menus or panels.  One aspect of learning SPF/Pro
   is learning which menu or panel performs what functions and how to move
   among them.  This chapter explains how to:

   *  Use menus and panels.  Each panel tells you where you are and what you
      can do next.  The Menus and Panels section below identifies different
      panel types and how they are used.

   *  Use keyboard features.  In addition to typing in text, there are a
      number of keyboard features of interest.  These include 3270-type
      features, PF keys, and special purpose keys.

   *  Issue commands.  The Command section introduces different types of
      SPF/Pro commands, where to type them in, using commands together, and
      other general information.

#  5.1 {Menus and Panels}

   SPF/Pro menus and panels fall into basic categories:

   MENUS

      Menus display a list of available functions.  The functions are listed
      by number or letter.  You select one by either:

      -  positioning the mouse pointer on the desired entry, and clicking the
         left mouse button, or

      -  typing in the number or letter in the primary command field and
         pressing [SPF-Enter].

      When you select a menu item, SPF/Pro displays an entry panel or a lower
      level menu.

      Note:  Once you determine which panels are most frequently used, you
      can bypass the menus by using the "jump" feature.

   ENTRY PANELS

      Entry panels have fields for information which is needed to carry out a
      function.  Simply fill in the fields and press [SPF-Enter] to execute
      the function.  To position to fields either:

      -  position the mouse pointer on the desired field and click the left
         mouse button

      -  use cursor and/or tab keys to position to fields

   SELECT LISTS

      SPF/Pro displays a select list when you initiate a function that
      requires a filename but you only supply a path name or a partial
      filename (including wild-card characters).

      You would normally specify a partial filename intentionally to get a
      select list. For example, if you wanted to edit a group of related
      COBOL source files you would specify "*.COB" in the filename field of
      the EDIT ENTRY PANEL. This would bring up a select list of all the
      COBOL source files in the current (or project) directory.

      Once a list is displayed, you can select one or more files to edit,
      browse, or perform some other function. File selection can be done by
      either:

      -  positioning the mouse pointer on the desired list entry and double
         clicking the left mouse button, or

      -  cursor positioning to the desired entry, placing an "s" to the left
         of the entry, and pressing [SPF-Enter].

      -  Click the left mouse button once on the desired list entry.  Click
         the right mouse button to display a popup menu of verbs that can be
         applied to the selection.

      -  To select a block of entries, click once on the first entry of the
         block, position the mouse to the last entry in the block, press
         [SHIFT] and click the left mouse button.  You can now use the popup
         menu to apply a verb to all the entries in the block.

   FILE DISPLAY PANELS

      SPF/Pro brings up a file display panel when you request edit or browse
      and give a complete filename.  The file display panel includes fields
      for primary and line commands.

#  5.2 {General Features}

   This section describes features common to all panel types.  General
   features are discussed below.  Features unique to a single panel type are
   discussed in following sections.

#  5.2.1 {Display Topology}

   SPF/Pro panels are normally pre-defined to display in an 80 by 25 display
   space.  In Windows the display space is arbitrarily sized.

   If the available space is smaller than the panel definition calls for, the
   excess columns and/or lines are clipped (not displayed) although they are
   still part of the active panel.  In any case where a portion of the panel
   is not visible, you can MAXIMIZE the window to reveal the remainder of the
   panel.

   If the available space is larger than the panel definition calls for, the
   panel is displayed flush top left in the available space. Excess space is
   rendered in the protected-low attribute.

   The SCREEN primary command of previous versions, is no longer supported.

#  5.2.2 {Select Lists and File Displays}

   Select lists and file displays are often larger than the screen area.
   Select lists are arbitrarily long and can be scrolled vertically.  File
   displays are arbitrarily long and wide and can be scrolled both vertically
   and horizontally.

   Menus and panels have the following basic features:

   PANEL HEADING

      The top line of the display contains:

      -  On the left, the product name followed by an integer number which is
         the session id.

      -  In the center, the panel title.

      -  On the right, the product version number.

      EDIT and BROWSE display a file name in place of the panel name and
      column numbers in place of the product version number.

   SHORT MESSAGE AREA

      The short message area overlays the right edge of the top display line
      when necessary to display a message.  SPF/Pro uses this area to display
      information and diagnostic messages.

   COMMAND or OPTION FIELD

      The second display line on all menus and panels contains the primary
      command field labeled COMMAND or OPTION.  In either case you can enter
      general primary commands.  In the OPTION case you can select an item
      from the menu by number or letter.

      You can enter any of the general commands listed at the end of this
      chapter. On file display panels you can enter additional primary
      commands supported by EDIT or BROWSE.

   LONG MESSAGE AREA

      When SPF/Pro displays a short message, enter HELP (or [F1]) to display
      a more detailed message.  The long message overlays the third display
      line when necessary to display the message.

   STATUS LINE

      The bottom display line is the Status Line. It contains the following
      status indicators from left to right:

      -  INPUT INHIBITED, a special symbol indicates that the last input
         character was not accepted.  If the symbol has a small arrow on each
         side, you tried to type in a protected area such as a field name.
         If the arrow is only on the right side of the symbol, you tried to
         insert characters into a line or field that is full.

      -  SYSTEM BUSY, the text "X SYSTEM" indicates the system is busy.
         Keyboard input is queued until the last command completes.

      -  KEYBOARD MACRO RECORDING, the text "RECORDING" indicates that a
         keyboard macro is being recorded.

      -  DATE/TIME, an optional field displaying todays date and the current
         time.  Use Terminal Option 0.1 to set date and time options.

      -  SHIFT STATE INDICATOR is visible when the SHIFT key is down.

      -  CAPS LOCK INDICATOR is visible when the CAPS LOCK state is TRUE.

      -  INSERT INDICATOR is on when the INSERT state is TRUE.

#  5.2.3 {PFSHOW}

   An alternative mode of display is one in which some or all of the PF keys
   are displayed at the top or bottom of the screen along with their labels.
   This mode is invoked with the PFSHOW primary command.

   Key labels are either the first eight characters of the map value or an
   explicitly assigned label from the KEYS panel. See Option 0.3 or Option
   0.K for details on defining PF key mappings and labels.

   When the PF keys are visible they can be selected by positioning the mouse
   cursor to the desired key and clicking the left mouse button.

#  5.2.4 {Menus}

   Menus present you with a list of SPF/Pro functions.  For example, the
   Primary Option Panel. Some options on this menu, like 2, Edit lead
   directly to function panels.  Others, like 3, Utilities lead to a
   secondary menu, where other options are listed.

   In addition to common general features, a Selection Menu has an OPTION
   LIST which lists options by number or letter with a title and short
   functional description.  To select an Option:

   *  click on the Option button with the left mouse button

   *  type the number (or letter) of the Option in the OPTION field and press
      [SPF-Enter].

#  5.2.5 {Entry Panels}

   SPF/Pro displays an Entry Panel when a selected function needs information
   such as a filename to proceed.  Entry Panels have titled fields for all
   needed information.

   SPF/Pro often displays the fields with the last information you typed.
   This data is often preserved from session to session. For example, the
   file specification in the Edit Entry Panel is preserved across sessions.

   Entry panels for different purposes have different formats.  They all have
   the items listed below, in addition to general panel features.

   In addition to general features, an Entry Panel has the following
   features:

   INPUT FIELDS

      These are blank fields indicating needed information.  Input fields are
      rendered in 3D giving a visual queue to their function.  For example,
      in the Option 2, EDIT panel, the PROFILE field is an Entry Field.

      Some entry fields are scrollable. When you type past the end of the
      field, it scrolls instead of giving you input-inhibited.  For example,
      the primary command field is scrollable.

      The maximum amount of data that can be entered in a scrollable field is
      1024 characters.

   OUTPUT FIELDS

      Output fields derive their content from SPF variables that are
      specified in the panel definition. For example, the 0.1 Terminal Option
      contains a number of output fields indicating various aspects of the
      display technology.

   LABELS

      Input and output fields normally have labels and in some cases other
      explanatory information in the form of comments.  Labels clarify field
      content and may give additional information or instructions.

      Note:  On color monitors labels and fields may be displayed in
      different colors.

#  5.2.6 {File Specifications}

   Some input fields call for a PC file specification.  For convenience,
   SPF/Pro supports several forms of file specification which augment the
   conventional form DRIVE:\PATH\FILENAME. The following additional forms are
   supported:

   PATH;PATH

      You can specify multiple paths separated by semicolon or comma.  You
      can also include a file name if desired with each path element.  For
      example, to access all .COB and .CPY files in the \SRC\V1 directory:

      \SRC\V1\*.COB;\SRC\V1\*.CPY

      If all the files you want are in the current directory you can simply
      specify the file names:

      *.COB;*.CPY

   [PATH;PATH]filename

      In cases where you want to operate on a common set of files from single
      or multiple directories you can specify a path set enclosed in square
      brackets followed by a file name or names. For example,

      [\SRC\V1;\SRC\V2]*.COB;*.CPY

      In this example we are asking for all .COB and all .CPY files from the
      directories specified within the square brackets.

   %ENV-VAR%

      You can use this form of specification to refer to an environment
      variable. For example:

      %PATH%

      To request all .EXE files in all elements of the PATH environment
      variable:

      [%PATH%]*.EXE

      Or access all .CPY files in the COBCPY library set:

      [%COBCPY%]*.CPY

      Or access all .H files in the INCLUDE library set:

      [%INCLUDE%]*.H

#  5.2.7 {Select Lists}

   SPF/Pro displays a Select List when you request an operation on a file
   without specifying a file name or when you use wild card characters.  Wild
   card characters are asterisk (*) and question mark (?).  Normally you use
   wild card characters when you are not sure of the file name or want to
   work with a related group of files.

   When all the files in a list reside in the same directory, the common
   directory is shown on line three of the display.  The common path
   component of the file name is not repeated in the list.

   PANEL HEADING

      The top display line identifies the context for the select list.

   SCROLL FIELD

      On the right end of the second display line is the scroll field.  This
      field specifies how far the select list will be scrolled in response to
      UP, DOWN, LEFT, or RIGHT commands.

   CURRENT DIRECTORY

      The third display line identifies the active disk and subdirectory. If
      no disk or directory information is displayed with the file
      information, this is the location of all files in the list.

   FILE INFORMATION

      The fourth and subsequent display lines contain file information for
      all files that match your specification.  Individual files are listed
      by fields:

      -  When all files are in the same directory, the fields are:

            NAME
            EXTENSION
            SIZE
            DATE
            TIME
            ATTRIBUTES

      -  Attributes are indicated with single characters as follows:

         A - archive
         R - read-only
         S - system
         H - hidden

      -  When files are in different directories, the PATH field is appended
         to the basic entry.

   LINE COMMAND AREA

      Each file information line has a two character input field for entry of
      select list line commands.  You can enter single or double character
      line commands to do a variety of things to an individual file or group
      of files. For example, in the edit or browse select list, the S line
      command selects the file for editing or browsing.

   SCROLL BAR

      When select lists and other lists like 0.2 and 0.7 have more entries
      than can be displayed, a vertical scroll bar is displayed.

   Select lists are dynamic in nature. As the file name length increases the
   SIZE, DATE, and TIME fields are moved to the right to accommodate the
   longest name.

   In the case where the longest name is such that the SIZE, DATE, or TIME
   fields will not fit, the non-fitting field is clipped.

   At any time you can use the I (information) line command to bring up a
   panel containing a full elaboration of the file's name and other
   attributes.

#  5.2.8 {File Display Panels}

   SPF/Pro uses File Display Panels to display files for editing or browsing.
   The edit panel displays line numbers and supports a full range of editing
   commands.  The browse panel has no line numbers and supports a limited set
   of commands.  If the file is deeper or wider than the available display
   space, it can be scrolled UP, DOWN, LEFT, or RIGHT.

   In addition to general panel features, a file display panel has the
   following features:

   MODE INDICATOR

      On the left end of the top display line, a mode indicator BROWSE or
      EDIT is displayed to indicate which function you are in.

   PATH AND FILENAME

      Following the mode indicator, the fully qualified path name of the file
      being edited or browsed is displayed.

   COLUMNS

      At the right end of the top display line the start and end data column
      are displayed.  The COLUMNS display is updated whenever the screen is
      scrolled LEFT or RIGHT.  In the EDIT file display panel, columns 1
      through 6 display line sequence numbers, columns 8 and beyond display
      data commencing with data column one.  The COLUMNS display shows 1
      through N where N is the rightmost data column displayed.

      If some characters do not fit in the display area, you can scroll to
      reveal them with a "RIGHT" primary command.  The COLUMNS display is
      updated each time you scroll left or right.

      In browse mode, the current line number is displayed along with the
      column numbers.

   SCROLL FIELD

      At the right end of the second display line the scroll field specifies
      how far the file will be scrolled in response to UP, DOWN, LEFT, or
      RIGHT commands.

   LINE COMMAND AREA

      The first six character positions of each text line are available for
      entry of Edit Line Commands.  This area appears only on the edit panel.
      It has two purposes:

      1. It displays line sequence numbers (relative or absolute)

      2. You enter EDIT Line Commands here.

      By default line numbers are relative and incremented by 1.  Line
      numbers are updated whenever a line is inserted, deleted, or moved.
      See primary commands NUMBER, RENUM and UNNUM for details on other
      numbering methods.

      Line commands are one or more characters that allow you to mark one or
      more lines for insert, copy, move, or delete and many other line
      related operations.

   FILE TEXT AREA

      This is the data in your file displayed one record per line.  You can
      scroll UP, DOWN, LEFT, or RIGHT as desired to reveal other areas of the
      file. By default EDIT is in overtype mode so you can simply type
      anywhere in the text area to make desired changes.  The [DEL] key
      deletes characters, and the [INS] key toggles the insert state.

      BROWSE does not allow modifications to the file.

   ROW/COLUMN INDICATOR

      At the right end of the status line the file line number (R) and column
      number (C) for the current cursor position is displayed.  These
      indicators are only displayed when in EDIT or BROWSE.

#  5.2.9 {Scrolling}

   Scrolling is moving the viewport into a file or select list UP, DOWN, LEFT
   or RIGHT.

   There are four ways to issue a scroll command:

   1. Use the [PG-UP] or [PG-DN] key.

   2. Use one of the pre-assigned PF keys:

      [F7]  -  UP
      [F8]  -  DOWN
      [F10] -  LEFT
      [F11] -  RIGHT

   3. Type it in the command field and press [SPF-Enter].

   4. Click on the desired arrow or move the slider of a scroll bar.

#  5.2.10 {Scrolling Amount}

   The amount you move with any scroll command is determined by the scroll
   field.  You can change the scroll amount any time by typing over it.  The
   scroll amount may also be typed in directly with any scroll command.
   Valid scroll values are listed below:

   PAGE (P)

      Scroll by the full dimension of the display area.  Vertically by the
      depth in lines of the display area.  Horizontally by the width in
      columns of the display area.

   HALF (H)

      Scroll by one half the amount of PAGE.

   CSR (C)

      Scroll to move the cursor to the edge of the display area.

      -  For UP, data is moved to place the cursor at the bottom edge of the
         display area.

      -  For DOWN, data is moved to place the cursor at the top edge of the
         display area.

      -  For LEFT, data is moved to place the cursor at the right edge of the
         display area.

      -  For RIGHT, data is moved to place the cursor at the left edge of the
         display area.

   DATA (D)

      Scroll by the amount of PAGE minus one line in the vertical, or minus
      one column in the horizontal.

   MAX (M)

      Scroll the maximum amount in the direction indicated.  MAX is reset to
      the original amount after the scroll is completed.

   In the vertical direction MAX is used to get to the top or bottom of the
   file or select list.

   In the horizontal direction MAX is used to get to the leftmost or
   rightmost data column.

   nnnn

      Scroll by nnnn lines or columns in the direction indicated.

   To temporarily override the scroll amount:

   *  Type a command and an amount in the command field.  For example, UP 10.

   *  Easier yet, type an amount in the command field and issue the scroll
      command with a function key.  For example, type 10 in the command
      field, and press [F7] for UP.

   Note:  In addition to scrolling, you can use:

   *  LOCATE and SELECT commands to position in select lists

   *  FIND, LOCATE, SELECT and LABEL commands to position in files

#  5.3 {Moving Between Menus and Panels}

   When you first start using SPF/Pro you will move from panel to panel
   invoking functions in a serial fashion. This technique is fine but may not
   be the most efficient for all cases. After you learn which panels are most
   frequently useful to you, you can go to and from panels directly using the
   techniques discussed below:

   *  Use the jump feature to go directly to a panel by typing =n or =n.n in
      the command field followed by [SPF-Enter].  You can use this feature in
      a random manner from any panel.  For example, to go directly to the

      UTILITIES, FILE LIST panel type =3.4 in the command area and press
      [SPF-Enter].

      Note:  After using the jump feature, the END command returns to the
      Primary Option Panel.

   *  Use the RETURN command (normally [F4]) any time to return directly to
      Primary Option Panel regardless of your current position in the menu
      tree.

   *  There are also startup options that allow you enter directly into EDIT,
      BROWSE, or any panel.

#  5.4 {Split Screen}

   This feature allows you to launch multiple independent copies of SPF/Pro.
   You can launch multiple copies of SPF/Pro in one of three modes:

   *  HORIZONTAL SPLIT - one session above, one session below.  To do a
      horizontal split, position the cursor to the desired split point, then
      press [F2] or use the SPLIT primary command.  Limit: two sessions.

   *  VERTICAL SPLIT - one session on the left, one session on the right.  To
      do a vertical split, position the cursor to the desired split point,
      then use the VSPLIT primary command.  (We also support the mainframe
      SPLITV primary command which always splits in the middle regardless of
      the cursor position).  Limit: two sessions.

   *  FULL SCREEN SPLIT - multiple copies occupying the full display space,
      the active session is visible.  To do a full screen split, use the
      FSPLIT primary command.  Limit: specified in Terminal Option 0.1.

      If no split has been done, you can effect a full screen split by simply
      pressing [F9] (SWAP).

   We refer to all forms of multi-session operation as split screen.  Each
   session is a complete task that allows you to use all SPF/Pro features and
   functions.  The session ID, an integer from 1 to N, is displayed after the
   product name at the left edge of the title line.

   In discussions of split screen, the task where the cursor is located is
   called the active task. Any command you issue is applied to the active
   task.

   Some things you can do with multiple sessions are:

   *  Edit two files at once, which is useful when you use the editor's
      cut-and-paste feature.

   *  Edit a file in one task and execute a utility program or compiler in
      the second task.

   *  Use an SPF/Pro feature in one task and use the command processing panel
      to issue operating system commands from the second.

   After you split the screen, use the SWAP command (normally [F9]) to switch
   between the tasks.

   If you are in horizontal split mode, and one of the sessions is less than
   five lines deep, SWAP reallocates the screen so that the active task
   always has the greater number of display lines.

   If you are in vertical split mode, and one of the sessions is less than
   ten columns wide, SWAP reallocates the screen so that the active task
   always has the greater number of columns.

   After splitting in one mode you can switch to the other mode by simply
   issuing the opposite split command.

   To change from horizontal split mode to vertical issue the VSPLIT or
   SPLITV command.

   To change from vertical split mode to horizontal issue the SPLIT command.

   To end split screen mode, simply [F3] out, or =X out of either task. The
   remaining task will occupy the full screen.

#  5.5 {SPF/Pro Commands}

   In previous sections we discussed menus and panels. We will now cover
   SPF/Pro commands. This section of the manual introduces three types of
   commands, and explains some of the rules for using commands: where to type
   them, how to use more than one command, how to stack commands, etc.

#  5.5.1 {Types of Commands}

   SPF/Pro commands are classified by where you type them:

   *  Primary commands are typed in the field labeled COMMAND or OPTION.
      These commands affect the panel, the function, the file, or your entire
      session.

   *  Line commands are typed in the input field at the left end of lines in
      files or select lists. This input field is called the Line Command
      Field.  These commands affect a single file or group of files in select
      lists, or a single line or block of lines in edit.

   You can also execute operating system commands without leaving the SPF/Pro
   environment.

#  5.5.2 {Issuing Commands}

   General rules for using each type of command are summarized below:

   *  Primary commands.  To issue a primary command, use the mouse or [HOME]
      key to move the cursor to the COMMAND or OPTION field.  Type in the
      command.  If the command requires a parameter, or you use an optional
      parameter, type it after the command.  Press [SPF-Enter].

   *  Line commands.  To issue a line command, use the mouse or cursor keys
      to position the cursor to the Line Command Field of the desired line,
      type in the command; press [SPF-Enter].

   *  To operate on a block of lines or group of files, type the desired line
      command on the first line in the block; move to the end of the block
      (use [F8] or [PG-DN] if necessary); then type the same line command on
      the last line in the block; press [SPF-Enter].

   *  In Edit, ISREDIT macro commands are invoked in the same manner as
      primary commands.  You can also use the IMACRO feature to execute a
      specific macro once at the time the file is opened.

   *  Operating system commands.  These are standard operating system
      commands that you normally enter at the operating system command
      prompt.  To issue an operating system command, use the mouse or [HOME]
      key to move the cursor to the command or option line, type in DOS
      followed by the command.  If the command requires a parameter or you
      use an optional parameter, type it after the command.  Press
      [SPF-Enter].

   *  PF keys.  After you have used SPF/Pro for a while and know which
      commands you use regularly, you can assign them to PF keys.  Then they
      can be executed with a single keystroke.

#  5.5.3 {Command Stacking}

   To invoke multiple related commands, enter the commands separated by
   semicolon (;), then press [SPF-Enter].  SPF/Pro executes the commands in
   the order in which you typed them.

   If an error occurs, the command in error remains in the primary command
   field.

#  5.6 {Using Your Keyboard With SPF/Pro}

   There are a number of single-keystroke functions on your keyboard.  Some
   of these are standard PC functions, others are unique to SPF/Pro. All are
   listed in this section.  In all cases the key assignment may be changed
   using Option 0.K, Keyboard Mapping.

#  5.6.1 {General Keys}

   [SPF-Enter]

      This symbol is used throughout SPF/Pro documentation to identify the
      equivalent to the 3270 ENTER key.  This key activates all SPF/Pro
      functions.

      This key does not actually exist on any PC keyboard so we use the
      following keys to effect [SPF-Enter]:

      -  For 101 key enhanced keyboard use:

         -- Right [CTRL] key, or

         -- [ENTER] key on the numeric keypad, or

         -- Left [CTRL] + [ENTER] key

      -  For AT-style keyboard use:

         --  key on numeric keypad, or

         -- Left or Right [CTRL] + [ENTER] key

      To get SPF/PC v. 2.1 style ENTER processing you must select the "SPF/PC
      2.1" keyboard scheme in Keyboard Options 0.K.  The default setting for
      this keyboard differs from the standard 3270 approach in that the
      [ENTER] key does newline processing AND 3270-ENTER processing.

   [BACKSPACE]

      Use this key to move the cursor to the left.  The default backspace is
      non-destructive.  You can assign the destructive form of backspace with
      Option 0.K, Keyboard Mapping.

   [DEL]

      Use this key to delete characters at the cursor; characters to the
      right of the cursor are shifted left one position.

   Left-[CTRL]

      When pressed by itself, the left [CTRL] key performs a 3270 RESET.

   [CTRL][DEL]

      Use this combination of keys to erase characters from the current
      cursor position to the end of the field or line. See 0.1 for an
      alternative key configuration for this function.

   [INS]

      Use this key to toggle insert mode. If insert is on, characters to the
      right of the cursor are moved farther to the right as new characters
      are typed.  Otherwise new characters overlay current characters as they
      are typed.  If a line or field is full, attempting to insert new
      characters causes a beep and an input inhibited indicator in the status
      line.

   [NUMLOCK]

      Use this key to set the shift state of the numeric keypad.  The Num
      Lock indicator is displayed when numeric lock is on.

   [ESC]

      Use this key to restore entry fields to their original values.  This is
      equivalent to an UNDO of the text typed since the last [SPF-Enter].

#  5.6.2 {Traveling Keys}

   [ENTER]

      Use this key to move from line to line or field to field.  If there is
      more than one field on a single line, use the [TAB] key to position to
      the next field, described below.  If the cursor is in the last line or
      field, it wraps around to the top of the screen when you press the key.

   [HOME]

      Use this key to move the cursor to the command/option field.  The
      CURSOR command also performs this function.

   [END]

      Use this key to move the cursor to the end of the current field. When
      you press the key, the cursor moves to the blank space following the
      last character in the field. If the field is blank, the cursor is
      positioned at the beginning of the field.

   [PG-UP]

      Use this key to scroll up toward the top of the file or select list.
      The amount of the scroll is determined by the scroll field.  [F7] can
      also be used to scroll up.

   [PG-DN]

      Use this key to scroll down toward the bottom of the file or select
      list.  The amount of the scroll is determined by the scroll field.
      [F8] can also be used to scroll down.

   [CTRL][PG-UP]

      Use this key to scroll to the top of the file.

   [CTRL][PG-DN]

      Use this key to scroll to the bottom of the file.

   [ARROW-UP]

      Use this key to move the cursor up. If you set VERTICAL SCROLL W/CURSOR
      on Editor Options panel, the screen scrolls in the direction that the
      cursor is moving when the cursor reaches the edge of the screen.

   [ARROW-DOWN]

      Use this key to move the cursor down. If you set VERTICAL SCROLL
      W/CURSOR on Editor Options panel, the screen scrolls in the direction
      that the cursor is moving when the cursor reaches the edge of the
      screen.

   [ARROW-LEFT]

      Use this key to move the cursor left. If you set HORIZONTAL SCROLL
      W/CURSOR on Editor Options panel, the screen scrolls in the direction
      that the cursor is moving when the cursor reaches the edge of the
      screen.

   [ARROW-RIGHT]

      Use this key to move the cursor right. If you set HORIZONTAL SCROLL
      W/CURSOR on Editor Options panel, the screen scrolls in the direction
      that the cursor is moving when the cursor reaches the edge of the
      screen.

   [ALT][ARROW-LEFT]

      Use these keys to move the cursor two characters to the left.

   [ALT][ARROW-RIGHT]

      Use these keys to move the cursor two characters to the right.

   [CTRL][ARROW-LEFT]

      Use these keys to move the cursor one word to the left (word jump).

   [CTRL][ARROW-RIGHT]

      Use these keys to move the cursor one word to the right (word jump).

   [TAB]

      Use this key to move the cursor to the next tab position in edit or
      field in a panel.

   [SHIFT][TAB]

      This is the backtab key. It works in the opposite direction of the tab
      key, moving to the previous tab position or field.

#  5.6.3 {Selection Keys}

   [SHIFT]+arrow-key

      Use the shift key in conjunction with an arrow key in place of the
      mouse to do selections.

      Pressing [SHIFT][ARROW-UP] is equivalent to pressing the left mouse
      button and dragging the mouse up.

      Pressing [SHIFT][ARROW-DOWN] is equivalent to pressing the left mouse
      button and dragging the mouse down.

      Pressing [SHIFT][ARROW-LEFT] is equivalent to pressing the left mouse
      button and dragging the mouse left.

      Pressing [SHIFT][ARROW-RIGHT] is equivalent to pressing the left mouse
      button and dragging the mouse right.

#  5.6.4 {PF Keys (Enhanced Keyboard)}

   [F1]-[F12]

      Base PF keys PF1 through PF12.

   [SHIFT][F1]-[F12]

      The SHIFT form of the base PF keys are used to effect PF13 through
      PF24.

   [CTRL][F1]-[F12]

      The CTRL form of the base PF keys are used to effect PF25 through PF37.

   [ALT][F1]-[F12]

      The ALT form of the base PF keys are used to effect PF37 through PF48.

#  5.6.5 {PF Keys (AT Keyboard)}

   [F1]-[F10]

      Base PF keys PF1 through PF10.

   [SHIFT][F1]-[F10]

      The SHIFT form of the base PF keys are used to effect PF11 through
      PF20.

   [CTRL][F1]-[F10]

      The CTRL form of the base PF keys are used to effect PF21 through PF30.

   [ALT][F1]-[F10]

      The ALT form of the base PF keys are used to effect PF31 through PF40.

#  5.6.6 {PF Keys, General}

   The PF keys can be used to issue an SPF/Pro command in a single keystroke
   and without moving to the command field.  There is a default set of
   SPF/Pro commands assigned to your PF keys.  You can change the PF key
   mappings any time with the KEYS command.

   The default settings of the PF keys are listed below:

               3270 Style    SPF/PC 2.1

      PF1   -  HELP          HELP
      PF2   -  SPLIT         SPLIT
      PF3   -  END           END
      PF4   -  RETURN        SWAP
      PF5   -  RFIND         RFIND
      PF6   -  RCHANGE       RCHANGE
      PF7   -  UP            UP
      PF8   -  DOWN          DOWN
      PF9   -  SWAP          LEFT
      PF10  -  LEFT          RIGHT
      PF11  -  RIGHT         RETURN
      PF12  -  RETRIEVE      RETRIEVE
      PF13  -  SCUT          n/a
      PF14  -  SCOPY         n/a
      PF15  -  SPASTE        n/a
      PF16  -  SCREATE       n/a
      PF17  -  SREPLACE      n/a
      PF18  -  STOUPPER      n/a
      PF19  -  STOLOWER      n/a
      PF20  -  SXCLUDE       n/a
      PF21  -  SDELETE       n/a
      PF22  -  n/a           n/a
      PF23  -  n/a           n/a
      PF24  -  n/a           n/a

      PF25-PF36  Repeat PF1-PF12
      PF37-PF48  Repeat PF1-PF12

   To execute one of these commands simply press the appropriate PF key (or
   combination of [SHIFT], [ALT] or [CTRL] and PF key).

   To pass a parameter to a PF key simply type it in the command field, then
   press the PF key.  For example, if you type 4 in the command field and
   then press [F7], it is equivalent to executing the command "UP 4".


#  6. {Directories and Files}

   In addition to the familiar services offered by the mainframe based ISPF,
   SPF/Pro provides a rich set of enhancements to manipulate files.

   You can use SPF/Pro's powerful file management system, to work with
   operating system directories and files in ways not available on the
   mainframe.  File management functions are supported through panels, and
   select lists. There is no need to issue operating system commands.  Using
   select lists you can apply various operations to individual files or
   groups of files.

   Standard ISPF file list line commands:

   *  Select

   *  Browse

   *  Edit

   *  Print

   *  Rename

   *  Delete

   *  Move

   *  Copy

   *  Information (display properties)

   Additional SPF/Pro file list line commands:

   *  Go (execute program or batch file)

   *  Tree (create recursive sub-list)

   *  User (apply user command)

   *  Convert (one format to another)

   *  Exclude (prune list)

#  6.1 {Basic BROWSE/EDIT Operation}

   *  Select Browse or Edit from the Primary Option Panel.

   *  SPF/Pro displays an entry panel.

   *  In the PROJECT FILE or SYSTEM FILE SPECIFICATION field enter the fully
      qualified path name for the directory containing files that you would
      like to operate on. For example,

      C:\SOURCE\COBOL\*.COB

   *  SPF/Pro displays all files that match your specification in a select
      list. You can now apply operations to individual files.

   *  You can use the SORT command to order the list by name, extension,
      date, time, size, or attributes.

   *  You can use the LOCATE command to find specific entries.

   *  You can use [PG-UP], [PG-DN], [F7], [F8] to scroll the list.

   *  Select a file to BROWSE or EDIT by placing an "s" in the line command
      field of the individual file entry.

      To edit a new file, use the SELECT primary command (e.g. "s new-name").
      After EDIT, the new file's name is automatically added to the list.

   *  When you press [SPF-Enter] SPF/Pro invokes BROWSE or EDIT on the
      selected file.

   *  If you issue an S (Select) line command on a subdirectory entry,
      SPF/Pro presents a corresponding select list. You can continue to
      select subdirectories in this manner as desired all the way down the
      subdirectory tree.

   *  When you complete your operation:

      -  press [F3] to return to the select list, or

      -  press [F4] to return to the Primary Option Panel

#  6.2 {Basic UTILITIES Operation}

   The UTILITIES function (Primary Option 3) provides additional file
   manipulations beyond BROWSE and EDIT.

   *  Select Utilities (3) from the Primary Option Panel.

   *  Select File List (4).

   *  SPF/Pro displays an entry panel.

   *  You can now perform the same steps as you did for BROWSE and EDIT above
      to create a select list of files that you would like to manipulate.

   *  In the Utilities File List, you place line commands on individual file
      entries to perform specific operations.

   The Utilities File List duplicates the functions of BROWSE and EDIT.
   Operating from the Utilities File List provides a lot of convenience and
   we highly recommend it.

#  6.3 {Super Lists}

   If you really want to step up in power and flexibility, super lists
   provide the most comprehensive set of functions available through a single
   interface point.

   Super lists extend the Utilities concept in a variety of ways:

   *  You can create a super list by searching:

      -  recursively

      -  across drives

      -  for a specific text string

      -  for directories only

      -  for files only

      -  for directories + files

      in any combination!

   *  Once you have created a super list, you can:

      -  add entries via primary command INSERT.

      -  subtract entries via primary command EXCLUDE.

      -  preserve entries via primary command INCLUDE (inverse of EXCLUDE).

      -  create a subset list of files containing a specific text string via
         primary command FIND.

      -  change one string to another in all files in the list via primary
         command CHANGE.

      -  save the list under a symbolic name for later use via primary
         command SAVELIST (a micro-project).

   *  Super lists support the extended line command set.

   *  Super lists support block operations for all line commands.

   *  Super Lists maintain the focus after an operation.  In ISPF if you P
      (print) a file, after the print is complete, the list is scrolled to
      place the printed file entry at the top and the cursor is placed in the
      primary command field.  In Super Lists, the list is not scrolled and
      the cursor remains in place.

   *  To eliminate ISPF style audit trails in select lists go to Option 0.6,
      set CLEAR LISTS = Y.  Example: if you delete a file, instead of
      flagging the entry with "DELETED", the entry is simply deleted from the
      list.

   *  To enable full super list line command set in all select lists go to
      Option 0.6, set EXTENDED LINE COMMANDS = Y.

#  6.4 {Popup Menu}

   For convenience, a popup menu containing the most frequently used select
   list line commands is available with a click of the right mouse button.

   For a operation on a single entry in the list, simply move the mouse
   cursor to the desired entry, click the right mouse button, and select the
   desired operation.

   To operate on multiple entries, move the mouse cursor to the first entry,
   click the left mouse button once to highlight the entry, move to the last
   entry in the block, click the right mouse button to complete the selection
   and display the popup menu.  Select the desired operation with a single
   click of the left mouse button.

#  6.5 {Entry Panel}

   The Printer Characteristics panel is a typical example of most entry
   panels.  Browse, Edit, and Utility entry panels look slightly different,
   but all use the same file specification rules.

   As previously stated, you can use the file specification fields to select
   a single file, a group, or an entire directory.

   SPF/Pro entry panels have two places to type a file specification.  These
   two forms give you maximum flexibility in identifying the file you want to
   work with.

   The PROJECT FILE field allows you to type a file specification in a
   structured format.

   Unlike standard operating system file specifications, the PROJECT FILE
   begins in the root directory regardless of the operating system current
   directory.

   On any PATH field you can enter multiple path elements separated by a
   backslash.  You can also type path elements without an initial backslash.
   In all cases SPF/Pro insures that the path specification you enter begins
   with backslash and does not end with backslash.

   The project file fields can be displayed either vertically (the default)
   or horizontally depending on the setting of File List Options 0.6.  The
   two forms are displayed below:

   PROJECT FILE:
      DRIVE ===> c:
      PATH  ===> \a
      PATH  ===> \b
      PATH  ===> \c
      NAME  ===> *.cob

   PROJECT FILE:
      DRIVE ===> c:
      PATH  ===> \a   PATH  ===> \b   PATH  ===> \c
      NAME  ===> *.cob

      There is an implied backslash preceding the NAME field's contents; it
      is never displayed.

   The following example shows how you can move back and forth between the
   program source of two related versions with a difference of one keystroke
   (v1 vs. v2) in the file specifications:

   PROJECT FILE:                 PROJECT FILE:
      DRIVE ===> c:                 DRIVE ===> c:
      PATH  ===> \v1                PATH  ===> \v2
      PATH  ===> \src               PATH  ===> \src
      PATH  ===>                    PATH  ===>
      NAME  ===> *.cob              NAME  ===> *.cob

   You can also request different subdirectories in a similar way.  Changing
   the second PATH field from \src to \doc, for example, would give you
   access to the project documentation files.

   PROJECT FILE:                 PROJECT FILE:
      DRIVE ===> c:                 DRIVE ===> c:
      PATH  ===> \v1                PATH  ===> \v1
      PATH  ===> \src               PATH  ===> \doc
      PATH  ===>                    PATH  ===>
      NAME  ===> *.cob              NAME  ===> *.doc

   Within a subdirectory the file subset is also easily changed.  For
   example, in the NAME field, a "C" program's source is accessed with *.c;
   its data structures with *.h.

   PROJECT FILE:                 PROJECT FILE:
      DRIVE ===> c:                 DRIVE ===> c:
      PATH  ===> \v1                PATH  ===> \v1
      PATH  ===> \src               PATH  ===> \src
      PATH  ===>                    PATH  ===>
      NAME  ===> *.c                NAME  ===> *.h

   You can also specify two or more file types in the NAME field separated by
   semicolon or comma. For example:

   PROJECT FILE:
      DRIVE ===> c:
      PATH  ===> \v1
      PATH  ===> \src
      PATH  ===>
      NAME  ===> *.c;*.h

   See page 31 for details on other advanced forms of file specification.

   *  If you want to specify the file in operating system command line form,
      use the SYSTEM FILE SPECIFICATION field.  Unlike the PROJECT FILE, if
      you do not begin with an initial backslash, the file name is the
      concatenation of the current directory and your specified name.

      The SYSTEM FILE SPECIFICATION takes precedence over the PROJECT FILE.

   *  SPF/Pro displays the current drive and directory in the SYSTEM CUR DIR
      field.

   *  If you leave other fields blank, and press [SPF-Enter], SPF/Pro
      displays a select list for the current directory.

   *  You can create new files from an entry panel by typing the new file
      name in either of the two file specification fields.

   *  You can create a new file from the Select List for Edit by typing  s
      newname in the COMMAND field and pressing [SPF-Enter].


#  7. {Primary Options}

   SPF/Pro is accessed via a series of menus.  The menus are organized in a
   tree form.  The first menu in the tree is the Primary Option Panel.

   The Primary Option Panel is a Selection Menu. Selection Menus have
   multiple choices indicated by buttons on the left with numbered or
   lettered identifiers followed by descriptive text.  We call these choices
   Options. To activate an Option, either click on the desired button, or
   type the Option identifier into the OPTION field and press [SPF-Enter].

   Picking an Option presents a lower level panel which in turn may cause an
   operation on a file or create a list of files which may be operated upon.
   The Primary Options are described below:

   0 - SPF PARMS

      Allows you to set SPF/Pro start up parameters, program function key
      definitions, run time parameters, and file profiles.  It is a good idea
      to review these items before working extensively with SPF/Pro.

   1 - BROWSE

      Allows viewing of a file without modifying it.

   2 - EDIT

      Allows viewing and modification of a file.

   3 - UTILITIES

      Provides select lists and file functions such as rename, delete, move,
      copy, and print.

   4 - FOREGROUND

      Allows you to set up compilers, utilities or other programs as user
      applications and execute them synchronously from within SPF/Pro.
      Control returns to the current panel when user program execution is
      complete.

   5 - BACKGROUND

      Allows you to set up compilers, utilities or other programs as user
      applications and execute them asynchronously from within SPF/Pro.  The
      user program is launched as a peer of SPF; control returns immediately
      to the current panel.

   6 - COMMAND

      Allows execution of operating system commands and programs from within
      SPF/Pro.

   7 - DIALOG TEST

      Provides a test harness for Panel Definitions, REXX macros, and a
      display facility for variables.

   A - APPLICATIONS

      This option provides access to the Custom Dialogs for Micro Focus, and
      XDB.

   C - CHANGES

      Provides a summary of changes in the current release.

   T - TUTORIAL

      Displays information to assist you in using SPF/Pro.  You can also
      reach this information by pressing [F1] at any time.

   X - EXIT

      Exits SPF/Pro and returns to the operating system command prompt.

   In most cases, selecting an Option takes you to a secondary menu.  Each
   time you make a selection you move one level deeper in the menu tree until
   you reach the desired function.

   After you use a specific function, you may:

   *  return to the next higher level by entering the END command (normally
      [F3]).

   *  return directly to the Primary Option Panel by entering the RETURN
      command (normally [F4]).

   *  return directly to the operating system prompt by entering =x in the
      command field and press [SPF-Enter].

#  8. {Parameter Options (Option 0)}

   SPF/Pro is a very flexible system. You can alter many of its operating
   characteristics through Primary Option 0, SPF/Pro PARMS.  The parameters
   controlling SPF/Pro are logically divided into major functional areas:

   *  Display and keyboard (Option 0.1).

   *  Printer destination and formatting characteristics (Option 0.2).

   *  PF key definitions (Option 0.3).

   *  Display characteristics (Option 0.4).

   *  Editor options (Option 0.5).

   *  File List options (Option 0.6).

   *  File Profiles (0.7)

   *  Paths (0.8)

   *  Concurrent (Option 0.C)

   *  Environment (Option 0.E)

   *  Fonts (Option 0.F)

   *  Keyboard Mapping (Option 0.K)

   *  Keyboard Macros (Option 0.M)

   There are two basic ways to access the parameter panels:

   *  When you start SPF/Pro, the first screen it presents is the Primary
      Option Panel.  If you want to work with the SPF/Pro parameters, select
      option 0, SPF/Pro Parameter Options. SPF/Pro responds by displaying the
      SPF Parameter Options menu.

   *  At any time, you can use the "jump" feature to move directly to the
      parameter options.  Move to the command line, type equal (=) and the
      option number (e.g. =0.5), then press [SPF-Enter].

#  8.1 {Terminal Characteristics (Option 0.1)}

   Panel 0.1 displays basic characteristics of your keyboard and display and
   allows you to alter some of them. This information tells SPF/Pro how you
   want to handle the display and keyboard.

   SPF/Pro obtains much of the information it needs from the operating
   system. Some entry fields on the panel prompt you for additional
   information.  For example, you identify the character you want to use as a
   command delimiter when issuing a string of commands.

   Individual fields are explained below:

   USER ID

      This field allows you to set up the user ID that SPF/Pro displays on
      the Primary Option Panel.  This is an informational field, it has no
      effect on processing.

   COMMAND DELIMITER

      Type in the character that you want to use to separate stacked
      commands. This character separates commands in a command string.  The
      default is a semicolon (;), which should only be changed with due
      consideration.

   PERSISTENT INSERT

      If YES is specified, the insert state is not reset when [SPF-Enter] is
      pressed.

      If NO is specified, the insert state is reset when [SPF-Enter] is
      pressed.

   SCROLL BARS

      If YES is specified, scroll bars are displayed for tables, browse, and
      edit.

      If NO is specified, scroll bars are not displayed for tables, browse,
      and edit.

   MAX CONCURRENT TASKS

      Specifies the maximum number of SPF/Pro sessions that can be active at
      any given time. New sessions are created by SPLIT, FSPLIT, SPLITV, and
      VSPLIT primary commands.

   DISPLAY TIME/DATE

      Specifies whether time, date, or both are to be displayed on the status
      line at the bottom of the display.

   PFSHOW Enable

      Specifies whether PFSHOW display should be enabled.  Specify "Y" or
      "N".

   PFSHOW Display Mode

      Specifies which PF key set is to be displayed as the first line of the
      PFSHOW bar.

      -  Specify "N" for NORMAL (PF1  - PF12)

      -  Specify "S" for SHIFT (PF13 - PF24)

      -  Specify "C" for CTRL (PF25 - PF36)

      -  Specify "A" for ALT (PF37 - PF48)

   PFSHOW Lines

      Specifies the number of display lines in the PFSHOW bar. Each line
      displays twelve PF keys.

   Cursor Insert Size

      Specifies the size of the text cursor when SPF/Pro is in insert mode.
      The size is expressed as a percentage from 1% to 100% where 100% is the
      largest available size.  If 0 is specified, the SPF/Pro default is
      used.

   Cursor Overtype Size

      Specifies the size of the text cursor when &PRODUCT is in overtype
      mode.  The size is expressed as a percentage from 1% to 100% where 100%
      is the largest available size.  If 0 is specified, the SPF/Pro default
      is used.

   Cursor Orientation

      Specifies how the text cursor is to be oriented.  Specify "V" for
      vertical orientation.  or "H" for horizontal orientation.

      Note:  Using other than default values for the cursor is only
      recommended for notebook computers where cursor visibility may not be
      as good as a traditional monitor.

   Press [F3] to effect changes and return to the SPF Parameter Options menu.

#  8.2 {Printer Characteristics (Option 0.2)}

   Panel 0.2 allows you to create multiple printer configurations which can
   be used to perform different printing roles. Printer setups are
   symbolically named. DEFAULT, the default, typically performs no formatting
   functions and is routed to logical device PRN.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   S - select existing printer setup
   E - edit existing printer setup
   C - copy existing printer setup

   You can also use one of the following primary commands to operate on the
   printer setup:

   S setup-name       (select existing setup)
   LPRINT setup-name  (select existing setup)
   E new-setup-name   (edit a new setup)

   When you END or [F3], the new definition is saved.

   Fields of the printer setup dialog are described below:

   PRINTER DESCRIPTION

      Optional.  A brief description of this printer's characteristics for
      your reference.  This description is presented to the right of the
      logical printer name in the printer setup select list.

   SETUP

      The SETUP button invokes the Common Printer Connection Dialog of the
      operating system. This dialog connects the SPF logical printer to a
      specific system printer.

   SELECT FONT

      The SELECT FONT button invokes the Common Font Selection Dialog of the
      operating system. This dialog sets the font which is to be used by this
      print setup.

      Note:  Page depth in lines is automatically adjusted to correspond to
      the font selection.  The smaller the font, the more lines will fit and
      vice versa.

   FORM FEED:

      Optional. Specifies whether and when form feeds should be produced.

      INITIAL

         Specifies whether an initial form feed is sent to the printer prior
         to page one. This is normally not needed.

      FINAL

         Specifies whether a final form feed is sent to the printer after the
         last page. This is normally not needed.

      INTER

         In the event that there is more than one page, you may specify that
         an intermediate form feed be generated between pages. When pages are

         printed to capacity (typically 66 lines), the intermediate form feed
         is not required as the page is advanced when the page depth plus one
         line prints. Some printers (HP LaserJet series) advance full pages
         and treat an intermediate form feed as an ADDITIONAL page eject. In
         this case you do not want to generate intermediate form feeds.

   MARGINS:

      Optional. Specifies page margins. If any margins are specified, the
      PAGE parameter must be specified.

      TOP

         Specifies the number of blank lines to print before the header or
         any body text is printed.

         Note:  SPF reserves a small amount of space at the top of the page
         to accomodate the fact that laser printers disallow print access to
         that area.  The result is that the topmost printed line with TOP=0
         prints slightly below the top edge of the physical sheet.

      BOTTOM

         Specifies the number of blank lines to print after the body text
         and/or footer is printed. Normally 3 lines = .5 inch.  If you
         request intermediate form feeds, there is no need to print the page
         to full capacity.

         Note:  SPF reserves a small amount of space at the bottom of the
         page to accomodate the fact that laser printers disallow print
         access to that area.  The result is that the bottommost printed line
         with BOTTOM=0 prints slightly above the bottom edge of the physical
         sheet.

      LEFT

         The number of columns to reserve on the left edge of the page before
         each line of text.  Normally 10 columns = 1.0 inch.

         The left margin is applied to header/footer and body text.

      RIGHT

         The number of columns to reserve on the right edge of the page after
         each header/footer line of text. Normally 10 columns = 1.0 inch.

         The right margin is only applied to header and footer text; not to
         body text. Body text lines are allowed to print over the right
         margin.

   HEADER:

      Optional. Specifies the elements to be included in the page header.

      PARTS

         This field lets you specify a variety of text elements that may be
         included in the page header.  The page header is printed below the
         top margin and above the body text.

         Header text elements are:

         -- NAME, if printing a file, the file name

         -- TIME, the current time

         -- DATE, the current date

         -- PAGE NUMBER, the physical page number

         Header text elements are specified as one or more characters.  For
         example, to get the file name in the header specify "n".  Up to four
         text elements (all possibilities) may be specified.  For example, to
         get name, data, time, and page number, specify "ndtp".

      ALIGN

         Specifies the text alignment for the header text.  The header text
         alignment choices are:

         -- LEFT, all parts of the header text are set flush left.

         -- CENTER, all parts of the header text are centered.

         -- RIGHT, all parts of the header text are set flush right.

         -- SPREAD, the space remaining on the header line is evenly
            distributed between the parts in such a way that they fill the
            space available between the left and right margins.

      SPACE

         The number of blank lines to print immediately below the page
         header.

   FOOTER:

      Optional. Specifies the elements to be included in the page footer.

      PARTS

         Same as the page header but the page footer is printed below the
         body text and footer space.

      ALIGN

         Same as the page header but the alignment is applied only to the
         footer text.

      SPACE

         The number of blank lines to print immediately above the page
         footer.


#  8.3 {PF Key Definitions (Option 0.3)}

   Panel 0.3 displays the current settings of the PF keys and allows you to
   change them.  You can also specify labels to be displayed when keys are
   displayed with PFSHOW.

   You change a PF key definition by typing over the current definition.
   Primary commands are typed as-is; line commands are prefixed with a colon
   (:); literal data strings are enclosed in single quotes.

   PFSHOW labels are typed into the LABPFnn fields at the bottom of the KEYS
   panel. If no labels are specified, the PFSHOW label is the first eight
   characters of the PF key value. For example, "F1=HELP"

   The sample panel above shows the initial settings for your keys, which
   give you one-keystroke access to some frequently used general commands.
   The initial settings are all primary commands; you can also use line and
   macro commands. 1

   The initial settings for keys beyond PF12 repeat PF1-PF12 settings.  You
   can modify these definitions as desired without affecting the definitions
   for PF1-PF12.

   Some of the ways in which changing key functions or adding new functions
   can make your editing faster and more efficient are listed below:

   *  Set up PF keys to execute frequently used commands in one keystroke.

   *  Rearrange keys (move functions from one key to another) to help you
      remember the functions or reach the keys more easily.

   *  Set a series of keys to perform related complex operations in different
      ways depending on results of a previous operation. An example of this
      is RFIND ([F5]), RCHANGE ([F6]).

   *  Create macro commands to perform arbitrarily complex operations and
      assign them to PF keys.

   PF keys are applied to the active panel.  Not all commands accessed via PF
   key may operate in all contexts.  For example, editor line commands only
   operate in the Edit File Display.

   Changes to PF key definitions are applied when you press [SPF-Enter].

   When a command is executed via PF key, the primary command field value, if
   present, is passed to the command as a parameter. For example, type 5 in
   the primary command field, then press [F7]. This is the equivalent of
   entering the primary command "up 5".

#  8.3.1 {3270 Style PF Key Definitions}

   The initial settings for PF keys [F1] to [F12] are briefly defined below.
   The initial assignments are primary commands; you can execute all of them
   from the primary command field.

   [F1] HELP, present context sensitive help panel or long message.

   [F2] SPLIT, split the screen, start another SPF/Pro session.

   [F3] END, end the current function, return to the previous panel.

   [F4] RETURN, end current function, return to the Primary Option Panel.

   1. The appearance of the panel depends on the keyboard.

   [F5] RFIND, repeat the last FIND primary command.

   [F6] RCHANGE, repeat the last CHANGE primary command.

   [F7] UP, scroll up by scroll field amount. Same as [PG-UP].

   [F8] DOWN, scroll down by scroll field amount. Same as [PG-DN].

   [F9] SWAP, swap to the other split-screen session.

   [F10] LEFT, scroll left by scroll field amount.

   [F11] RIGHT, scroll right by scroll field amount.

   [F12] RETRIEVE, retrieve and display the last primary command.

#  8.3.2 {Mouse Selection Operations}

   The shifted PF keys are set up to do operations on the current selection.
   This mapping is for your convenience. Feel free to re-assign these keys as
   you see fit for your own use.

   [SHIFT][F1] SCUT, Copy the current selection to the clipboard, then delete
   it from the file.

   [SHIFT][F2] SCOPY, Copy the current selection to the clipboard.

   [SHIFT][F3] SPASTE, Paste the contents of the clipboard at the current
   cursor position.  The pasted data is always inserted. The contents of the
   clipboard are unchanged.

   [SHIFT][F4] SCREATE, Create a new external file from the contents of the
   current selection.

   [SHIFT][F5] SREPLACE, Replace an existing external file with the contents
   of the selection.

   [SHIFT][F6] STOUPPER, Convert the alpha characters in the current
   selection to uppercase.

   [SHIFT][F7] STOLOWER, Convert the alpha characters in the current
   selection to lowercase.

   [SHIFT][F8] SXCLUDE, Exclude all lines touched by the current selection.

   [SHIFT][F9] SDELETE, Delete the current selection from the file.

   [SHIFT][F10] SPRINT, Print the current selection.

#  8.3.3 {Changing PF Key Definitions}

   You can use a PF key to execute an SPF/Pro general command, edit primary
   command, edit line command, or edit macro command.  As mentioned above,
   you set up a key to execute a command by typing the command on the PF Key
   Definitions panel.  The rules for typing in each type of command are
   covered below:

   *  To assign a general command, an edit primary command, or a macro
      command to a function key, simply type in the command name.

   *  To assign a line command to a function key, type in a colon (:)
      immediately followed by the line command name.

   *  To assign string type data to the key, enclose the string in single
      quotes.

   *  To reset the assignment to the default value, clear the field then
      press [SPF-Enter].

   Changes to PF key assignments are immediately reflected in the PFSHOW
   display if present.

   Press [F3] to return to the SPF Parameter Options menu.

#  8.4 {Color Definitions (Option 0.4)}

   Panel 0.4 allows you to create multiple color schemes which can be used
   for different purposes. Each color scheme is named. Only one is active at
   any given time.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   C - copy an existing color scheme
   D - delete an existing color scheme
   E - edit an existing color scheme
   R - rename an existing color scheme
   S - select an existing color scheme

   Use the following primary command to create a new color scheme:

   S new-name

   When a new color scheme is created, it is initialized to the values of the
   active color scheme.

   Use these panels to set colors for all SPF/Pro menus and panels.

   SPF/Pro menus and panels are divided into multiple color zones. Each color
   zone has a FOREGROUND and BACKGROUND color. A color zone is determined by
   the context of the text in the zone, not by its location on the screen.
   All text and symbols with the same context are displayed in the same
   color. You can assign any color combination to any zone.

   The following points should be considered when setting colors:

   *  Assigning the same color to FOREGROUND and BACKGROUND makes text
      invisible (e.g. black on black); SPF/Pro does not allow this.

   *  On a monochrome monitor this feature can control the location of normal
      and highlighted text. On gray-scale monitors it can control the level
      of gray assigned to different types of text.

      The GOTHAM color scheme is specifically designed for use on monochrome
      displays.  It is comprised of varying levels of grey to achieve
      attractive results in the limited environment.

   The names and functions of color zones are defined below:

   PROTECTED NORMAL

      Specifies the colors for protected areas which are used to display
      characters that identify panel and display information.  The "normal,"
      or low-intensity protected areas are used for such items as the names
      of display and input fields, and system-generated values in display-
      only fields.

   PROTECTED HIGH

      Specifies the colors for the high-intensity protected areas which are
      used for items that define the panel format: the panel title, the
      command line, SPF/Pro messages, and the arrows that mark input and
      display fields.

   UNPROTECTED NORMAL

      Specifies the colors for unprotected areas which are used to display
      characters you type in, including characters you have already typed.

      The "normal," or low-intensity unprotected areas are used for your
      normal working area, such as text or code and line numbers on an edit
      panel.

   UNPROTECTED HIGH

      Specifies the colors for the high-intensity unprotected areas which are
      used where you interact directly with SPF/Pro, such as the filename
      fields on entry panels, the scroll at the top of edit, browse, and
      select lists, and the command line.

   SHORT/LONG MESSAGE

      Specifies the colors for the short message which is displayed in the
      upper right corner of any panel.  The long message is displayed on the
      third display line of the panel.

   SHORT/LONG MESSAGE WITH ALARM

      Specifies the colors for the short message which is displayed in the
      upper right corner of any panel.  The long message is displayed on the
      third display line of the panel.

   BROWSE TEXT

      Specifies the colors for the text area of the browse function.

   EDIT TEXT

      Specifies the colors for the text area of the edit function.

   TOP/BOTTOM OF DATA TEXT

      Specifies the colors for the Top of Data and Bottom of Data lines.

   NOTE LINES

      Specifies the colors for note lines.

   MSG LINES

      Specifies the colors for message lines.

   INSERT LINES

      Specifies the colors for insert lines.

   PROF LINES

      Specifies the colors for profile lines.

   LINE COMMANDS

      Specifies the colors for the line command field when any character is
      typed in.

   LINE LABELS

      Specifies the colors for line labels.

   LINE NUMBERS

      Specifies the colors for line numbers.

   LINE TYPE MARKERS

      Specifies the colors for line type indicators such as "MSG", "NOTE",
      etc.

   LINE ACTIVE INDICATOR

      Specifies the colors for the active line. The active line is
      established by FIND and LOCATE primary commands and by software
      tabbing.

   SELECTED TEXT

      Specifies the colors for text which is selected with the mouse in
      BROWSE or EDIT, and text which is highlighted by FIND or CHANGE.

   COLORIZATION WORD CLASS 1

      Specifies the colors for class 1 programming language elements defined
      in the active .CLR file.

   COLORIZATION WORD CLASS 2

      Specifies the colors for class 2 programming language elements defined
      in the active .CLR file.

   COLORIZATION WORD CLASS 3

      Specifies the colors for class 3 programming language elements defined
      in the active .CLR file.

   COLORIZATION WORD CLASS 4

      Specifies the colors for class 4 programming language elements defined
      in the active .CLR file.

   COLORIZATION SOURCE STRINGS

      Specifies the colors for literal strings in program source.

   COLORIZATION SOURCE COMMENTS

      Specifies the colors for comments in program source.

   COLORIZATION SPECIAL CHARACTERS

      Specifies the colors for individual special characters in program
      source.

   Press [F3] to return to the SPF Parameter Options menu.

#  8.5 {Editor Options (Option 0.5)}

   Panel 0.5 lets you specify a number of options that affect the general
   operating characteristics of SPF/Pro.  The fields on the panel are listed
   and explained below:

   SOUND ALARM

      Indicate whether you want the alarm (beep) to sound when SPF/Pro issues
      an error message:

      Y

         Specifies that SPF/Pro is to beep when it issues an error message.

      N

         Specifies that SPF/Pro is not to beep when it issues an error
         message.

   VERTICAL SCROLL WITH CURSOR

      Indicate whether you want your cursor to cause vertical scrolling:

      Y

         Specifies that SPF/Pro is to scroll up or down by one when the
         cursor reaches the top or bottom of the screen.  This is typical for
         PC systems.

      N

         Specifies that the cursor is to wrap to the opposite edge when it
         reaches the top or bottom of the screen.  This is typical of
         3270-type terminals.

   HORIZONTAL SCROLL WITH CURSOR

      Indicate whether you want your cursor to cause horizontal scrolling:

      Y

         Specifies that SPF/Pro is to scroll left or right by one when the
         cursor reaches the left or right edge of the screen.  This is
         typical for PC systems.

      N

         Specifies that the cursor is to wrap to the opposite edge when it
         reaches the left or right edge the screen.  This is typical of
         3270-type terminals.

   MAX RECORD LENGTH

      Specifies the nominal maximum record length for any records that may be
      handled.  Set this value to the longest record you expect to process.
      The smaller the default maximum is, the more efficiently SPF/Pro will
      run. All internal buffers used to handle records are allocated at the
      maximum record length.

      When loading data delimited records from normal DOS text files, EDIT
      examines the length of each variable length record.  If it is the
      longest record read, the maximum record length allowed is automatically
      increased up to the limit set here by MAX RECORD LENGTH.

   RECENT EDIT DEPTH

      Specifies the depth of the Recent Edits file list which is accessed via
      Utility function 3.H.  The minimum depth is 1; the maximum is 99; the
      default is 16.

   SYNTAX COLORIZATION

      Specifies whether program source should be colorized or not.  This is a
      global setting. In addition to enabling colorization here, it is also
      necessary to bind a language colorization file (.CLR) to a particular
      file type and set a color scheme which defines which colors apply to
      the different classes of language elements.

      Y

         Program source colorization is globally enabled.

      N

         Program source colorization is globally disabled.

   AUTOMATIC PROFILE CREATE

      Indicate whether you want SPF/Pro to create profiles automatically.

      Y

         Create profiles automatically.  If not already present, a profile is
         created when a profile variable is altered.

      N

         Do not create profiles automatically under any circumstance.

   VIRTUAL LOAD

      Specifies the method of file loading to be used.  Virtual loading loads
      a small portion of the file and then displays the first frame. This
      provides the effect of "instant" loading even on very large files.

      A

         Specifies that virtual loading is ALWAYS used.

      E

         Specifies that virtual loading is used with EDIT only.

      B

         Specifies that virtual loading is used with BROWSE only.

      N

         Specifies that virtual loading is NEVER used.

   FIND/CHANGE SEARCH TYPE

      Indicate whether you want case-sensitive or case-insensitive searches
      when you issue a FIND, CHANGE, or EXCLUDE primary command.

      Whichever you select, you can request the other type explicitly when
      you issue the command.

      C

         Specifies that text searching is to be case-sensitive.  Character
         search mode matches your string exactly as entered, including
         upper/lower case.

      T

         Specifies that text searching is to be case-insensitive.  Text
         search mode matches your string with any case character in any
         position.

   EDIT READ-ONLY FILES

      Specifies whether you want to be able to edit read-only files.  In this
      case edit loads the file and allows all functions of EDIT to operate in
      the normal manner but will not allow you to save the file.  This is
      handy when you want to examine a file which has the read-only attribute
      and you want to perform operations which are not available in BROWSE.

      Y

         Allow edit of read-only files.

      N

         Don't allow edit of read-only files.

   SCROLL NOTELINES

      Specify whether NOTE lines are to scroll with the adjacent text or be
      static while text scrolls past them.

      Y

         Specifies that NOTE lines are to scroll.

      N

         Specifies that NOTE lines are not to scroll.

   UNDO ENABLE

      Specifies whether UNDO support is to be active. When UNDO support is
      active more memory is used to record edit transactions that may later
      be undone. In a memory constrained system you may want to disable UNDO.

      Y

         Activate UNDO support.

      N

         Deactivate UNDO support.

   ABEND RECOVERY ENABLE

      Specifies whether abnormal termination recovery procedures should be
      activated. Abnormal termination recovery gives you an opportunity to
      save work in progress before SPF terminates.

      Y

         Activate ABEND recovery.

      N

         Deactivate ABEND recovery.

   Press [F3] to return to the SPF Parameter Options menu.

#  8.6 {File List Options (Option 0.6)}

   Panel 0.6 lets you specify a number of options that affect the general
   operating characteristics of SPF/Pro.  The fields on the panel are listed
   and explained below:

   CLEAR LISTS

      Indicate whether you want ISPF style audit trail of file actions in
      select lists or not:

      Y

         Clear standard ISPF file action indicators in select lists.  For
         example, a deleted file simply drops out of the list.

      N

         Present standard ISPF file action indicators in select lists.  For
         example, a deleted file is marked "< DELETED >".

   CONFIRM DELETE OF FILES

      Indicate whether you want a delete confirmation panel presented any
      time you delete a file from a select list:

      Y

         Present a delete confirmation panel before deleting a file.

      N

         Do not present a delete confirmation panel before deleting a file.

   EXTENDED LINE COMMANDS

      Indicate whether you want the extended line command set to be available
      in all select lists.

      Y

         Make all extended line commands available in all select lists.

      N

         Extended line commands are only available in 3.x select lists.

   DEFAULT DIRECTORY SEQUENCE

      Specifies the sort sequence for select lists:

      *

         Files are presented in the same order as they are maintained in the
         system directory. Same as operating system DIR command.

      N

         Sort files by NAME.  This option produces ISPF/PDF style select
         lists.

      E

         Sort files by EXT.

      S

         Sort files by SIZE.

      D

         Sort files by DATE (TIME field is also sorted).  The sort is in
         descending time order, most recent first.

      Note:  All sort sequences except "*" present subdirectories together at
      the top of the list.

      Note:  You can also sort the select list with the SORT primary command.

   SHOW HIDDEN/SYSTEM FILES

      Specifies whether files with the hidden or system attribute should be
      displayed in directory lists.

      Y

         Show all files regardless of attributes.

      N

         Show all files except files with hidden or system attribute.

   SORT DIRS TO TOP

      In select lists you can have both files and sub-directories.  This
      option specifies that all directory type entries be displayed together
      at the top of the list.

      Y

         Display all directories together at the top of the list.

      N

         Display directories in the order they naturally occur.

   LIST PATHS HORIZONTALLY

      Specifies how path fields are to be displayed in panels which contain a
      PROJECT FILE section.

      Y

         Array the three elements of the path field horizontally.

      N

         Array the three elements of the path field vertically.

   EXPAND VARS

      Specifies whether to expand Ampersand (&) and Percent (%) type
      variables in file name specifications.

      Y

         Expand the variables.

      N

         Do not expand the variables.

   Press [F3] to return to the SPF Parameter Options menu.

#  8.7 {File Profiles (Option 0.7)}

#  8.7.1 {Profile Select List}

   Panel 0.7 lets you access individual file profiles from a select list.
   Each file profile is stored in directory SPFPRO\PROFILES.  Profiles are
   named extension.PRF corresponding to the various file extensions that you
   work with.  Files without an extension use profile NULL.PRF.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   C - copy an existing entry
   D - delete an existing entry
   R - rename an existing entry
   S - edit an existing entry

   To create a new entry, use the following primary command:

   S new-name

   SPF/Pro allows you to apply special treatment to different classes of
   files based on the file type (file extension). For example,

   *  .COB files might be comprised of fixed length records of 80 characters.
      On an IBM mainframe this would be DSORG=F, LRECL=80.

   *  .C files might be variable length records delimited by a special escape
      sequence like CR/LF per the operating system stream file convention.

   *  Other files downloaded from a mainframe might contain binary data which
      requires special input processing.

   SPF/Pro is distributed with a number of example profiles.  When you edit a
   file with a type not provided, a default profile is used. If you alter
   profile values while editing the file, the altered profile is saved under
   the name of the file type in question.

   For example, after editing FOO.ABC, the profile ABC.PRF is created to
   preserve your profile changes. Subsequent edits of file type .ABC use the
   saved profile.

   As you can see from the example, file profiles are assigned a unique name
   matching the file type (extension) in the form "extension.PRF".  File
   profiles are kept in SPFPRO\PROFILES (or the directory where you installed
   SPF/Pro).

   Automatic profile creation is controlled by Option 0.5, AUTOMATIC PROFILE
   CREATE.

   When a new profile is created, its initial values are copied from the
   profile "DEFAULT".

   Option 0.7 allows you to set up information that SPF/Pro uses to process
   files.  If all your files are in standard ASCII data delimited format you
   will have little need to work with this panel.

   If you work with files that have non-standard formats, you must set up
   profiles that supply SPF/Pro with the information it needs to read and
   write these files. The following file formats are supported:

   *  ASCII or EBCDIC character set

   *  variable or fixed length data delimited records

   *  data delimiters CR, LF, or CR/LF

   *  Micro Focus Header-variable and VRECGEN formats

   Before discussing individual fields on the profile panel and explaining
   how to set up profiles for different purposes, we will take a look at how
   SPF/Pro uses the information in file profiles.

#  8.7.2 {How SPF/Pro Uses File Profiles}

   A file profile is a description of a file format.  Whenever you ask
   SPF/Pro to open a file, it looks for profile "extension.PRF".  The
   information in the profile tells SPF/Pro how to separate individual
   records within the file, how to find the end of the file, and other
   information needed to prepare the file for display and write it back to
   disk.

   To illustrate the significance of file profile information, let's review
   the standard format for ASCII text files and see how SPF/Pro processes
   these files:

   *  ASCII files are data-delimited. They contain a continuous stream of
      ASCII characters (bytes), with carriage-return (CR, x'0D') and line-
      feed (LF, x'0A') characters marking the end of each record.  That is,
      the records are delimited by escape sequences, rather than by record
      length, and they contain a variable number of characters.  The end of
      the file is indicated in one of two ways: by the length recorded in the
      operating system directory, or by an end-of-file (EOF, x'1A') character
      in the last character of the file.

   *  When SPF/Pro opens a standard file, it knows from the profile that it
      is data-delimited.  It reads the stream of characters until it reaches
      a CR/LF sequence; that constitutes one logical record.  The data
      portion of each record is preserved in memory, while the CR/LF
      sequences are discarded.  Input records are processed until the EOF
      character is encountered or physical end of file.

      Note:  If you create a profile for a new extension, SPF/Pro uses the
      default values from DEFAULT.PRF.

   *  In the standard case, when you close a file (with SAVE or END) SPF/Pro
      writes a standard file back to disk.  For each record on the display,
      it writes out the data characters, removes trailing blanks, and
      terminates the record with the CR/LF sequence. After writing the last
      record it writes the EOF character and closes the file.

   When you work with files in other formats, you need to set up profiles
   that tell SPF/Pro how to process these files.  Following sections cover
   individual fields that make up a file profile.  After that, we present
   some examples of setting up non-standard profiles.

#  8.7.3 {Profile Definition Panel}

   Profile definitions are effected through multiple panels.  The first panel
   is common to all profiles.  The second panel takes one of four forms
   depending on the record format D, L, M, or V.  File profile fields are
   discussed below:

   PROFILE NAME

      The name of the profile.  This name must match an existing file
      extension if it is to be applied automatically when a file of that type
      is loaded.  Names that do not exactly match a particular file extension
      may be applied by filling in the PROFILE field of the EDIT ENTRY PANEL.

      For reference, FAT file systems limit file extensions to three
      characters; HPFS file systems have no restriction on length.

   RECORD FORMAT

      This field indicates the record format.

      D (Data-delimited)

         This is the standard file format. It is also the SPF/Pro default.
         The input file is read and parsed into logical records at CR/LF (or
         other specified) record terminator boundaries.

      L (Length-delimited)

         This option is for non-standard files that may have been transferred
         to your system with fixed-length records, or for files (such as
         .EXE) that are not divided into records at all.

      M (Micro Focus Header-variable)

         This option is for Micro Focus header-variable record format.

      V (Micro Focus VRECGEN)

         This option is for Micro Focus VRECGEN record format.

      If you indicate that the input format is length delimited, SPF/Pro uses
      the maximum record length amount to divide the file into records,
      rather than looking for record delimiter characters. In addition,
      SPF/Pro uses the file length in directory entry to find the end of the
      file, instead of looking for the EOF character.  If the file length is
      not an even multiple of the record length, the last record is padded
      with blank characters to the maximum record length.

      If you don't know the format of a particular file, use example profile
      L72; its properties are

      MAX REC LENGTH = 72
      RECORD FORMAT = L

      Load the file via Option 2 (Edit).  In this mode, literally every
      character in the file is displayed in successive 72 byte records. If
      the characters are not meaningful as ASCII, use HEX ON to display them
      in hexadecimal format.  If the file is of standard format, you will see
      the CR/LF characters on the screen as well as the EOF character at the
      end. Other file formats can be examined using this technique.

   MAXIMUM RECORD LENGTH

      The maximum record length in bytes.  The maximum allowable value is
      64000.

      -  For data-delimited files, if an input record is longer than the
         profile maximum, an error message is issued and the maximum length
         is automatically increased to the maximum actual length encountered.
         Under no circumstance can an individual record be longer than 64000
         bytes.

         Each output record is written to disk with a CR/LF terminator.
         Trailing blanks are clipped.  An EOF character is written after the
         last record.

      -  For length-delimited files, input blocks of data are read in and
         parsed into records exactly equal to the maximum record length

         without regard to the data content.  So for example, a file of 800
         bytes with a maximum record length of 80 would yield exactly 10
         records of 80 bytes.

         Output records of maximum length are written directly to disk "as
         is" without delimiters. No CR/LF or EOF characters are written.

   CHARACTER SET

      Specify the character set for this file type.  Each data character is
      represented by a single byte of data with a decimal value in the range
      of 0 to 255. The ASCII character set is used in most non-IBM large
      computer systems and virtually all small computer systems.  The EBCDIC
      character set is used in all IBM S/370 systems.

      A

         Files of this type contain ASCII data characters.

      E

         Files of this type contain EBCDIC data characters.

   SAVE ON COUNT

      Specifies whether a file being edited should be saved after [SPF-Enter]
      has been pressed a specific number of times.

      If 0 is specified, the file is not saved until an END or SAVE command
      is processed.

      If a non-zero value is specified, the edit file is saved when
      [SPF-Enter] has been pressed the specified number of times.

      The default is 0.

   BACKUP ON SAVE

      Indicate whether a backup copy (.BAK) of the file you are editing
      should be created when you SAVE it.

      Y

         Create .BAK file on SAVE (or END).

      N

         Do not create .BAK file on SAVE (or END).

   OVERWRITE ORIGINAL

      Specifies whether on SAVE or END, the file is to be directly
      overwritten in place or written to a temp file which is subsequently
      renamed.  The former choice uses less disk space, the latter choice is
      safer.

      Y

         Overwrite the file in place.  The amount of disk space needed to
         save the file in this manner is equal to its size.

      N

         Create a new temporary file; then delete the original file (unless
         backup is on), then rename the temp file to the original file name.

         The amount of disk space needed to save the file in this manner is
         double its size. This method is safer but does require more space.

   DATA SHIFT ON CHANGE

      Indicate whether the CHANGE command should follow the ISPF DATA SHIFT
      rules.

      Y

         CHANGE should follow the ISPF DATA SHIFT rules.

      N

         CHANGE should not follow the ISPF DATA SHIFT rules.

   LINE TERMINATOR

      This item only applies to data-delimited files.  On input SPF/Pro
      treats the line terminator sequence as end of record.  On output
      SPF/Pro writes the line terminator sequence at the end of each record.
      See Maximum Record Length and Record Format for a summary of SPF/Pro's
      processing of these delimiters. The options available for the line
      terminator are:

      CR

         On input, end records on CR (Carriage Return, x'0D').  On output,
         write CR at end of each record.

      LF

         On input, end records on LF (Line Feed, x'0A').  On output, write LF
         at end of each record.

      CRLF

         On input, end records on CR+LF.  On output, write CR+LF at end of
         each record.  This is standard PC DOS ASCII file format.  It is also
         the SPF/Pro default.

      SCRLF

         On input, end records on LF or CR+LF.  On output, write CR+LF at end
         of each record.  This form is provided to untangle corrupted files.
         It is not normal to mix record terminator forms in the same file.

      Note:  Using the CR form, you can import/export files to/from APPLE
      systems.  Using the LF form, you can import/export files to/from UNIX
      systems.

   FILE TERMINATOR

      This field indicates whether on input to interpret the EOF (End of
      File, x'1A') character as "end of file". Similarly, on output it
      indicates whether to write the EOF character at the end of the file.

      Y

         On input, end reading when EOF character is processed.  On output,
         write EOF character at end of file.

      N

         On input, ignore EOF character; read to physical end of file.  On
         output, do not write EOF character at end of file.

   INPUT TABS TO

      Specifies whether TAB characters should be expanded to blanks when a
      file is loaded. It also specifies where the TAB stops are.

      If 0 is specified, TAB characters are not expanded when a file is
      loaded.

      If a non-zero value is specified, TAB characters are converted to
      blanks every N characters.

      The default is 0.

   OUTPUT TABS AT

      Specifies whether TAB characters should be inserted in place of blanks
      when a file is written to disk. It also specifies where the TAB stops
      are.

      If 0 is specified, TAB characters are not inserted when a file is
      loaded.

      If a non-zero value is specified, blanks are converted to TABs every N
      characters.

      The default is 0.

   PAD RIGHT W/BLANKS

      This field specifies whether data-delimited records, which are normally
      stripped of trailing blanks, should be padded with blanks to the
      maximum record length.  One of the examples (Fixed-length Files From
      Other Systems) in the following section makes use of this option.

   NULL PROTECTED

      Specifies whether characters in the range of decimal 0 (x'00') to
      decimal 31 (x'1F') are protected by the null character (x'00').  (This
      is a unique data form used in the Micro Focus Workbench environment.)

      Y

         On input, if a null character is processed, ignore it and process
         the character that follows it as a data character regardless of its
         value.

      N

         Process characters "as is". All characters below decimal 32 are
         non-data characters and may have side effects.

   Press [F3] apply changes and return to the SPF Parameter Options panel.

#  8.7.4 {File Profile Examples}

   Using the proper profile, SPF/Pro can adapt automatically to any file
   format.  This section includes some examples of using profiles to work
   with non-standard file formats.

   Fixed-length Files from Mainframes

      Program source files downloaded from IBM mainframe computers are
      normally fixed-length 80 character records (no delimiters). To edit

      these files set up a profile with a name like F80 with the following
      properties: RECORD FORMAT = L, MAX RECORD LENGTH = 80 (or other
      appropriate value), CHARACTER SET = E.

   UNIX Files

      Program source files downloaded from UNIX systems are variable length
      data-delimited with the LF character.  To edit these files, set up a
      profile with a name like UNIX with the following properties: RECORD
      FORMAT = D, MAX RECORD LENGTH = 80 (or other appropriate value),
      CHARACTER SET = A, LINE TERMINATOR = LF.

   APPLE Files

      Program source Files downloaded from APPLE systems are variable length
      data-delimited with the CR character.  To edit these files, set up a
      profile with a name like APPLE with the following properties: RECORD
      FORMAT = V, MAX RECORD LENGTH = 80 (or other appropriate value),
      CHARACTER SET = A, LINE TERMINATOR = CR.

   .EXE Files

      Executable file (.EXE) and other binary file forms (data bases) are of
      undefined format. You can however scan them using an arbitrary record
      length. For the purpose of the example we will use the editors default
      viewing width of 72 so that no horizontal scrolling will be necessary.
      To edit these files, set up a profile with a name like EXE or BIN with
      the following properties: RECORD FORMAT = L, MAX RECORD LENGTH = 72 (or
      other appropriate value), CHARACTER SET = A (or E as appropriate).

      When editing binary files, regardless of record length, you must not
      delete or add any characters.  This would change the length of the
      affected line and corrupt the file.  You can overtype characters.  To
      replace a character string with a shorter one, pad the replacement
      string with blanks to maintain the original length.

   Note:  If you intend to keep a non-standard file in your system for an
   extended period (or permanently), use Option 3.G, File Convert, to convert
   the file to the standard ASCII form.  The conversion process is
   straightforward; you specify one profile to read the file (e.g. UNIX_C)
   and a different profile to write the file (e.g. STD_C). In this manner you
   can convert any file form to any other form by simply applying different
   profiles.

#  8.8 {Paths (Option 0.8)}

   Panel 0.8 lets you display and modify all paths which are of interest to
   SPF/Pro.  SPF/Pro paths may be specified with multiple directories
   separated by a semicolon.

   Distinct paths are provided to facilitate shared use on LANS so that you
   can subscribe to a common set of control files while at the same time
   maintaining your own local control files without interfering with others.
   The 0.8 panel supports the following fields:

   DEFAULT SEARCH PATH

      Displays the value set in the SPF5PATH environment variable.  If
      SPF5PATH is not present, it displays the same value as that shown in
      EXECUTABLE PATH.

   EXECUTABLE PATH

      Displays the path where the SPF/Pro executable was found.

   GENERAL PROFILE, TABLE, AND KEYBOARD SEARCH PATH

      This is the directory (or directories) in which all profile and table
      based options are found (and altered). When storing a new profile (or
      option), the data is always stored in the first directory in the path.

   MACRO AND COMMAND PROCEDURE SEARCH PATH

      This is the directory (or directories) where all ISREDIT macros and
      ISPEXEC procedures are stored.

   PANEL AND MESSAGE SEARCH PATH

      This is the directory (or directories) where all panel and message
      definition files are stored.

   The search for control files proceeds in the following directory order:

   *  applicable custom path, if not found, then

   *  applicable preset path, if not found, then

   *  default search path, if not found, then

   *  executable path, if not found, then

   *  current directory

#  8.9 {Concurrent (Option 0.C)}

   The Concurrent option displays information about the Concurrent SPF/Pro
   execution environment. This panel is used by your network administrator to
   manage access to the concurrent form of SPF/Pro. A detailed discussion of
   this panel and its use is contained in the Concurrent SPF/Pro
   Administrator Reference.

#  8.10 {Environment (Option 0.E)}

   The Environment option displays information about the platform the SPF/Pro
   is running on. This is most frequently helpful when there is a question
   about your hardware or software configuration.

#  8.11 {Font (Option 0.F)}

   The FONT option lets you set the display fonts for panels and the PFSHOW
   buttons. The panel font is always monospace as panels are rendered on a
   grid of common sized cells. The PFSHOW font is used for the button labels
   on the PFSHOW bar. This font can be monospace or proportional.

   The first panel presented when you select Option 0.F is the FONT SELECTION
   PANEL. You can choose either the PANEL FONT option or the PFSHOW FONT
   option.

   Either font selection displays a lower level FONT SELECTION PANEL which
   displays the current face, size, and a table of available faces.  When you
   select a face, the FONT STYLE SELECTION panel is displayed.  This panel
   lets you set the font size, and the attributes BOLD and ITALIC.

   In summary to set the panel font:

   *  Activate Option 0.F

   *  on the first panel, select the PANEL FONT Option

   *  on the next panel, select the desired font face

   *  on the third panel specify the font size

   *  also on the third panel, set the bold and/or italic attributes if
      desired

   *  exit all panels via [F3] or END primary command

   The same procedure (modifying the second step) is followed to set the
   PFSHOW font.

#  8.12 {Keyboard (Option 0.K)}

   Panel 0.K allows you to create multiple keyboard schemes which can be used
   for different purposes. Each keyboard scheme is named. Only one is active
   at any given time.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   S - select keyboard scheme
   E - edit keyboard scheme
   D - delete keyboard scheme
   C - copy keyboard scheme
   R - rename keyboard scheme

   When a new keyboard scheme is created via "e newname" primary command, it
   is initialized to the values of the active keyboard scheme.

   When you edit a keyboard scheme you are presented with a menu of Keyboard
   Mapping Options. All non-data key variations are represented in the
   keyboard mapping choices. Data keys are not mappable.  You can pick one
   of:

   1. Function Keys - allows you to specify mappings for all variations of
      FUNCTION keys.

   2. ALT Keys - allows you to specify mappings for all variations of the ALT
      keys.

   3. CTRL Keys - allows you to specify mappings for all variations of the
      CTRL keys.

   4. SHIFT Keys - allows you to specify mappings for all variations of the
      SHIFT keys.

   5. Extended Keys - allows you to specify mappings for all variations of
      the Extended keys (i.e. numeric keypad and island keys)

   6. Mouse - allows you to specify mappings for all variations of mouse
      buttons.

   7. Custom Keys - allows you to specify mappings for variations of the keys
      of your own design.

#  8.12.1 {Keyboard Mapping Data}

   For each key in any given set of keys there is a key name and mapping
   data. Mapping data is typed to the right of the key name in the key entry
   and consists of one of the following mapping data types:

   *  DATA - any text string enclosed in single quotes.  Example:

      'the man in the moon'

      Hexadecimal data is entered in the form x'nn'.  Example:

      x'1B'

   *  PRIMARY or LINE COMMANDS - commands are entered "as is" with no special
      syntactic treatment just as they would be in the primary or line
      command field. Line commands are prefixed with a colon (:).  As with
      function keys, data entered in the primary command field is treated as
      a parameter when a mapped key is processed.  Example:

      LOCATE SPECIAL

   *  SPF ACTIONS - a single SPF action enclosed in square brackets.
      Example:

      [CURSOR-UP]

   SPF actions are described below:

   CURSOR-UP nnn

      Move the cursor up "nnn" positions.  If "nnn" is not specified, 1 is
      assumed.

   CURSOR-DOWN nnn

      Move the cursor down "nnn" positions.  If "nnn" is not specified, 1 is
      assumed.

   CURSOR-LEFT nnn

      Move the cursor left by "nnn" positions.  If "nnn" is not specified, 1
      is assumed.

   CURSOR-RIGHT nnn

      Move the cursor right by "nnn" positions.  If "nnn" is not specified, 1
      is assumed.

   WORD-LEFT

      Move the cursor one word to the left.

   WORD-RIGHT

      Move the cursor one word to the right.

   END-OF-DATA

      Move the cursor to the end of data in the current field (the blank
      after the last data character).

   TAB

      Move the cursor to the first position of the next field.

   BACKTAB

      Move the cursor to the first position of the current field. If already
      at the first position, move to the first position of the previous
      field.

   NEWLINE

      Move the cursor to the first position of the next field or line.

   CURSOR

      Move the cursor to the first position of the primary command field.

   CURSOR-MOUSE

      Move the cursor to where the mouse pointer is located.

   SCROLL-LEFT nnn

      Scroll left "nnn" positions.  If "nnn" is not specified, scroll the
      number of positions specified in the current scroll amount.

   SCROLL-LEFT-MAX

      Scroll left to character position one.

   SCROLL-RIGHT nnn

      Scroll right "nnn" positions.  If "nnn" is not specified, scroll the
      number of positions specified in the current scroll amount.

   SCROLL-RIGHT-MAX

      Scroll to the rightmost position of the file record length.

   SCROLL-UP nnn

      Scroll up "nnn" lines.  If "nnn" is not specified, scroll the number of
      positions specified in the current scroll amount.

   SCROLL-UP-MAX

      Scroll to the top of the file.

   SCROLL-DOWN nnn

      Scroll down "nnn" lines.  If "nnn" is not specified, scroll the number
      of positions specified in the current scroll amount.

   SCROLL-DOWN-MAX

      Scroll to the bottom of the file.

   ENTER-3270

      Perform 3270 style enter processing.

   ENTER-SPFPC

      Perform early style SPF/Pro ENTER processing.  This action is provided
      for compatibility with older versions of SPF/Pro.

   CURSOR-SELECT

      Select the item on which the cursor resides. In menus this is the
      equivalent of typing the menu item number in the primary command field
      and pressing [SPF-Enter]. In select lists this is the equivalent of
      entering the select line command and pressing [SPF-Enter].

   CURSOR-MOUSE-SELECT

      Move the cursor to where the mouse pointer is located.  Select the item
      on which the cursor resides. In menus this is the equivalent of typing
      the menu item number in the primary command field and pressing
      [SPF-Enter]. In select lists this is the equivalent of entering the
      select line command and pressing [SPF-Enter].

   MOUSE-STREAM-SELECT

      Holding the left mouse button down and dragging the mouse produces the
      "Button-1-Drag" mouse event. By default this mouse event is mapped to
      "MOUSE-STREAM-SELECT". In this context, if the mouse cursor is in the
      text area, the selection is extended character by character as the
      mouse is dragged.  If the mouse cursor is in the line command field,
      the selection is extended line by line as the mouse is dragged.

   EXTEND-STREAM-SELECT

      Once the mouse cursor has been set via single click on the left mouse
      button, you can reposition the mouse, press [SHIFT] and click the left
      mouse button again. This extends the selection from the original mouse
      cursor position to the the current mouse position in a single step (no
      mouse dragging necessary).

   MOUSE-BLOCK-SELECT

      Holding the right mouse button down and dragging the mouse produces the
      "Button-2-Drag" mouse event. By default this mouse event is mapped to
      "MOUSE-BLOCK-SELECT". In this context, the block selection is extended
      blockwise as the mouse is dragged.

   EXTEND-BLOCK-SELECT

      Once the mouse cursor has been set via single click on the left mouse
      button, you can reposition the mouse, press [SHIFT] and click the right
      mouse button. This extends the block selection from the original mouse
      cursor position the the current mouse position in a single step (no
      mouse dragging necessary).

   STREAM-SELECT-UP

   STREAM-SELECT-DOWN

   STREAM-SELECT-LEFT

   STREAM-SELECT-RIGHT

   STREAM-SELECT-PGUP

   STREAM-SELECT-PGDN

      These events are mapped to the [SHIFT] key combined with the desired
      arrow key or page scroll key.  In all of these cases, the stream
      selection is extended in the direction and amount of the key pressed.

   DEL-CHAR

      Delete the character at the current cursor position.  If there are
      characters to the right of the deleted character, shift them to the
      left one position.

   BACKSPACE

      Move the cursor left one position; delete the character at that
      position.  If there are characters to the right of the deleted
      character, shift them to the left one position.

   BACKSPACE-BLANK

      Move the cursor left one position; blank the character in that
      position.

   DEL-END-OF-DATA

      Delete characters from the current cursor position to the end of the
      field.

   CANCEL

      If searching a list of files for a text string, abort the search.

      If a keyboard macro is playing, abort the macro.

      If entering data in a panel or the text area of an edit session, clear
      all data entered since the last [SPF-Enter] was processed.

   RESET

      Reset the input-inhibited condition and insert mode.

   KEY-MACRO macro-name

      Execute the named keyboard macro.

   KEY-MACRO-RECORD

      This action toggles key macro recording.  If key macro recording is
      OFF, start key macro recording.  If key macro recording is ON, stop key
      macro recording.

#  8.12.2 {Mapping a Custom Key}

   Custom keys come in two forms:

   *  Combinations of CTRL, ALT, and SHIFT keys that are not already
      represented in the standard keyboard mapping tables.

   *  Non-standard keyboards may have keys which are unknown to SPF/Pro.
      These keys are mappable through the CUSTOM interface (see following
      instructions).

   Follow these steps to map a custom key:

   1. After selecting 0.K, edit the desired keyboard scheme.  Select Option 7
      (CUSTOM).

   2. You are presented with a panel which requests that you press the custom
      key you want mapped. Press it. For example, you might press CTRL+ALT+A
      to create a unique custom key sequence.

   3. The custom key pressed is echoed in the KEY NAME field of the panel.
      Press [SPF-Enter] to accept the name.

      Note:  Keys which are unknown to SPF/Pro are given system generated
      names in the form "CUSTOM-nnnn" which you can alter later.

   4. You are now presented with a panel which once again echoes the name.
      At this point you can alter the name to be more meaningful or leave it
      "as is".

   5. Specify the mapping value for the custom key (i.e. data, primary or
      line command, or SPF/Pro action).

   6. Press [SPF-Enter] to accept the name and value. Press [F3] to return to
      the custom key list. The custom key is now mapped and should appear in
      the list in alphabetical order.

#  8.13 {Keyboard Map Files}

   Keyboard map files are kept in files corresponding to the map name with
   file type .KEY appended. For example, the keyboard map file for key map
   CCODE would be in file SPFPRO\PROFILES\CCODE.KEY.

#  8.14 {Key Macros (Option 0.M)}

   Panel 0.M displays a list of active keyboard macros.  The main use of the
   list is to refresh your memory as to which keyboard macros exist.
   Keyboard macros are bound to keys with the "[KEY-MACRO ...]" SPF action.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   C - copy existing keyboard macro
   D - delete an existing keyboard macro
   E - edit existing keyboard macro
   R - rename existing keyboard macro

   Keyboard macros may be used to perform complex operations that do not
   naturally fall into the other categories of keyboard mapping.

   To record a keyboard macro, press [ALT]+[M]. You are presented with a
   panel which has fields for Name and Description.

   After entering the name and description, press [F3]. That returns you to
   the current context. All subsequent keystrokes are recorded exactly as
   entered. While you are recording keystrokes, the status line displays
   "RECORDING".

   When you press ALT+M a second time, macro recording is ended. A panel is
   presented which has a field for the key sequence to activate the macro.
   The initial value is "NONE". At this point if you press [SPF-Enter] the
   panel is dismissed and no key assignment is made. The named macro is
   placed in the macro pool for future assignment.

   If you press any other key, the key legend is presented in the entry field
   for confirmation. At this point if you press [SPF-Enter] the macro is
   bound to the displayed key in the active keyboard scheme and the panel is
   dismissed. If you press any other key, it takes the place of the currently
   displayed key.

   At any time you can press [ESC] to reset the entry field to the "(no
   assignment)" value.  Your recorded keystrokes are played back when you
   press the key that is bound to the macro. See SPF action [KEY-MACRO ...]
   for a description of how to manually bind a keyboard macro to a key.

#  8.15 {Keyboard Macro Files}

   Keyboard macro files are kept in files corresponding to the macro name
   with file type .MAC appended. For example, the keyboard macro file for key
   map IF would be in file SPFPRO\PROFILES\IF.MAC

#  9. {Browse (Option 1)}

   The SPF/Pro browse option allows you to view but not modify files.  When
   you start SPF/Pro the Primary Option Panel is presented.  Select option 1,
   Browse Entry Panel.

   A new screen is presented to you called Browse Entry Panel.  Enter the
   file name of the file you want to browse.

   If the file name specified contains wild-card characters ("*" or "?"), a
   Select List is generated.

   You can select a file to browse from this list by placing an S to the left
   of the desired filename and pressing [SPF-Enter].  The system then brings
   up the file to be browsed.

   Browse mode differs from edit mode in two fundamental ways:

   *  You can not modify the file in any way.

   *  There are no line commands; all columns are used for display.


#  10. {Edit (Option 2)}

   SPF/Pro edit allows you to create, modify, or display files.  Normally,
   you edit standard text files. By using length-delimited record format, you
   can edit files of any format or content.

   Standard text files are simply collections of variable length records
   terminated by CR/LF sequences. The file is terminated by an EOF character.
   There are many variations on this theme all of which can be processed by
   SPF/Pro with appropriate profiles.

   Some examples of standard operating system text files are:

   *  Computer program source files (*.COB, *.C, et al)

   *  system procedure language source (*.BAT, *.CMD)

   *  dBASE procedure files (*.PRG, *.FRM)

   *  Listing files (*.LST)

   Some examples of non-standard files are:

   *  S/370 mainframe EBCDIC files

   *  Executable programs (*.EXE)

   *  DLL files (*.DLL)

   *  dBASE databases (*.DBF, *.NDX)

#  10.1 {Selecting a File to Edit}

   After you start SPF/Pro, the Primary Option Panel is displayed. Select
   Option 2, Edit.

   The Edit Entry Panel is presented.  Enter the name of the file you want to
   edit.

   If the file name contains wild-card characters ("*" or "?"), a select list
   is generated.

   You can select a file to edit from a select list by placing an S to the
   left of the desired filename and pressing [SPF-Enter].

#  10.2 {Edit Profile}

   Each time you edit a file, SPF/Pro activates an environment consisting of
   modes, options, and parameters, called the edit profile. SPF/Pro maintains
   edit profiles in disk files between sessions.

   For each file extension, there is a corresponding edit profile.  Each time
   an edit session is begun, the corresponding profile is loaded to create
   the edit environment.  SPF/Pro saves the profile whenever the environment
   is changed.  For example, if you change CAPS mode from OFF to ON while
   editing a file with extension .COB, subsequent edits of files with that
   extension will have CAPS mode ON.

   To avoid saving changes from a particular edit session, use the PROFILE
   LOCK command.

   A different profile may be used when editing a particular file by
   specifying the PROFILE NAME in the Edit Entry Panel.

   A new edit profile is created when:

   *  a profile for this file extension does not exist, and

   *  Option 0.5, field AUTOMATIC PROFILE CREATE = Y, and

   *  a profile variable is altered from the default setting.

   The following table lists edit profile fields.

      Change with Primary Commands

      AUTONUM   Renumbers data automatically
      AUTOLIST  Lists data automatically on exit
      AUTOSAVE  Saves data automatically on exit
      BNDS      Specifies right and left bounds for edit commands
      CAPS      Controls translation to uppercase
      COLORMAP  Colorizes program source
      COMPARE   SUPERC file compare
      HEX       Displays data in hexadecimal format
      IMACRO    Names an initial macro to execute
      XMACRO    Names an exit macro to execute
      NUMBER    Controls line number generation
      PROFILE   Allows locking the edit profile
      STATS     Controls generation of a level number
      TABS      Enables or disables tabbing

      Change with Line Commands

      BNDS      Specifies right and left bounds for edit commands
      MASK      Applies a preset mask to inserted lines
      TABS      Defines tab stops

      Change with Line Commands

      SCROLL    Scrolling amount on edit, browse, select list panels

   The following table lists profile fields set in panel 0.7

      PROFILE NAME     The name of the profile (corresponds to file EXT)
      RECORD FORMAT    Specifies whether the file is data-delimited or
                       length-delimited
      MAX RECORD LEN   Specifies the maximum record length
      CHARACTER SET    Specifies the character set for text files, either
                       ASCII or EBCDIC
      SAVE ON COUNT    Specifies that SAVE should be invoked after
                       [SPF-Enter] is pressed a specific number of
                       times
      BACKUP ON SAVE   Specifies whether .BAK file should be created
      OVERWRITE        Specifies whether SAVE overwrites in place or not
      DATA SHIFT TYPE  Specifies whether the CHANGE primary command
                       should use ISPF style data shift
      LINE TERMINATOR  For data-delimited files,
                       specifies the line terminator sequence
      FILE TERMINATOR  For data-delimited files,
                       specifies the file terminator sequence
      INPUT TABS       For data-delimited files,
                       specifies expansion of tabs to blanks
      OUTPUT TABS      For data-delimited files,
                       specifies insertion of tabs in place of blanks
      PAD RIGHT W/BLNK For data-delimited output files,
                       specifies that output records should be padded on
                       the right with blanks to maximum record length
      NULL PROTECTED   For data delimited files, specifies protection
                       method for non-data characters

   The contents of edit profiles are displayed in:

   *  Panel 0.7 - this panel allows you to select, display, and modify
      profiles for specific file types.

   *  Within EDIT - the PROFILE command displays variables that are not part
      of Panel 0.7.

   Profile Name

      The first profile display field is unnamed. It contains the profile
      name followed by the record format and maximum record length in
      parenthesis.

      Normally the profile name is derived from the extension of the file
      being edited.  For example, if you are editing PROG1.COB, the profile
      will be COB.PRF.  You can invoke edit with a different profile by
      putting the alternate profile name in the PROFILE field of the EDIT
      ENTRY PANEL.

   RECOVERY

      RECOVERY is not supported and is always shown as OFF.

   NUMBER

      OFF

         No numbers are generated or expected.  This is the system default.

      ON

         SPF/Pro verifies that all lines have valid numbers in ascending
         sequence. It renumbers all lines if any lines are either unnumbered
         or out of sequence, but does not otherwise alter existing sequence
         numbers.

      STD

         Specifies that sequence numbers are to be generated in columns 73 to
         80.

         If stats is on, sequence numbers are in columns 73 to 78; a level
         number is generated in columns 79 and 80. The level number is
         increased by one each time the file is modified.

      COBOL

         Specifies that sequence numbers are to be generated in columns 1 to
         6.

      DISPLAY

         Specifies that sequence numbers, normally obscured, are to be
         displayed.

         This variable can be changed with the NUMBER primary command.

   CAPS

      ON

         Specifies that all data entered is to be set in upper case.

      OFF

         Specifies that all data entered is to be set "as is".  This is the
         default.

   HEX

      ON

         Display the file being edited in hexadecimal format. Each data line
         is followed by two corresponding lines vertically depicting its
         hexadecimal value.  The data can be modified by changing the text
         line or the hex lines.

      OFF

         Text is displayed in the normal manner.  This is the default.

   SAVECOUNT

      Displays OFF or the number of times [SPF-Enter] must be pressed before
      an automatic SAVE is performed.

   TABS

      This field specifies whether and how tabs are to be processed.

      ON

         Specifies that tabs are to be processed.

         STD

            Specifies that the [TAB] key is to move the cursor to the next
            hardware tab stop as defined by asterisk (*) characters on the
            TABS line.

            Unlike ISPF/PDF, SPF/Pro does not simulate 3270 attribute bytes.
            The cursor is still positioned one character after the tab stop
            (*) but the character at the tab stop can be modified.

         ALL

            Same as STD.

         character

            When a logical tab character is specified, data entered with that
            character is positioned to the nearest tab stop when [SPF-Enter]
            is pressed.

      OFF

         Hardware and logical tabs are ignored.  This is the default.

   CHARSET

      This field identifies the character set that the file data is in.

      ASCII

         Used in most small and midsize computer systems.

      EBCDIC

         Used in IBM S/370 mainframes and compatible systems.

         This variable can be changed in panel 0.7.

   AUTOSAVE

      This field describes whether to automatically save the file on exit.

      ON

         Files are saved on exit.  This is the default.

      OFF

         Files are not saved on exit.

   AUTONUM

      This field describes whether lines are to be renumbered when the file
      is saved.

      ON

         Lines are renumbered on exit.

      OFF

         Line numbers are not changed on exit.  This is the default.

   AUTOLIST

      This field describes whether listing is made on exit.

      ON

         The file is printed on exit.

      OFF

         The file is not printed on exit.  This is the default.

   STATS

      Stats indicates whether level stamping is on or off.

      ON

         If standard line numbering is on, columns 79 and 80 receive a level
         number which is incremented each time the file is edited.

      OFF

         No level stamping is done.  This is the default.

   PROF

      This is identical to ISPF field PROFILE.  We did not have enough room
      on the profile line to fully spell the field name.  Specifies whether
      the profile is locked.

      LOCK

         Changed profile parameters are not saved on exit.

      UNLK

         Changed profile parameters are saved on exit.  This is the default.
         This is identical to ISPF state PROFILE UNLOCK.  We did not have
         enough room on the profile line to fully spell the state value.

   IMAC

      This is identical to ISPF field IMACRO.  We did not have enough room on
      the profile line to fully spell the field name.  Identifies the name of
      the initial macro.

      This variable can be changed in the EDIT ENTRY PANEL.

   XMAC

      Identifies the name of the exit macro.

      This variable can be changed in the EDIT ENTRY PANEL.

   PACK

      PACK is not supported and is always shown as OFF.

   COLORMAP

      Displays the name of the colormap file or OFF.

#  10.3 {Editing a File}

   If you haven't already done so, take a moment now to read the quickstart
   chapter. This brief chapter will give you a minimal working knowledge of
   SPF/Pro.  It explains how to enter primary and line commands and a subset
   of editing operations.

#  10.4 {Popup Menus}

   Two popup menus are provided for your convenience while editing files:

   *  To access the line command popup menu, position the mouse cursor
      anywhere in the line command field area, click the right mouse button.
      Select the desired line command by positioning the mouse cursor over it
      and and clicking the left mouse button.

   *  To access the primary command popup menu, position the mouse cursor
      anywhere in the text area, click the right mouse button.  Select the
      desired line command by positioning the mouse cursor over it and and
      clicking the left mouse button.

#  10.5 {Edit Termination}

   The edit session may be ended in one of following ways:

   *  Press [F3]. (normally the END primary command)

   *  Execute the END primary command. This command saves the file then
      returns to the parent panel.

   *  Execute the CANCEL primary command. This command returns to the parent
      panel without saving the file.

   *  Double-click on the task close box with the left mouse button.

   Note:  When the END command is processed and AUTOSAVE = OFF + NOPROMPT,
   the file is not saved. In this case END is equivalent to CANCEL.

   When the END command is processed and AUTOSAVE = OFF + PROMPT, a prompt
   message appears, giving you a chance to issue a SAVE or CANCEL primary
   command to terminate the edit session.

   You may save the data at any time by issuing the SAVE primary command.

#  11. {Utilities (Option 3)}

   You can perform a number of utility functions, including moving, copying,
   renaming, and deleting files, without leaving the SPF/Pro environment. You
   can use SPF/Pro utility features to manage files instead of operating
   system commands. If you are an experienced ISPF/PDF user, this gives you
   the opportunity to work with directories and files in a familiar way.

   If you prefer to use operating system commands, you can issue them from
   the command line, or the Primary Option 6 panel (COMMAND). If you have
   non-SPF/Pro utilities you prefer to use, you can use Primary Option 4
   (FOREGROUND) to execute them from inside SPF/Pro.

   The two basic ways to access the utility functions are listed below:

   *  When you start SPF/Pro it displays the Primary Option Panel.  If you
      want to work with the utility functions, select Option 3, SPF/Pro
      Utilities. SPF/Pro responds by displaying the Utility Selection Menu.

   *  At any time, you can use the "jump" feature to reach the utility
      panels.  Type =3.x, in the primary command field, where "x" is the
      number or letter of the utility panel you want to use.  Then press
      [SPF-Enter].

   SPF/Pro utilities are located on multiple entry panels. You can perform
   utility functions by selecting a utility entry panel and typing in the
   file(s) and utility function(s) you want. The functions available on each
   panel are summarized below.

   3 - MOVE/COPY

      This panel allows you to move or copy a file, group of files or an
      entire directory. You can move or copy from one directory to another or
      from one drive to another. You can also rename the files as part of the
      move or copy.

   4 - FILE LIST

      This panel presents a select list that allows you to browse, edit,
      print, rename, or delete files with line commands.  This is useful when
      you want to clean up or reorganize a directory.

      Note: Super Lists A - E provide significant extensions to the basic 3.4
      functional set.

   A - DIRECTORY SEARCH

      If you are interested exclusively in directories, use this panel to do
      a single or multilevel search for directories.  The result of the
      search is a select list of directories that meet the search criteria.

   B - FILE SEARCH

      If you are interested exclusively in files, use this panel to do a
      single or multilevel search for files.  The result of the search is a
      select list of files that meet the search criteria.

   C - TEXT SEARCH

      If you want to search for a specific text string in one or more files,
      use this panel to do a single or multilevel text search.  The result of
      the search is a select list of files that contain the specified text
      string.

   D - COMPLEX SEARCH

      Complex search is provided for the power user who is already familiar
      with the basic directory, file, and text search methods.  It combines
      the capabilities of 3.A, 3.B, and 3.C in a single panel.  The result of
      the search is a select list of files and/or directories that meet the
      complex search criteria.

   E - DRIVE SEARCH

      Drive search lets you take a drive-oriented approach to your search.
      It presents a select list from which you can select one or more drives
      to search. The cross drive search can be particularly useful when you
      are in a networked environment that gives you visibility to many
      logical drives. You can do a single or multilevel search for
      directories, files, or both.  The result of the search is a select list
      of files and/or directories that meet the drive search criteria.

   F - SAVED LISTS

      When you use the SAVELIST primary command to save a select list, the
      saved list is preserved under a symbolic name. This panel displays a
      select list of those names. When you select an entry, it displays the
      selected list.

   G - FILE CONVERSION

      File conversion lets you convert files from one format to another.  For
      example, you might download a batch of mainframe files and then using
      file conversion, convert them to standard ASCII format for permanent
      residence on your PC.

   H - MOST RECENT EDITS

      Each time you edit a file, it is placed in the Most Recent Edits file
      list. List depth is optioned. The list persists across SPF/Pro
      sessions.

   I - SUPERC

      Compare one or more files, one to the other, line by line or byte by
      byte.  Produce a change report in a variety of formats.  Send the
      change report to BROWSE, PRINT, or a file.

   J - Command Tables

      This option lets you add new primary commands to the system or modify
      the behavior of existing primary commands.

   K - Partitioned Dataset Access

      This option provides access to PC based Partitioned Datasets which are
      used to contain SPF/Pro control information such as panel definitions.

   From the Utility Selection Menu you can select a utility panel or press
   [F3] to return to the Primary Option Panel.  Individual utility panels are
   covered in the following sections.

#  11.1 {MOVE/COPY (Option 3.3)}

   Panel 3.3 allows you to to move or copy a files and/or directories.  You
   can move or copy from one directory to another on the same drive or
   different drives.

   You can use wild-card characters (* and ?) in the from fields, to fields,
   or both, to specify a group of files:

   *  Typically you copy FROM files intact to the TO directory. In this case
      you specify the FROM NAME field and LEAVE the TO name field blank.

   *  If you want to rename files as they are copied or moved, you specify
      the FROM NAME field with a particular extension and the TO NAME field
      with a different extension. For example:

      FROM FILE:
         NAME ===> *.CBL

      TO FILE:
         NAME ===> *.COB

      In this example as the *.CBL files are moved or copied, they are
      renamed to *.COB.

   Individual fields are explained below.

   OPTION

      Specify the desired action in the OPTION field:

      M

         Moves files from one directory to another.  All files and
         sub-directories within the FROM directory are moved.

      C

         Copies files from one directory to another.  All files and
         sub-directories within the FROM directory are copied.

   FROM FILE

      Use these fields to specify the file(s) you want to move or copy.  The
      SYSTEM FILE SPECIFICATION overrides this field.

   TO FILE

      Use these fields to specify the destination for files you are moving or
      copying.  The SYSTEM FILE SPECIFICATION overrides this field.

   SYSTEM CURRENT DIRECTORY

      This field displays the current directory.  This field applies to the
      SYSTEM FILE SPECIFICATION only.

   FILE SPECIFICATION FROM/TO

      If you prefer operating system command line syntax, use these fields
      instead of the FROM FILE / TO FILE fields.

   Press [F3] to return to the Utility Selection Menu menu.

#  11.2 {FILE LIST (Option 3.4)}

   Panel 3.4 allows you to browse, edit, print, rename, or delete a file or
   group of files.  Simply specify the file (or files) on the FILE LIST
   UTILITY panel and press [SPF-Enter]. SPF/Pro presents a select list where
   you can specify line commands to perform various functions.

   This panel is particularly useful when you want to reorganize a directory;
   you can scroll up and down the select list, using different line commands
   to work with different files.

   You can:

   *  Browse or edit to review individual files.

   *  Use the delete command to remove outdated files.

   *  Use the rename command to reorganize the directory.

   *  Use the SORT command to reorder the directory.

   Use wild-card characters (* and ?) in the file selection fields to specify
   a group of files:

   *  The sample panel above would result in SPF/Pro displaying a select list
      of all files in the c:\TEST directory.  You could then use select list
      line commands to work with this group of files.

   *  If you wanted to be more specific, you could specify *.COB in the NAME
      field.  SPF/Pro would then display a select list containing only files
      with the COB extension.

   Individual fields are explained below.

   OPTION

      This is a standard command field, where you can enter SPF/Pro general
      commands.  Line commands are only available in the select list.

   PROJECT FILE

      Use this group of fields to identify the file(s) you want to work with.
      The SYSTEM FILE SPECIFICATION overrides this field.

   SYSTEM CURRENT DIRECTORY

      This field displays the current directory.  The current directory
      applies to the SYSTEM FILE SPECIFICATION field only.

   SYSTEM FILE SPECIFICATION

      If you prefer operating system command line syntax, use this field
      instead of the PROJECT FILE fields.

   CONFIRM DELETE REQUEST

      Use this field to specify whether you want confirmation before a file
      is deleted.

      YES

         When you issue a delete command in the select list, SPF/Pro displays
         a panel requesting confirmation before the delete is actually done.

      NO

         Delete commands in the select list are processed without
         confirmation.

   Once in the FILE LIST select list, the following line commands are
   available:

   B - browse the file.
   E - edit the file.
   N - launch new SPF task to edit the file
   P - print the file.
   R - rename the file.
   D - delete the file.
   G - execute .EXE, .BAT, or .CMD file
   T - make directory tree list
   K - convert file

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.3 {DIRECTORY SEARCH (Option 3.A)}

   Panel 3.A allows you to search for directory type files, at one or more
   levels, from a specific path origin.  The resulting select list contains
   all directories at all requested levels that meet the directory file
   specification criteria.

   Individual fields are explained below:

   SYSTEM CUR DIR

      Identifies the current directory. This field only applies when the path
      specification does not proceed from the root directory.  For example,
      if you specified "C:\FOO" the search for "FOO" would begin in the root
      directory of drive "C".  If you specified simply "FOO" the search for
      "FOO" would begin in the current directory.

   PATH

      Specifies the origin for the search.  Directories may have file
      extensions although this is not a common practice.

   SEARCH SUBDIRECTORIES

      This field lets you specify whether the search should be limited to the
      first level of the specified path or to all levels (via recursive
      search).  For example, you might have a directory structure like:

      SPF             (directory for SPF project)
       +- DOC         (sub-directory for documentation)
       |   +- TEXT    (sub-directory for text files)
       |   +- SCREENS (sub-directory for raw images)
       |   +- CHARTS  (sub-directory for annotated images)
       |
       +- SRC         (directory for program source files)
           +- EDIT    (sub-directory for edit source)
           +- DM      (sub-directory for DM source)
           +- TOOLS   (sub-directory for tools source)

      In the example directory structure, if you specified

      PATH ===> \SPF

      SEARCH SUBDIRECTORIES ===> N

      you would get a select list of the directories from the first level
      only:

      DOC    <dir>
      SRC    <dir>

      Alternatively, if you specified

      PATH ===> \SPF

      SEARCH SUBDIRECTORIES ===> Y

      you would get a select list of the directories from all first levels:

      CHARTS   <dir>
      DM       <dir>
      DOC      <dir>
      EDIT     <dir>
      SCREENS  <dir>
      SRC      <dir>
      TEXT     <dir>
      TOOLS    <dir>

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.4 {FILE SEARCH (Option 3.B)}

   Panel 3.B allows you to search for files, at one or more levels, from a
   specific path origin.  The resulting select list contains all files at all
   levels that meet the file specification criteria.

   Individual fields are explained below:

   SYSTEM CUR DIR

      Identifies the current directory.  The current directory comes into
      play when the file specification does not start in the root directory.

      For example, if you specified simply "FOO" the search for "FOO" would
      begin in the current directory.

      If you specified "C:\FOO", the search for "FOO" would begin in the root
      directory of drive "C".

   PATH

      Specifies the origin for the search and optionally constrains
      conformant files to a particular file extension.  Normal files are
      typically classed by extension. For example, COBOL program source files
      might have the extension ".COB".

   SEARCH SUBDIRECTORIES

      This field lets you specify whether the search should be limited to the
      first level of the specified path or to all levels (via recursive
      search).

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.5 {TEXT SEARCH (Option 3.C)}

   Panel 3.C allows you to search for files containing a specific text
   string, at one or more levels, from a specific path origin.  The resulting
   select list contains all files at all levels that contain the specified
   text string.

   Individual fields are explained below:

   SYSTEM CUR DIR

      Identifies the current directory. This field only applies when the path
      specification does not proceed from the root directory.

   PATH

      Specifies the origin for the search and optionally constrains
      conformant files to a particular file extension.

   SEARCH SUBDIRECTORIES

      This field lets you specify whether the search should be limited to the
      first level of the specified path or to all levels (via recursive
      search).

   TEXT

      Specifies the text string to look for.

   CASE SENSITIVE

      Specifies whether the TEXT string search should be for an exact match
      (CASE SENSITIVE = Y), or for a match on upper and lower case characters
      (CASE SENSITIVE = N).

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.6 {COMPLEX SEARCH (Option 3.D)}

   Panel 3.D incorporates all the functions of panels 3.A, 3.B, and 3.C.
   With Complex Search you can:

   *  Search for directories, on one or more drives, at one or more levels,
      in one or more paths.

   *  Search for files, on one or more drives, at one or more levels, in one
      or more paths.

   *  Search for files and directories, on one or more drives, at one or more
      levels, in one or more paths.

   *  Search for one or more text strings, in files, on one or more drives,
      at one or more levels, in one or more paths.

   Individual fields are explained below:

   SYSTEM CUR DIR

      Identifies the current directory. This field only applies when the path
      specification does not proceed from the root directory.

   FILE TYPES TO DISPLAY

      Specifies the types of files that are to be displayed.  You can specify
      "D" for directories only, "F" for files only, or "B" for both files and
      directories.

   SEARCH SUBDIRECTORIES

      This field lets you specify whether the search should be limited to the
      first level of the specified path or to all levels (via recursive
      search).

   PATH

      Specifies the origin for the search and optionally constrains
      conformant files to a particular file extension.  You can specify up to
      four individual paths, all of which participate in the search. Paths
      may specify different drives.

   TEXT

      Specifies the text string to look for.  You can specify up to four
      independent text strings.  If ANY of the text strings is found, the
      file containing the text appears in the resulting select list.

   CASE SENSE

      Specifies whether the TEXT string search should be for an exact match
      (CASE SENSE = Y), or for a match on upper and lower case characters
      (CASE SENSE = N).

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.7 {DRIVE SEARCH (Option 3.E)}

   Panel 3.E presents the search function from a disk drive viewpoint.  It
   displays a select list of drives attached to your system which contains
   useful information about each drive.  You can then select one or more
   drives via the "s" line command and perform a variety of functions:

   *  Search for directories, on one or more drives, at one or more levels,
      from the root directory.

   *  Search for files, on one or more drives, at one or more levels, from
      the root directory.

   *  Search for files and directories, on one or more drives, at one or more
      levels, from the root directory.

   Individual fields are explained below:

   FILE TYPES TO DISPLAY

      Specifies the types of files that are to be displayed.  You can specify
      "D" for directories only, "F" for files only, or "B" for both files and
      directories.

   SEARCH SUBDIRECTORIES

      This field lets you specify whether the search should be limited to the
      first level of the specified path or to all levels (via recursive
      search).

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.8 {SAVED LISTS (Option 3.F)}

   Panel 3.F displays a select list of saved lists. In practical terms, a
   saved list is a select list that you have decided to save under a symbolic
   name.

   A typical application of saved lists is to keep track and act upon groups
   of related files. For example a programmer might be working on ten related
   source files out of a larger set. By creating and then saving a list of
   these files, he can repeatedly access them without regard to the larger
   file set. When the activity related to a particular list is complete, the
   list is deleted.  One simple way to think about saved lists is as "micro-
   projects".

   Use the SAVELIST primary command to save a list.

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.9 {FILE CONVERSION (Option 3.G)}

   Panel 3.G lets you specify a source and destination file and their
   respective profiles. In this way you can convert any file to any supported
   format.  Individual fields are explained below:

   SOURCE

      The SOURCE specification has two fields: FILENAME and PROFILE.  Specify
      the name of the source file you want to convert and the profile to be
      used for input processing of the specified file.

   DESTINATION

      The DESTINATION specification has three fields: FILENAME, PROFILE, and
      MAX LRECL.  Specify the name for the converted output file and the
      profile to be used for output processing. If you simply want to change
      the record length, use the MAX LRECL field.

   The source file is read using the source profile and then written out to
   the destination file name using the destination profile.

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.10 {MOST RECENT EDITS (Option 3.H)}

   Panel 3.H lets you reactivate a previous edit session.  Each time you edit
   a file, the file name and associated information is placed in the Most
   Recent Edits file list. This list is functionally equivalent to any of the
   3.x lists. You can use any of the super list line commands. List entries
   are in temporal order (order of creation).

   The depth of the list is controlled by the RECENT EDIT DEPTH field of
   panel 0.5.

   Note:  Files residing on removable drives (e.g. A:, B:, etc) are not
   included in the Most Recent Edits list.

   Press [F3] to return to the FILE LIST UTILITY.

   Press [F3] again to return to the Utility Selection Menu.

#  11.11 {SUPERC (Option 3.I)}

   Panel 3.I allows you to:

   *  compare one or more files in one or more directories

   *  compare files line by line or byte by byte

   *  create change reports in a variety of formats

   *  direct the change report to a variety of destinations

   Individual fields are explained below:

   NEW FILE

      NAME

         Required.  Specifies the more recent version of the file (or files)
         to be compared.  Specify one of:

         -- a fully qualified individual file name

         -- an ambiguous file name (contains * or ?)

      PROFILE

         Optional.  Specifies the profile name for reading the new file.  If
         not specified, the profile is determined by the file type.  If
         COMPARE TYPE = BYTE, the profile is ignored.

   OLD FILE

      NAME

         Required.  This is the original (or older version) of the file (or
         files) to be compared.  Specify one of:

         -- a fully qualified individual file name

         -- an ambiguous file name (contains * or ?)

      PROFILE

         Optional.  Specifies the profile name for reading the old file.  If
         not specified, the profile is determined by the file type.  If
         COMPARE TYPE = BYTE, the profile is ignored.

   Note:  The following scenarios occur when specifying new and old file
   names:

   *  NEW FILE is an individual file.  OLD FILE is a directory (or ambiguous
      file name).  In this case the "new" file is compared to the "old" file
      of the same name (if it exists) in the directory specified in OLD FILE.

   *  NEW FILE is a directory (or ambiguous file name).  OLD FILE is a
      directory (or ambiguous file name).  In this case all "new" files that
      fit the file pattern are compared to "old" files of the same name (if
      they exist) in the OLD FILE directory.

   *  NEW FILE is a directory (or ambiguous file name).  OLD FILE is an
      individual file.  In this case the "new" file (if it exists) with the
      same name as the "old" file is compared to the file specified in OLD
      FILE.

   COMPARE TYPE

      This field specifies the type of comparison to make.

      FILE

         This mode of compare is the fastest available.  It does not report
         specific differences; it simply reports if files differ (forces
         LISTING TYPE = OVSUM).

      LINE

         This mode of compare is the most intelligent comparison mode for
         program source.  It reports inserts and deletes on a line by line
         basis.

      BYTE

         This mode of compare is most useful in comparing binary or other
         non-record oriented files.  The files are compared byte by byte and
         the report provides differences in hexadecimal dump format with a
         summary.  When BYTE is specified, the PROFILE fields are ignored.

   LISTING TYPE

      This field specifies the form for the output listing of the report.

      OVSUM

         This form provides an overall summary of differences without a
         detail level report.

         Note:  When COMPARE TYPE = FILE is set, OVSUM is the only allowable
         choice.

      DELTA

         This form provides differences only in the detail level of the
         report followed by a summary.

      CHANGE

         This form provides the same data as the DELTA form with the addition
         of up to 10 matching lines before and after each differences
         section.

      LONG

         Lists the entire new file with all differences noted and a summary
         section.  This is the most detailed level of reporting available.

   OUTPUT

      This field specifies where the report is to be sent.

      BROWSE

         The report is placed in temporary file SUPERC.TMP and BROWSE is
         invoked on that file.  When you exit from BROWSE, the temporary file
         is deleted.

      PRINTER

         The report is sent to the current logical printer.  See Print Setup
         Option 0.2 for details on selecting and setting up logical printers.

      filename

         The report is placed in the specified file.

   PROCESS OPTIONS

      This field specifies a variety of special processing operations that
      may be applied to the compare.

      ANYC

         This option causes all characters to be treated as if they are
         uppercase for the purpose of the comparison. The actual file is not
         changed.  For example, with ANYC specified, "ABC" and "abc" would
         compare equal.  This option is only valid for COMPARE TYPE = LINE.

      COBOL

         This option causes characters in columns 1 through 6 to be ignored.
         In COBOL source files these columns are reserved for sequence
         numbers.  This option is only valid for COMPARE TYPE = LINE.

      STD

         This option causes the last eight characters of each fixed length
         record to be ignored.  In assembly language and some control type
         source files these columns are reserved for sequence numbers.  This
         option is only valid for COMPARE TYPE = LINE.

   COMPARE COLUMNS

      This field specifies the range of columns to which the comparison
      applies.

      START

         The first column to which the comparison applies.  Columns prior to
         the start column are ignored.

      END

         The last column to which the comparison applies.  Columns after the
         end column are ignored.

#  11.11.1 {Detail Report (Line Compare)}

   The detail report for COMPARE TYPE = LINE provides three classes of
   information regarding differences between files:

   *  Lines that are present in the old file but not present in the new file
      are displayed as "deletes" in the following form:

      D - ... text of line ...  00000 DELETED

      Where 00000 is the line sequence number in the old file.

   *  Lines that are present in the new file but not present in the old file
      are displayed as "inserts" in the following form:

      I - ... text of line ...  00000 INSERTED

      Where 000000 is the line sequence number in the new file.

   *  Lines that are present in both files are displayed when LISTING TYPE =
      CHANGE or LONG is specified.

#  11.11.2 {Detail Report (Byte Compare)}

   The byte compare detail report displays 32 hex bytes at a time (64 printed
   characters).  For each 32 byte segment, the report shows offset (OFFSET),
   matching bytes (M), inserted bytes (I), and deleted bytes (D), on three
   separate lines one above the other in the following format:

   OFFSET: 000080
   M - 6D5C6C6F   646D69 2E  7973 202F723A
   I -          31         58
   D -          34         65*

   In the example above, the asterisk (*) on the "D" line indicates that more
   than one character was deleted at that point.

   If all characters in the line match, only the M (match) line is printed.
   This case applies to LISTING TYPE = CHANGE and LONG.

#  11.11.3 {Summary Report (All Compares)}

   The summary report is always produced.  It is comprised of:

   *  date and time of comparison

   *  old and new file names on separate lines

   *  number of inserts, deletes, and matches

   *  separator line for multiple compares

   mm/dd/yy  hh:mm:ss         INSERT   DELETE   MATCH
   ... old name ...
   ... new name ...           000000   000000   000000
   ---------------------------------------------------
   ... old name ...
   ... new name ...           000000   000000   000000
   ---------------------------------------------------
   ... old name ...
   ... new name ...           000000   000000   000000
   ---------------------------------------------------

#  11.12 {Command Tables (Option 3.J)}

   This option lets you add new primary commands to the system or modify the
   behavior of existing primary commands.

#  11.13 {Partitioned Dataset Access (Option 3.K)}

   This option provides access to PC based Partitioned Datasets which are
   used to contain SPF/Pro control information such as panel definitions.

#  12. {Foreground (Option 4)}

   The SPF/Pro foreground feature allows you to set up external programs and
   utilities for execution while you are working with SPF/Pro.  Foreground
   tasks run synchronous to SPF/Pro.  Control is returned to the current
   panel when their execution is complete.  See page     for a method of
   running tasks asynchronous to SPF/Pro.

   The distinction between using FOREGROUND and executing operating system
   commands directly from the primary command field is that FOREGROUND has
   access to SPF/Pro variables which are automatically set when you edit,
   browse, select a file from a select list:

   *  &ZDSN, the fully qualified file name (path + name).  Example,
      \PROJECT1\SOURCE\ACCOUNTS.COB

   *  &ZDSNPATH, the path component of the fully qualified file name.
      Example, \PROJECT1\SOURCE

   *  &ZDSNNAME, the name component of the fully qualified file name.
      Example, ACCOUNTS.COB

   *  &ZDSBASE, The base component (file name) of the fully qualified file
      name.  Example, ACCOUNTS

   *  &ZDSNEXT, the extension component (file type) of the fully qualified
      file name.  Example, COB

   In addition, FOREGROUND eliminates the need to key in set patterns of
   parameters when you invoke commands.

   There are two foreground panels; the first panel is a select list of the
   applications you can execute.  The second panel is used when setting up a
   specific application.

   The following line commands are supported. Enter the line command to the
   left of the list entry, then press [SPF-Enter].

   B - execute an existing application in background
   C - copy an existing application
   D - delete an existing application
   E - edit an existing application
   F - execute an existing application in foreground
   R - rename an existing application
   S - execute an existing application

   To set up a new application, use the following primary command:

   S new-application-name

   To execute a specific user application directly, use the following primary
   command:

   USER application-name

#  12.1 {Setting Up a User Application}

   When you edit an application using the E line command, SPF/Pro displays
   the User Application Definition panel.  Use this panel to identify a user
   application program by drive, path, and program name. You can also set up
   a parameter that will be passed to the user application program when you
   execute it. The parameter can be a literal string, or a variable (such as
   the current filename symbol) that is resolved when the user application is
   executed.

   The information on this panel is passed to the operating system when you
   request execution of a user application.  Individual fields are explained
   below:

   USER APPLICATION NAME

      A symbolic name of your choice representing the function performed by
      the application. This is the name you type in the primary command field
      to execute the application.

   APPLICATION DESCRIPTION

      A short description of the function performed by the application.  This
      information augments the application name.

   PROGRAM

      Specify the fully qualified path name of the executable file (.EXE)
      which is to be activated by this application.

   PARMS

      Use this field to specify a parameter to be passed to the named
      program.

      You can specify literals or variables in this field. If you specify a
      variable, it will be resolved before it is passed to the operating
      system.

      The most commonly used variable is &ZDSN, the name of the last file
      Edited, Browsed, or identified with the U or UU line command in a
      select list.  This facilitates launching a compile directly out of the
      editor.

   WORKING DIRECTORY

      Some programs must execute within a directory which is different from
      the current directory.  In this case, use this field to specify the
      directory that should be used.

   After setting up the application, press [F3] to return to the Application
   Edit Selection Menu.

   After any foreground application executes, you will get the Press any key
   to continue. prompt. Press any key to dismiss the TTY screen and return to
   normal SPF/Pro operation.

   Note:  The only applications that may be executed via this option are:

   *  system commands or batch files

   *  commands serviced by COMMAND.COM (e.g. DIR)

#  13. {Background (Option 5)}

   The SPF/Pro background feature allows you to set up external programs and
   utilities for execution in parallel with SPF/Pro. This is essentially
   identical to FOREGROUND Option 4 except that applications launched via
   BACKGROUND run asynchronously to SPF/Pro under a separate process.

   See page 119 for details on setup and use.


#  14. {Command Processor (Option 6)}

   This option allows you to execute operating system commands from inside
   the SPF/Pro environment.  You can also do this from any primary command
   field. This function is primarily useful when you want to issue a series
   of operating system commands without intervening SPF/Pro operations.

   The are a number of ways to access the command processing panel:

   *  From the Primary Option Panel select Option 6, Command.

   *  From any panel use jump command =6 to go directly to Primary Option 6.

   *  From any panel use the DOS primary command without parameters.  This is
      equivalent to invoking Primary Option 6.  You can also use DOS command
      alias CMS, CP, TSO.

   There are three entry fields:

   ENTER SYSTEM COMMAND BELOW:
   ===>

   Type the command or program name and any parameters desired at the arrow
   following the field name, then press [SPF-Enter].

   FORCE KEY PRESS AFTER COMMAND EXECUTION ===> Y | N

   Specify "Y" (yes) if you want the command to run to completion and then be
   prompted before the command shell is terminated.

   Specify "N" (no) if you want the command to run to completion and
   automatically terminate the command shell.

   EXECUTE IN FOREGROUND ===> Y | N

   Specify "Y" (yes) if you want the command to suspend SPF/Pro execution
   during its execution.

   Specify "N" (no) if you want the command to run outside the process
   control of SPF/Pro. In this case, the command and SPF/Pro operate
   completely independently.

   The entry fields are followed by a table containing a command history.
   Use this table to retrieve any previously entered command to the command
   entry field.  Commands are retrieved by either the select (S) line command
   or by double-clicking the mouse on the desired comamnd.

   Command history is most recent first with automatic elimination of
   duplicates.

   The command history is maintained across SPF sessions so that you may use
   it repeatedly after fully terminating SPF/Pro.


#  15. {Dialog Test (Option 7)}

   The Dialog Test Option provides facilities for testing of modified or
   newly developed dialogs.


#  16. {Applications (Option A)}

   SPF/Pro provides custom dialogs to interface with a number of complex
   environments which are integral to the development and maintenance of
   business applications.

   MF

      This custom dialog of over 65 panels provides a comprehensive SPF style
      interface to all elements of the Micro Focus Workbench development
      tools allowing trouble free development of applications targeting the
      MVS host environment.

   XDB

      This custom dialog of over 25 panels provides a comprehensive SPF style
      interface to the XDB RDBMS DB2 emulator.  All the familiar panels found
      in DB2I are now at the workstation level.

   SAMPLES

      Sample dialog applications.


#  17. {Custom Dialog for Micro Focus}

   This custom dialog provides an SPF style interface to Micro Focus'
   workstation tools for COBOL application development.  It completely
   replaces all menus provided by Micro Focus with a more familiar SPF style
   presentation while executing in a functionally equivalent manner.

   Access is also provided to the ancilliary tools related to development of
   programs which use IMS, DB2 and CICS.

#  17.1 {Main Menu}

    SPF/Pro(1) ------------------ Custom Dialog for MF Main Menu -------------- 5.0
    OPTION===>

       0  Environment      - View the environment variables     USERID   - CTCUSER1
       1  BROWSE           - Browse source and data files       TIME     - 10:37
       2  EDIT             - Create or change source data       OPER SYS - Win95
       3  UTILITIES        - Invoke file utilities              Version  - V1
       4  FOREGROUND       - Checking, Compiling, Animating and Running
       5  BACKGROUND       - Checking, Compiling and Running in background
       6  COMMAND          - Execute operating system command
       7  DIRECTIVES       - Edit Checker Directive files
       A  About            - About Custom Dialog for MF (help has more information)
       C  CICS             - Invoke MCO and associated utilities
       D  DB2              - Invoke XDB and associated utilities
       I  IMSVS86          - Invoke IMSVS86 and associated utilities










   

   The Main Menu offers access to all the components of the custom dialog.
   These are:

   Environment

      List all environment variables.  All the system's environment variables
      are displayed in alphabetical order. Details are displayed on one
      screen, with extended lines being broken into readable components.

   BROWSE

      Browse source and data files (SPF/Pro Browse).  Source and simple data
      files can be browsed with the usual Browse utility.

   EDIT

      Edit source and data files (SPF/Pro Edit).  Source and simple data
      files can be edited with the usual Edit utility.

   UTILITIES

      Access common Workbench file utilities.  The Micro Focus utilities for
      file management are provided via this menu. The facilities available
      are listed below. A standard ISPF style interface is provided where
      possible otherwise the product's own interface is invoked.

   FOREGROUND

      The foreground options are similar to those on the mainframe providing
      familiar front end panels to drive the Micro Focus Checker, Animator
      and run time environments.

   BACKGROUND

      The background options are also similar to those on the mainframe
      providing familiar front end panels to drive the Micro Focus Checker
      and Compiler. The tasks initiated as background tasks post completion
      messages when finished.

   COMMAND

      SPF/Pro command line interface.  Execute operating system commands from
      the command line.

   DIRECTIVES

      Edit checker directives for selected COBOL dialect.  The checker
      directives files can be accessed and edited from this panel.  It lists
      all the available checker files.

   About

      Display information about Custom Dialog for Micro Focus.  Help
      information and technical support.

   CICS

      Load the Micro Focus CICS option panels if installed.

   DB2

      Load the DB2 emulator, either XDB or PC based DB2, if installed.

   IMS

      Load the Micro Focus IMS option panels if installed.

#  17.2 {Environment Variables Display List (Option 0)}

    SPF/Pro(1) ------ Custom Dialog for MF Environment Variables --- ROW 017 OF 096
    OPTION ===>

    The following list shows the current setting of the environment variables.
    The values may be scrolled up and down and left to right.

    Environment        Current          Startup Directory
    Variable           Setting          ===>E:\MASTER\SOURCE
    ------------------------------------------------------------------------------
    COBDEMO            E:\ADE\COBOL\DEMO
    COBDIR             E:\ADE\COBOL\LBR;E:\ADE\COBOL\EXEDLL;
     --->               E:\ADE\MCO\LBR;E:\ADE\IMS;e:\ade\ds\gui
    COBFSTATCONV       HOSTSTAT
    COBHNF             E:\ADE\COBOL\ON-LINE
    COMSPEC            D:\OPSYS\CMD.EXE
    CPE                E:\ADE\CP2
    DB2CHKPTR          O
    DB2INSTANCE        DB2
    DB2PATH            E:\SQLLIB
    DLSINI             D:\IBMLAN\NETPROG\NETGUI.INI
    DPATH              D:\ibmcom;D:\IBMLAN\NETPROG;D:\IBMLAN;D:\MUGLIB;

     --->               D:\OPSYS;D:\CMLIB;D:\OPSYS\SYSTEM;D:\OPSYS\INSTALL;D:\;
     --->               D:\OPSYS\BITMAP;D:\OPSYS\MDOS;D:\OPSYS\APPS;D:\MMOPSYS;
     --->               D:\MMOPSYS\INSTALL;C:\WINDOWS

   

   This panel allows you to browse the environment variable settings for the
   environment. It provides a list of all the environment variables, Micro
   Focus, XDB, as well as those set for Windows.

   The list is scrollable if it extends over more than one screen. For long
   environment variable values these are broken down over serveral lines -
   note the "--->" notation indicating continuation.

#  17.3 {Browse Source and Data Files (Option 1)}

    SPF/Pro(1) ------------------- BROWSE - ENTRY PANEL --------------------- V 5.0
    COMMAND ===>

    PROJECT FILE:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.cbl
                  (Blank or pattern for file selection list)

    SYSTEM CUR DIR: E:\MASTER\

    SYSTEM FILE SPECIFICATION:
    ===>e:\samples\*.cbl,*.cpy

    PROFILE  ===>           (Blank defaults to file extension)








   

   The source file name can be entered directly or a wild card specification
   can be used as in the example above. This results in the display of a
   selection list as seen below.

    SPF/Pro(1) ------------------- BROWSE SELECTION LIST ----------- ROW 134 OF 186
    COMMAND ===>                                                  SCROLL ===>CSR
    E:\SAMPLES
        NAME     EXT    SIZE      DATE     TIME   ATTRS COMMENTS
    ------------------------------------------------------------------------------
        PROGRAMA CBL      2190   5-01-91   2:23a  A...
        PROGRAMB CBL      2091   5-01-91   2:23a  A...
        PROGRAMC CBL      2091   5-01-91   2:23a  A...
        PRINTPRG CBL      2712   5-07-91  12:31p  A...
        PUBLISHR CPY       177   7-27-92  10:06p  A...
        READER01 CBL      3545   9-11-91  12:10p  A...
        READER02 CBL      1238   2-21-89   5:44p  A...
        REPORT01 CBL      2451   4-30-90  11:21a  A...
        REPORT02 CBL      2451   1-23-90   2:14p  A...
        REPORT03 CBL      2370   4-30-90  11:24a  A...
        REPORT04 CBL      2422   5-03-90  12:22p  A...
        ROOMPLAN CPY       178   3-29-90   4:34p  A...
        ROUTERX1 CBL       845   5-01-91   2:23a  A...

        RTS-INVO CBL     28497   4-08-91   5:23a  A...
        SALESLST CBL      4976   5-01-91   2:23a  A...
        SCREEN1  CPY      2896   4-30-90  10:07a  A...
        SCREEN2  CPY      3546   5-01-90  10:36a  A...
        SCREEN3  CPY      2407  10-09-91  11:21a  A...
        SCREEN4  CPY       375   1-25-91  11:32p  A...

   

   Source and data files can be browsed using the normal SPF/Pro Browse
   utility.

#  17.4 {Edit Source and Data Files (Option 2)}

    SPF/Pro(1) -------------------- EDIT - ENTRY PANEL ---------------------- V 5.0
    COMMAND ===>

    PROJECT FILE:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.cbl
                  (Blank or pattern for file selection list)

    SYSTEM CUR DIR: E:\MASTER

    SYSTEM FILE SPECIFICATION:
    ===>e:\samples\*.cbl,*.cpy

    PROFILE  ===>           (Blank defaults to file extension)

    MAX RECL ===>           (1..4096, new profile default = 80 )
    IMACRO   ===>
    XMACRO   ===>




   

   As with the Browse utility a file name can be entered directly or wild
   cards can be used to select a list of candidate files for editing.

   The Profile, Max Recl, IMACRO and XMACRO options allow the file to be
   viewed with alternative settings to the default for .CBL and .CPY files
   thus enabling data files, in EBCDIC for example, to be edited directly.
   See page 72 for details on profile specification.  IMACRO and XMACRO allow
   an edit macro to be applied to the file being edited, perhaps to expand
   all the COPY statements as note lines (try using the NOTECOPY macro).

   Source and data files can be edited using the normal SPF/Pro Browse
   utility.

#  17.5 {Utilities Menu (Option 3)}

   The file utilities provided by Micro Focus support development of
   mainframe programs which use non-database (IMS/DB2) files. This menu
   provides access to the most common features of the Workbench products.
   They are:

    SPF/Pro(1) ----------- Custom Dialog for MF File Utilities Options -------- 5.0
    OPTION===>


       0  HYHELP           - On line help panels
       1  MFXFER           - File transfer
       2  MDECONV          - Conversion utility for source with embedded hex
       3  DIFF             - File comparison utility
       4  MFWFL            - Workbench file loader
       5  HEXEDIT          - Hexadecimal editor
       6  DFED             - Data file editor
       7  PARMPASS         - Define runtime program Parameters
       8  MFEXTMAP         - Define DDnames for local files
       F  File-AID/PC VSAM - Invoke File-AID/PC IF INSTALLED
       P  ProxMVS          - Invoke ProxMVS IF INSTALLED

    +----------------------------------------------------------------------------+
    | File utilities are provided for supporting the development of a COBOL      |
    | program.                                                                   |
    +----------------------------------------------------------------------------+






   

   0 HYHELP

      On line help panels.  Micro Focus On-line Help gives ready access to
      detailed information about COBOL and the Workbench Products.

   MFXFER

      File transfer.  MFXFER is the intelligent file transfer mechanism
      provided by Micro Focus. The intelligence comes from the ability of the
      source file transfer mechanism to read the download/upload source for
      CALL and COPY (and INCLUDE) statements and then to append these to the
      download/upload list.

   MDECONV

      Conversion utility for source code with embedded hex.  Some downloaded
      programs contain embedded characters which are not printable (that is
      special EBCDIC codes often used as some kind of attribute in CICS and
      IMS/C programs). The conversion program MDECONV translates a source
      program in EBCDIC to ASCII but it will not alter literals containing
      any non-printable EBCDIC codes.

   DIFF

      File comparison utility.  DIFF is used to compare two source files; it
      highlights differences in content in terms of lines added, deleted and
      changed.

   MFWFL

      Workbench file loader.  MFWFL is similar to Access Methods Services on
      the mainframe and it enables the developer to convert data files from
      sequential formats to indexed and relative formats and vice versa as
      well as doing EBCDIC to ASCII conversion.

   HEXEDIT

      Hexadecimal editor.  HEXEDIT allows you to see the contents of the file
      in hexadecimal format. Internal file structure is ignored. Every byte
      of the file can be viewed in its raw form including all control
      information.

   DFED

      Data file editor.  DFED is used to edit indexed and relative files
      without the need to write a specific COBOL program for that limited
      purpose.

   PARMPASS

      Define runtime program parameters.  PARMPASS allows you to specify run
      time parameters in the absence of JCL.

   MFEXTMAP

      Define DDnames for local files.  MFEXTMAP allows you to specify DD name
      assignments in the absence of JCL.

   File-AID/PC

      Invoke FileAid-PC (if installed).  If Compuware's FileAid-PC is
      installed it can be accessed from this option.

   ProxMVS

      Invoke ProxMVS (if installed).  Proximity Software's JCL emulator
      PROXMVS can be invoked from this option if it is available.

#  17.5.1 {Online Help (HYHELP) (Option 3.0)}


    SPF/Pro(1) ------------ Custom Dialog for MF Online Help (HYHELP) --------- 5.0
    COMMAND ===>
                                 Online Help (HYHELP)

    Access to on line help provides information on all aspects of the Micro Focus
    product range. You can enter a topic which is any text string such as a COBOL
    reserved word. If no topic is entered you will be presented with the contents
    page. You may use the mouse to navigate around on line help.

        Enter optional topic ===>












    Press ENTER to continue END to exit with no action


   

   Micro Focus online help (HYHELP) is available from this menu.  It provides
   information about all aspects of the Micro Focus products from COBOL
   syntax and error messages to Checker Directives and guidance on the use of
   tools.

   Field on the panel:

   Optional topic

      Optional.  Any name, COBOL reserved word, Checker directive message
      number.  If omitted a menu is provided.

#  17.5.2 {Micro Focus File Transfer (Option 3.1)}

   The file transfer program, MFXFER, when invoked by the Utilities Option 1
   presents the Micro Focus panels for driving this program.

   MFXFER allows specification of host and workstation defaults for such
   things as PDS names containing source and copy code, target directories,
   source control commands etc.

   During the upload/download process MFXFER can be programmed to detect
   COPY, INC, INCLUDE and CALL statements and add these objects to the list
   to be transfered.

   Note:  Custom Dialog for MVS provides these same features from within the
   SPF/Pro, a seamless integration the MVS host mainframe.  Contact Command
   Technology Sales for more information. Custom Dialog for MVS also allows
   direct access to Panvalet and Librarian datasets.

#  17.5.3 {Source File Conversion (Option 3.2)}

    SPF/Pro(1) ---- Custom Dialog for MF Source File Conversion ---- ROW 001 OF 018
    COMMAND ===>
                           Source File Conversion (MDECONV)

    If the downloaded program or the program to be uploaded contains NTC's (or
    Non-Text Characters) then Source Converter will correctly deal with them.

    File name of source file ===>e:\ade\spfpc40\rexx.doc
    File name of target file ===>e:\ade\spfpc40\rexx.doc
    (if left blank the source file will be overwritten)

    Directives ===>
    Directives are listed below (the list can be scrolled)
    ------------------------------------------------------------------------------
    Directive  Description
    ASC        DEFAULT - Causes file to be converted from EBCDIC to ASCII
    BAD:A      Abort if file contains bad characters and stop
    BAD:F      Fail if file contains bad characters and go on to next one
    BAD:O      Turn checking for bad characters Off
    BAD:U      DEFAULT - Ask the user if file contains bad characters
    BAD:W      Warn the user if file contains bad characters and continue
    EBC        Causes the file to be converted from ASCII to EBCDIC
    ERR:A      Abort if the conversion errors and stop
    ERR:F      Fail if the conversion errors and go on to next one

   

   The MDECONV panel (Source File Conversion) allows you to specify the files
   for conversion and the directives to use to control the conversion. The
   directives are listed at the bottom of the screen and can be scrolled.

   Source File Conversion is required when the EBCDIC source file on the
   mainframe contains embedded hexadecimal characters for such things as
   screen attributes in CICS and IMS/DC programs. If these sources were
   converted to ASCII during the file transfer process the embedded hex
   values would be changed also.

   MDECONV converts EBCDIC to ASCII and vice versa.

   Note:  For VSC2 programmers, a new way of specifying hex constants is
   provided in COBOL (e.g. VALUE X'E231').

   Fields on the panel:

   Source file

      Required.  The name of the original source file. The usual extension is
      .CBL.  The field can have the full path specified as it is scrollable.

   Target file

      Optional.  The name of the converted source file. The usual extension
      is .CBL.  The field can have the full path specified as it is
      scrollable.  If this field is omitted, the input file is also used as
      the output file.

   Directives

      Optional.  Here is where the MDECONV directives are listed. Any number
      can be typed into this scrollable field. The values which can be typed
      are shown at the bottom of the screen in a scrolling list.

#  17.5.4 {Source File Comparison (Option 3.3)}

    SPF/Pro(1) ------- Custom Dialog for MF Source File Comparison - ROW 001 OF 053
    COMMAND ===>
                             Source File Comparison (DIFF)

    This utility will allow the user to compare two files (in ASCII) and to list
    the differences. A large number of directives are available for use.

    File name of 'old' file ===>e:\backup\source\stats001.cbl
    File name of 'new' file ===>e:\master\source\stats001.cbl

    Directives ===>list(e:\work\stats0001.dif)
    Alternatively create a file called DIFF.DIR which contains these directives.

    Directive  Description
    ------------------------------------------------------------------------------
    AHEAD(n)   DEFAULT(257) - ABBR AHD - Look ahead limit - 1 to Buffer size
    ASM        DEFAULT NOASM - Don't include spaces lines or * and ; lines
    BEEP       DEFAULT NOBEEP - Beep if Diff halts
    BELL       DEFAULT NOBELL - Beep if Diff halts
    BROWSE(n)  DEFAULT(10) - ABBR BRO - Display n records if look ahead reached
    BUFFER(n)  DEFAULT(512) - ABBR BUF - Specify buffer size
    COBCPY(pat DEFAULT($COBCPY) - Path of copy/include books
    COBOL      DEFAULT NOBCOBOL - ABBR CBL - Matches in col 7 to 72 and ignore * bl
    CONFIRM    DEFAULT NOCONFIRM - ABBR CNF - Writes directives used in report

   

   The DIFF panel (Source File Comparison) allows you to specify the files
   for comparison and the directives to use to control the comparison. The
   directives are listed at the bottom of the screen and can be scrolled.
   Alternatively use SUPERC on Option 3.I.

   Fields on the panel:

   Old file name

      Required.  The name of the original or 'old' source file. The usual
      extension is .CBL.  The field can have the full path specified as it is
      scrollable.

   New file name

      Required.  The name of the replacement or 'new' source file. The usual
      extension is .CBL. The field can have the full path specified as it is
      scrollable.

   Directives

      Optional.  This is where DIFF directives are listed. Any number can be
      typed into this scrollable field. The values which can be used are in
      the table shown.

#  17.5.5 {Workbench File Loader (Option 3.4)}

    SPF/Pro(1) ----------- Custom Dialog for MF Workbench File Loader --------- 5.0
    COMMAND ===>
                            Workbench File Loader (MFWFL)

    WFL is used to convert data files from one format to another. Formats include
    line sequential, record sequential(fixed or variable), indexed sequential (f/v)
    relative (f/v), VRECGEN, mainframe report and PC report formats. In addition a
    'mask' can be created to allow for COMP and PACKED DECIMAL fields and ASCII/
    EBCDIC conversion can take place.

    If you have a profile already set up enter it here ===>.PRO











    Press ENTER to continue END to exit with no action


   

   File formats on the workstation and mainframe are similar but must be
   converted via Workbench File Loader (or FileAid/PC from Compuware if it is
   available). The correspondence between file formats is as follows:

   Other file formats are supported including Mainframe and PC report
   formats, VRECGEN and BTRIEVE.

   Field on the panel:

   Name of Profile File

      Optional.  The profile name is the name of a pre-existing file which
      has been created by Workbench File Loader. If no profile exists, leave
      this field empty and the WFL entry panel will be displayed.

#  17.5.6 {Hexadecimal Editor (Option 3.5)}

    SPF/Pro(1) ----------------- Custom Dialog for MF Hexedit ----------------- 5.0
    COMMAND ===>

                             Hexadecimal Editor (HEXEDIT)

    The HEXEDIT utility gives the ability to see both source and data files in hex.
    The same facility is available through edit by using the primary command
    HEX ON. Also, for data files when using Data File Editor, vertical hex can be
    toggled on via ALT F2.

    Enter file name ===>











    Press ENTER to continue END to exit with no action


   

   The HEXEDIT utility gives the ability to see both source and data files in
   hex.  The same facility is available through edit by using the primary
   command HEX ON. Also, for data files when using Data File Editor, vertical
   hex can be toggled on via ALT F2. Hexadecimal editing of Indexed
   Sequential and Relative files is best achieved with FileAid/PC if
   available.

   Note: Records cannot be inserted or deleted with HEXEDIT. They can only be
   updated. Hex searching is provided as well as view modes of ASCII or
   EBCDIC.

   Field on the panel:

   Name of file

      Required.  The file name is the name of a pre-existing file which needs
      to be edited.

#  17.5.7 {Data File Editor (Option 3.6)}

    SPF/Pro(1) ------------- Custom Dialog for MF Data File Editor ------------ 5.0
    COMMAND ===>
                               Data File Editor (DFED)

    The Data File Editor utility allows data files, sequential, indexed or relative
    to be edited in situ. By using the Structure Selector record layouts (copy
    books) can be superimposed upon the data and this can be done selectively.


    Enter file name ===>LIBCODED.DAT

    EBCDIC or ASCII ===>E (E/A)
    Backup file     ===>N (Y/N) Backup files are called name.DBK (Index=name.IBK)
    Full edit mode  ===>Q (F/Q) FULL (all file types) or QUICK (indexed and rel.)









    Press ENTER to continue END to exit with no action


   

   This provides easy editing of EBCDIC (and ASCII) data files especially
   Indexed and Relative forms. Alternatively you replace this option with
   FileAid/PC.

   Fields on the panel:

   Name of file

      Required.  The name of a pre-existing or new file which needs to be
      edited.

   EBCDIC or ASCII

      Required. Specify one of: 'E' or 'A'.  The choice between E and A
      invokes DFED in EBCDIC or ASCII mode.

   Backup file

      Required. Specify one of: 'Y' or 'N'.  If backup is selected the
      original data file is copied (.DAT becomes .DBK and .IDX becomes .IBK).
      This can take some time on a large data file.

   Edit Mode

      Required. Specify one of: 'F' or 'Q'.  Quick edit mode is only for
      Indexed and Relative files. It is useful on large files because they
      are not loaded into memory. Full edit (all file types) edits in memory;
      being written to disk when a save is performed.

#  17.5.8 {Parameter Passer (PARMPASS) (Option 3.7)}

   In JCL the option exists to pass data to the COBOL program's Linkage
   Section by means of the PARM= statement. As JCL is not available (unless
   PROX/MVS is used) on the Workstation the Micro Focus Workbench enables
   this data to be added to a file called PARMPASS.DAT.

    SPF/Pro(1) EDIT E:\MASTER\DATA\PARMPASS.DAT ------------------- COLUMNS 001 072
    COMMAND ===>                                                  SCROLL ===>CSR
    ****** ********************************* TOP OF DATA **************************
    000001 ********?>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    000002 PROGNAME?Description of Parameters
    000003 ********?is Y for EBCDIC and N for ASCII
    ****** ******************************** BOTTOM OF DATA ************************



















   

   Option 7 on the utility menu provides invokes the editor on this file.
   The internal format of this files is as follows:

   The the PARMPASS.DAT file does not exist, it is created for you with an
   example layout.

#  17.5.9 {External File Mapper (Option 3.8)}

   In JCL the mapping of files to DDNAMES is done with DD statements. As JCL
   does not exist on the workstation (unless PROX/MVS is used) an external
   file can be used to map DDNAMES to workstation names. This file is called
   MFEXTMAP.DAT. It can be located in the current directory or on the path
   specified by the MFEXTMAP environment variable.

    SPF/Pro(1) EDIT E:\SHELLS\MVSSHELL\MFEXTMAP.DAT --------------- COLUMNS 001 072
    COMMAND ===>                                                  SCROLL ===>CSR
    ****** ********************************* TOP OF DATA **************************
    000001 *Example layout for file external mapper file
    000002 *--------------------------------------------
    000003 *These DDNAMES are for program: XYZ123
    000004 *DDNAME   data set name
    000005 DDNAME01  MAINFILE.DAT
    000006 DDNAME01  X:\DATA\TRANFILE.DAT
    000007 DDNAME03  \PROJECT\TESTING\HISTORY.DAT
    000008 *--------------------------------------------
    ****** ******************************** BOTTOM OF DATA ************************














   

   Option 8 on the Utility Menu invokes the editor on this file.  The
   internal format of the file is as follows:

   If the MFEXTMAP.DAT file does not exist, it is created for you with an
   example layout and recommended standards.

   Note: If more than one program is being developed at the same time they
   share MFEXTMAP.DAT. If two or more programs have the same DDNAME, the
   lines for that program must be placed higher in the file to ensure they
   are detected first.

#  17.5.10 {Fileaid-PC/VS (Option 3.F)}

   Compuware's Fileaid-PC/VS can be invoked if it is installed.

   When invoked, Fileaid-PC appears in the VS (VSAM) mode and this can be
   toggled to IMS or DB2 (if installed) modes by use of F2=Change Environment
   command.

   Please note that Fileaid-PC is a self contained program an its panels are
   not modifiable nor are function key settings passed from SPF/Pro to
   Fileaid-PC.

#  17.5.11 {ProxMVS (Option 3.P)}

   Proximity Software's JCL emulator PROXMVS can be invoked from this option
   if it is available.

#  17.6 {Foreground Menu (Option 4)}

   Foreground gives access to the most common features of the Workbench
   products involved in Check, Compile, Animate and Run.

    SPF/Pro(1) ------------ Custom Dialog for MF Foreground Options ----------- 5.0
    OPTION===>
                            Foreground Processing Options

       1  CHECK                 - Check program (to .INT)
       2  COMPILE               - Compile program (to .GNT)

       3  ANIMATE Batch Non-IMS - Batch Programs (with QSAM/VSAM/DB2)
       4  ANIMATE IMS           - Batch(IMS/DB)/Online(IMS/DC) Programs (with DB2)
       5  ANIMATE CICS          - Online(CICS) Programs (with VSAM/IMS/DB2)


       6  RUN Batch Non-IMS     - Batch Programs (with QSAM/VSAM/DB2)
       7  RUN IMS               - Batch(IMS/DB)/Online(IMS/DC) Programs (with DB2)
       8  RUN CICS              - Online(CICS) Programs (with VSAM/IMS/DB2)

                           (Select option and press ENTER )
    +----------------+----------------------------------------------------+------+
    | Program Type:  | Animation or Run option:                           |Select|
    |         CICS   | Animation or Run via CICS (including CICS/IMS/DB2) | 5/8  |
    |         IMS/DB | Animation or Run via IMS (including IMS/DB/DB2)    | 4/7  |
    |         IMS/DC | Animation or Run via IMS (including IMS/DC/DB2)    | 4/7  |
    |         Other  | Animation or Run via 'Normal' (incl. Batch/DB2)    | 3/6  |
    +----------------+----------------------------------------------------+------+


   

   CHECK

      Check program (to .INT).  Programs of all kinds can be checked in this
      option. If required the CICS HLPI(IMS) or DB2(XDB) pre-processor can be
      invoked. If checker errors are detected control is passed to SPF/Pro
      Edit.

   COMPILE

      Compile program (to .GNT).  Programs can be compiled and thus have
      their code optimized.

      Note: .GNT programs cannot be animated.

   ANIMATE Batch

      Animate batch non-IMS.  Invoke the animator for all batch COBOL
      programs not using IMS or CICS.

   ANIMATE IMS

      Animate batch IMS/DB or online IMS/DC.  Invoke the animator for batch
      or online COBOL programs using IMS.

   ANIMATE CICS

      Animate online CICS.  Invoke the animator for online COBOL programs
      using CICS.

   RUN Batch

      Run batch COBOL programs not using IMS or CICS.

   RUN IMS

      Run batch or online COBOL programs using IMS.  Invoke 'native' IMS and
      start the application with a TRANCODE, /FOR, BMP, prog, psb or DLI,
      prog, psb option.

   RUN CICS

      Run online COBOL programs using CICS.  Invokes MCO (the CICS option).

#  17.6.1 {Foreground Check (Option 4.1)}

   The Check panel allows you to specify a COBOL source file to be syntax
   checked to produce .INT executables. After compilation, if any errors have

   been detected, the error messages are posted into the source file as
   =NOTE= lines allowing easy correction of syntax errors.

    SPF/Pro(1) ----------------- Custom Dialog for MF Checker ----------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE CHECKED:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.cbl

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:               PREPROCESS REQUIREMENTS:    OTHER DIRECTIVES:
    Language    ===>VSC23     EXEC SQL     ===>N (Y/N)    ________________________
    Error Pause ===>N (Y/N)   EXEC CICS    ===>N (Y/N)    ________________________
    CSI         ===>N (Y/N)   EXEC DLI     ===>N (Y/N)    ________________________
    Structure   ===>N (Y/N)   Subroutine   ===>N (Y/N)    ________________________
    Analyze     ===>N (Y/N)                               ________________________
    List to     ===>NONE    (NONE/CON/PRN:/FILE)

    Press ENTER to continue END to exit with no action



   

   The directives in use can be viewed and edited via Custom Dialog for MF
   Option 7.

   Fields on the panel:

   Name of program to be checked

      Required.  A file name of a COBOL Source (usually .CBL or .CPY).  Wild
      cards are permitted.  If specified, the 'system file spec' takes
      precedence.  If a 'wild card' is specified, SPF/Pro presents a select
      list of all files matching the search criteria.  Several programs can
      be checked by selecting each one with an 'S'. After checking the
      results are displayed alongside.  Further panel field descriptions can
      be found on the next panel.

   Directives:

      Language

         Required. Specify one of: OSVS, VSC21, VSC22, VSC23, VSC24, COB370,
         DOSVS, SAAL1, SAAL2, ANS85, MF, WB, NONE.  This specifies the
         language dialect. Details of current checker directives can be found
         via panel M.5.

                                                      continued ...


      Error Pause

         Required. Specify one of: 'Y' or 'N'.  Should a syntax error
         (information, warning, error or severe depending on the WARNING
         directive) be detected should the compilation stop? If the answer is
         Y, you have the option to continue or return to the source file to
         correct the errors.

      CSI

         Required. Specify one of: 'Y' or 'N'.  COBOL Source Information.
         CSI provides for online help information about a COBOL program. If
         this option is selected CSI becomes available in the Animator.

      Structure

         Required. Specify one of: 'Y' or 'N'.  This causes the program to be
         checked such that a hierarchical structure diagram can be presented
         during animation.

      Analyze

         Required. Specify one of: 'Y' or 'N'.  This causes the program to be
         checked such that the analyzer can be invoked during animation. The
         analyzer counts lines as they are executed.

      List to

         Required. Specify one of: CON, LPT1, LPT2, LPT3, PRN: and FILE.
         This option specifies where the listing is to be displayed. CON is
         the console (or screen), FILE is a file (name.LST), and the others
         are printers.

      Preprocess Requirements:

      EXEC SQL

         Required. Specify one of: 'Y' or 'N'.  If the program contains
         embedded SQL statements invoke the appropriate pre-processor.

      EXEC CICS

         Required. Specify one of: 'Y' or 'N'.  If the program contains EXEC
         CICS statements invoke the appropriate pre-processor.

      EXEC DLI

         Required. Specify one of: 'Y' or 'N'.  If the program contains
         embedded HLPI statements invoke the appropriate pre-processor.

      Subroutine

         Required. Specify one of: 'Y' or 'N'.  When a subroutine is compiled
         which contains embedded SQL it has to be compiled differently to a
         main-program. Main programs use the Logon and Logoff pre-processor
         directives to establish communication with the XDB Server.
         Subroutines must not do this.  If done, the linkage is lost.

         This option only takes effect if XDB Pre-process is also selected.

      Other Directives

         Optional. Five input fields are available.  Here any other checker
         directives can be added. For a full list of these directives choose
         Hyhelp =M.3.0.

   An example of selected list for compilations follows. Note how several
   programs can be selected together and the results of the compilations
   shown in the message column.

    SPF/Pro(1) ---------------- Custom Dialog Select List ---------- ROW 099 OF 145
    COMMAND ===>                                                  SCROLL ===>CSR
                                  Foreground Checker
             Type an S against each entry to action or E to Edit the file

       Name             Date      Time         Size Attr Message
    ------------------------------------------------------------------------------
        PROGRAMA CBL  1990/06/13  02:41          566  A-
        PROGRAMB CBL  1989/02/21  14:08          923  A-
        PROGRAMC CBL  1989/02/21  15:33         2955  A-
        PRINTPRG CBL  1991/09/11  12:23         4674  A-
        PUBLISHR CPY  1991/05/01  02:23         2190  A-  Check failed
        READER01 CBL  1991/05/01  02:23         2091  A-  Checked errors
        READER02 CBL  1991/05/01  02:23         2091  A-  Checked OK
        REPORT01 CBL  1991/05/07  12:31         2712  A-
        REPORT02 CBL  1991/09/11  12:10         3545  A-
        REPORT03 CBL  1989/02/21  17:44         1238  A-
        REPORT04 CBL  1990/04/30  11:21         2451  A-
        ROOMPLAN CPY  1990/01/23  14:14         2451  A-
        ROUTERX1 CBL  1990/04/30  11:24         2370  A-
        RTS-INVO CBL  1990/05/03  12:22         2422  A-
        SALESLST CBL  1991/05/01  02:23          845  A-
        SCREEN1  CPY  1991/04/08  05:23        28497  A-
        SCREEN2  CPY  1991/05/01  02:23         4976  A-

   

   The message Checker failed is issued if the checker is terminated before
   it completes the check process.  Checked errors means that syntax errors

   were detected and these can be seen as =NOTE= lines in the source be
   selecting the file again with an "E" (for Edit). If the message is Checked
   OK, there are no syntax errors and the program is ready to be tested.

#  17.6.2 {Foreground Compile (Option 4.2)}

   The Compile invokes COBOL to convert .INT programs to .GNT (optimized).

    SPF/Pro(1) ----------------- Custom Dialog for MF Compiler ---------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE COMPILED:  TARGET PATH OF .GNT
       DRIVE ===>E:                           DRIVE ===>
       PATH  ===>\master                      PATH  ===>
       PATH  ===>\source                      PATH  ===>
       PATH  ===>                             PATH  ===>
       NAME  ===>*.cbl                     (note any .INT and .IDY will be deleted)

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    ASM         ===>N (Y/N)
    List to     ===>NONE
    Bound       ===>Y (Y/N)





    Press ENTER to continue END to exit with no action


   

   Fields on the panel:

   Name of program to be compiled

      Required.  A file name of a checked program (.INT). Wild card
      specification is permitted.  If present the 'system file spec' is used
      in preference.

   Directives:

      ASM

         Required. Specify one of: 'Y' or 'N'.  This specifies whether an
         assembly listing is to be produced, or not.

      List to

         Required. Specify one of: CON, LPT1, LPT2, LPT3, PRN: and FILE.
         This option specifies where the listing is to be displayed. CON is
         the console (or screen), FILE is a file (name.LST), and the others
         are printers.

      Bound

         Required. Specify one of: 'Y' or 'N'.  Specifies whether subscript
         and index boundary checking should be done.

#  17.6.3 {Batch Animation (non-IMS) (Option 4.3)}

    SPF/Pro(1) ----------------- Custom Dialog for MF Animator ---------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE ANIMATED (WITH PARMPASS):
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.INT

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    Structure   ===>N (Y/N)
    Analyze     ===>N (Y/N)
    Zoom        ===>N (Y/N)

    Others      ===>user-session(pm) end_________________________________________
                ===>_____________________________________________________________
                ===>_____________________________________________________________

    Press ENTER to continue END to exit with no action


   

   The animation panel allows you to select the name of a program (.INT) for
   animation. Wild cards can be used and the program selected from a list.

   Fields on the panel:

   Name of program to be animated

      Required.  A file name of clean checked program with a .INT extension.
      Wild cards may be used to obtain a selection list. The system 'file
      spec' is used if present.

   Directives:

      Structure

         Required. Specify one of: 'Y' or 'N'.  This causes the program
         structure diagram to be drawn when animation commences. If the
         program has not been checked with the structure option, no structure
         will be drawn.

      Analyze

         Required. Specify one of: 'Y' or 'N'.  This causes the analyzer to
         be turned on during animation. The analyzer counts lines as they are
         executed and can be used with CSI. If the program has not been
         checked with the analyze option, this will not occur.

      Zoom

         Required. Specify one of: 'Y' or 'N'.  This option invokes the
         animator in zoom mode. That is, program execution begins without the
         animate screen. The animator appears only if an exception condition
         occurs, a break point is encountered or you type [CTRL].

      Others

         Optional.  Entry space is available for free form entry of other
         Animator directives.

#  17.6.4 {Batch Animation IMS (Option 4.4)}

   To animate an IMS program the IMS Emulation environment must be loaded.
   Once the environment has loaded, the following screen is presented.


    CONNECTED TO MICRO FOCUS IMS OPTION  (Version=3.x.xx  ApplRgnID=0074)























   

   To invoke a program there are three possible methods.

   *  Enter the TRANCODE as defined in IMSCONFIG, see Option I.0

   *  Enter 'BMP,progname,psbname' for a BMP type program

   *  Enter 'DLI,progname,psbname' for a DLI type program

#  17.6.5 {Batch Run non-IMS (Option 4.6)}

   The run panel allows you to select the name of a program (.INT or .GNT)
   for execution. Wild cards can be used and the program selected from the
   list offered.

    SPF/Pro(1) ------------------- Custom Dialog for MF Run ------------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE RUN (WITH PARMPASS):
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.INT

    SYSTEM FILE SPECIFICATION:
    ===>











    Press ENTER to continue END to exit with no action


   

   Fields on the panel:

   Name of program to be run

      Required.  A file name of clean checked program with a .INT extension.
      Wild cards may be used to obtain a selection list. The system 'file
      spec' is used if present.

#  17.6.6 {Batch Run IMS (Option 4.7)}

   To run an IMS program, the IMS Emulation environment must be loaded.  Once
   the environment has loaded, the following screen is presented.


    CONNECTED TO MICRO FOCUS IMS OPTION  (Version=3.x.xx  ApplRgnID=0074)























   

   To invoke a program there are three possible methods.

   *  Enter the TRANCODE as defined in IMSCONFIG, see Option I.0

   *  Enter 'BMP,progname,psbname' for a BMP type program

   *  Enter 'DLI,progname,psbname' for a DLI type program

#  17.7 {Background Menu (Option 5)}

    SPF/Pro(1) ------------ Custom Dialog for MF Background Options ----------- 5.0
    OPTION===>
                            Background Processing Options

       1  CHECK                 - Check program (to .INT)
       2  COMPILE               - Compile program (to .GNT)

       Check and compile will execute in background, i.e. separate sessions
       will be started (START command) and will complete independently.






                           (Select option and press ENTER )









   

   Background gives access to the most common features of the Workbench
   products involved in Check and Compile. On completion of the selected
   task, the success or failure of the event is posted to the screen.

   CHECK

      Check program to produce .INT format.  Programs of all kinds can be
      checked in this option. If required the CICS HLPI(IMS) or DB2(XDB)
      pre-processor can be invoked. If checker errors are detected control is
      passed to the editor (SPF).

   COMPILE

      Compile program to produce .GNT format.  Programs can be compiled and
      thus thus have their code optimized.

      Note: .GNT programs cannot be animated.

#  17.7.1 {Background Check (Option 5.1)}

   The Check panel allows you to specify a COBOL source file to be syntax
   check to .INT executables. After compilation, the system displays the
   outcome of the check to the screen.

    SPF/Pro(1) ----------------- Custom Dialog for MF Checker ----------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE CHECKED:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.CBL

    SYSTEM FILE SPECIFICATION:
    ===>


    DIRECTIVES:               PREPROCESS REQUIREMENTS:    OTHER DIRECTIVES:
    Language    ===>VSC23     EXEC SQL     ===>N (Y/N)    ________________________
    Error Pause ===>N (Y/N)   EXEC CICS    ===>N (Y/N)    ________________________
    CSI         ===>N (Y/N)   EXEC DLI     ===>N (Y/N)    ________________________
    Structure   ===>N (Y/N)   Subroutine   ===>N (Y/N)    ________________________
    Analyze     ===>N (Y/N)                               ________________________
    List to     ===>NONE    (NONE/CON/PRN:/FILE)

    Press ENTER to continue END to exit with no action



   

   The directives in use can be viewed and edited via Custom Dialog for MF
   Option 7.

   The fields on the Background Check Panel are identical to those on the
   Foreground Check Panel described on page 142.

#  17.7.2 {Background Compile (Option 5.2)}

    SPF/Pro(1) ----------------- Custom Dialog for MF Compiler ---------------- 5.0
    COMMAND ===>

    ENTER NAME OF PROGRAM TO BE COMPILED:  TARGET PATH OF .GNT
       DRIVE ===>E:                           DRIVE ===>
       PATH  ===>\master                      PATH  ===>
       PATH  ===>\source                      PATH  ===>
       PATH  ===>                             PATH  ===>
       NAME  ===>*.CBL                     (note any .INT and .IDY will be deleted)

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    ASM         ===>N (Y/N)
    List to     ===>NONE
    Bound       ===>Y (Y/N)





    Press ENTER to continue END to exit with no action


   

   The Compile invokes COBOL to convert .INT programs to .GNT (optimized).

   The fields on the Background Compile Panel are identical to those on the
   Foreground Compile Panel described on page 146.

#  17.8 {Edit Checker Directives (Option 7)}

    SPF/Pro(1) ----------- Custom Dialog for MF Compiler Directives ----------- 5.0
    OPTION===>

       0  OSVS    - IBM OSVS COBOL Compiler (ANSI 74)
       1  VSC21   - IBM Version 2 COBOL Compiler release 1
       2  VSC22   - IBM Version 2 COBOL Compiler release 2
       3  VSC23   - IBM Version 2 COBOL Compiler release 3

       4  VSC24   - IBM Version 2 COBOL Compiler release 4
       5  COB370  - IBM COBOL 370 Compiler
       6  SAAL1   - IBM SAA Level 1
       7  SAAL2   - IBM SAA Level 2
       8  DOSVS   - IBM DOS/VS Compiler (ANSI 68)
       A  ANS85   - ANSI 85 COBOL Compiler
       C  COBOL   - Micro Focus COBOL.DIR default directive file
       M  MF      - ANSI 85 COBOL with Micro Focus extensions
       W  WB      - Default compiler directives file

    +----------------------------------------------------------------------------+
    | You can edit the compiler directive files for the particular dialect of    |
    | COBOL you are using. A backup copy of the directives file will be made.    |
    +----------------------------------------------------------------------------+




   

   This menu allows you to edit the mainframe style environment variable
   files supplied by Micro Focus. These files are found on the COBDIR
   environment variable path.

#  17.9 {IMS Menu (Option I)}

   The IMS Menus include access to the most common IMS Utilities:

    SPF/Pro(1) ----------------- Custom Dialog for MF IMS Menu ---------------- 5.0
    OPTION===>

       IMS Main Menu (access to IMSVS86 tools)

       0  IMSGEN           - IMS configuration and installation information
       1  DBDGEN           - DBDGEN and/or ZEROLOAD a database
       2  ZEROLOAD         - ZEROLOAD a database
       3  PSBGEN           - PSBGEN
       4  MFSGEN           - MFSGEN and /FOR emulation
       5  MFSPaint         - MFS Screen Painter (if installed)
       6  IMSPRINT         - Convert BTS.LST into user readable format
       7  Animate          - Invoke IMS Animation Environment
       8  Run              - Invoke IMS Run Environment
       F  File-AID/PC IMS  - Invoke File-AID/PC for IMS IF INSTALLED


                  (Select one option and press ENTER or END to exit)







   

   IMSGEN

      IMS Configuration and environment maintenance.

   DBDGEN

      Database Description Generation and Optional Zeroload.

   ZEROLOAD

      Initialize database area in preparation for receipt of data.

   PSBGEN

      Program Specification Block Generation.

   MFSGEN

      Message Format Services Generation and Optional /FOR test.

   MFSPaint

      Message Format Services Screen Painter (IMSVS86 Optional Product).

   IMSPRINT

      Convert BTS trace file to readable format and browse results.

   Animate

      Invoke Animator in 'native' IMS.

   Run

      Invoke Run in 'native' IMS.

#  17.9.1 {IMSGEN (Option I.0)}

   When the IMSGEN option is selected, the IMSGEN panel appears. This gives
   access to the following features:

   *  Define transaction codes

   *  Define logical terminal ids

      -  General configuration options

      -  Colorization options

      -  IMS Data Communications (IMSDC)

      -  IMS Database options (IMSDB) cache sizes, shared database options,
         catalog defaults etc.

   *  DBDGEN maintenance (view/delete) including BTS tracing options, 5x
      PSB/DBD information (view/delete) DB2 emulator used and IMSLIB

   *  PSBGEN maintenance (view/delete)

   *  MFSGEN information (view/delete)

   *  Reorganize DBDGEN library (The reorganize option REPRO's the file
      consolidating the space used by deleted entries and improving IMS
      performance)

   *  Reorganize PSBGEN library define USER ID, LTERM, PFKEY

   *  Reorganize MFSGEN library type, max SPA size etc.

   *  Catalog database definition

   Help for IMSGEN is included for completeness as IMSGEN does not contain
   any help. The IMSGEN panels are not modifiable as they are hard coded into
   IMSVS86.

#  17.9.2 {DBDGEN (Option I.1)}

   The DBDGEN panel allows you to select a file containing DBD macros (the
   usual naming convention is name.DBD) for generation.

    SPF/Pro(1) ------------------ Custom Dialog for MF DBDGEN ----------------- 5.0
    COMMAND ===>

    ENTER NAME OF DBD TO BE GENERATED:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.DBD

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    COPY ext        ===>CPY        blank, CPY, ASM or NULL
    Listing         ===>N          (Y/N)
    Map             ===>N          (Y/N)
    Run type        ===>NORMAL     NORMAL, PHYSONLY or VIRTONLY
    DBDGen/Zeroload ===>G          G(en only), Z(eroload only) or B(oth)




    Press ENTER to continue END to exit with no action


   

   Fields on the panel:

   Name of DBD to be generated

      Required.  A file name of DBD macros. Wild card specification is
      permitted.  If present, the 'system file spec' is used in preference.

   Directives:

      Copy ext

         Optional. Specify one of: 'blank', 'CPY', 'ASM' or 'NULL'.  This
         specifies the extension used on any file names which contain DBD
         macros in copybooks. The 'CPY' option is the usual one.

      Listing

         Required.  Specify one of: 'Y' or 'N'.  Specifies whether a hard
         copy listing is to be produced or not. If specified, a the listing
         is placed in file "name.LST" which is printable.

      Map

         Required. Specify one of: 'Y' or 'N'.  Specifies whether a
         hierarchical map of the DBD is to be generated.  The map shows
         pictorially the database hierarchy. If 'Y' is specified, the map is
         placed in file "name.MAP" which can be browsed or printed later.

      Run Type

         Required. Specify one of: 'NORMAL', 'PHYSONLY' or 'VIRTONLY'.

         -- NORMAL - both the physical and logical elements of the DBD are
            processed and generated. If the physical base segments which are
            described as logical in this DBD have not themselves been
            generated yet, the DBDGEN will fail.

         -- PHYSONLY - allows all the DBDs to have just their physical
            components generated.

         -- VIRTONLY - allows for later generation of the logical segments.

      DBDGen/Zeroload

         Required. Specify one of: 'G', 'Z' or 'B'.  This selects the action
         to be taken.

         -- If just a DBDGEN is required, select 'G' generation only.

         -- If just a Zeroload (initialization of the database and
            destruction of data - if any) is required, select 'Z'.

         -- If both a DBDGEN and a Zeroload are required, choose 'B' for
            both.

#  17.9.3 {ZEROLOAD (Option I.2)}

   If an IMS database is about to be used for the first time or if it needs
   to be re-initialized a Zeroload is performed. This panel allows the name
   of the database to entered.

    SPF/Pro(1) ---------- Custom Dialog for MF Zero Load IMS Database --------- 5.0
    COMMAND ===>

                               Zeroload and IMS Database

    If you ZEROLOAD the database all data will be lost. You must DBD Gen the
    database first. You can DBDGEN and ZEROLOAD from the DBDGEN panel.

        Enter IMS Database   ===>













    Press ENTER to continue END to exit with no action


   

   Zeroload can also be achieved via the DBDGEN panel.

   Field on the panel:

   IMS Database

      Required.  The name of a DBDGENed database. A name.GNT should exist for
      the specified database.

#  17.9.4 {PSBGEN (Option I.3)}

   The PSBGEN panel allows you to select a file name containing PSB macros
   (the usual naming convention is name.PSB) for generation.

    SPF/Pro(1) ------------------ Custom Dialog for MF PSBGEN ----------------- 5.0
    COMMAND ===>

    ENTER NAME OF PSB TO BE GENERATED:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.PSB

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    COPY ext    ===>CPY        blank, CPY, ASM or NULL
    Listing     ===>N          (Y/N)
    Verify      ===>Y          (Y/N) Y recommended






    Press ENTER to continue END to exit with no action


   

   Fields on the panel:

   Name of PSB to be generated

      Required.  A file name of PSB macros. Wild card specification is
      permitted.  If present, the 'system file spec' is used in preference.

   Directives:

      Copy ext

         Optional. Specify one of: 'blank', 'CPY', 'ASM' or 'NULL'.  This
         specifies the extension used on any file names which contain PSB
         macros in copybooks. The 'CPY' option is the usual one.

      Listing

         Required. Specify one of: 'Y' or 'N'.  Specifies whether a hard copy
         listing to be produced. If specified, the listing is placed in file
         "name.LST" which is printable.

      Verify

         Required. Specify one of: 'Y' or 'N'.  Specifies whether the PSB is
         to be validated against the DBD (effectively an ACBGEN).  It is
         recommended that this be done.

#  17.9.5 {MFSGEN (Option I.4)}

   The MFSGEN panel allows you to select a file name containing MFS macros
   (the usual naming convention is name.MFS) for generation.

    SPF/Pro(1) ------------------ Custom Dialog for MF MFSGEN ----------------- 5.0
    COMMAND ===>

    ENTER NAME OF MFS TO BE GENERATED:
       DRIVE ===>E:
       PATH  ===>\master
       PATH  ===>\source
       PATH  ===>
       NAME  ===>*.MFS

    SYSTEM FILE SPECIFICATION:
    ===>

    DIRECTIVES:
    COPY ext    ===>CPY        blank, CPY, ASM or NULL
    Listing     ===>N          (Y/N)
    /FOR        ===>Y          (Y/N)
    3270 Model  ===>MOD2       MOD2, MOD3, MOD4, MOD5 or MODEL(?)
    Stack       ===>OFF        AUTO, OFF or ON



    Press ENTER to continue END to exit with no action



   

   Fields on the panel:

   Name of MFS to be generated

      Required.  A file name of MFS macros. Wild card specification is
      permitted.  If present, the 'system file spec' is used in preference.

   Directives:

      Copy ext

         Optional. Specify one of: 'blank', 'CPY', 'ASM' or 'NULL'.  This
         specifies the extension used on any file names which contain MFS
         macros in copybooks. The 'CPY' option is the usual one.

      Listing

         Required. Specify one of: 'Y' or 'N'.  Specifies whether a hard copy
         listing to be produced. If specified, the listing is placed in file
         "name.LST" which is printable.

      /FOR

         Required. Specify one of: 'Y' or 'N'.  Specifies whether a /FOR
         message is to be issued after successful generation. If specified,
         the message is presented on the screen. The message can be modified
         for testing purposes.

      3270 Model

         Required. Specify one of: MOD2, MOD3, MOD4, MOD5, MODEL(?).  This
         indicates the target terminal type for the generation. Model2 is 80
         columns by 24 lines.

      Stack

         Required. Specify one of: 'AUTO', 'OFF' or 'ON'.

#  17.9.6 {MFSPaint (Option I.5)}

   This product allows you to Paint MFS screen layouts and then generate the
   MFS macros and copybooks for them.

   Since the SPF like dialog is hard coded, the panels cannot be modified.

   MFS Paint/MSG are optional products and do not not form part of the
   IMSVS86 product suite.

#  17.9.7 {IMSPrint (Option I.6)}

   If BTS (Batch Terminal emulator) tracing is switched on (see IMSGEN option
   3A) then a file called BTS.LST (by default) is created as programs are Run
   and Animated. This file is overwritten each time a program is run.

   Because the data is usually stored in EBCDIC, file BTS.LST is unreadable.
   IMSPRINT reads this file and converts it to ASCII with some additional
   formatting in case the file is to be printed. Once the conversion is
   complete, the file is Browsed.  Use the PRINT ALL primary command to print
   the file. The converted file is called IMSPRINT.LST.

   Note: If in IMSGEN, and the name is changed, this option will not work.

#  17.9.8 {ANIMATE (Option I.7)}

   Animate batch IMS/DB or online IMS/DC.  Invoke the animator for batch or
   online COBOL programs using IMS.

#  17.9.9 {RUN (Option I.8)}

   Run batch or online COBOL programs using IMS.  Invoke 'native' IMS and
   start the application with a TRANCODE, /FOR, BMP, prog, psb or DLI, prog,
   psb option.

#  17.9.10 {Fileaid-PC/IMS (Option I.F)}

   Compuware's Fileaid-PC/IMS can be invoked if it is installed.

   When invoked, Fileaid-PC appears in IMS mode. The mode can be toggled to
   VSAM or DB2 (if installed) by use of F2=Change Environment command.

   Fileaid-PC is a self contained program, not part of SPF/Pro.  Its panels
   are not modifiable nor are function key settings passed from SPF/Pro to
   Fileaid-PC.


#  18. {Custom Dialog for XDB}

   This custom dialog provides an ISPF/DB2I like interface to XDB Systems'
   XDB database and all of its features.

   Appropriate XDB programs are invoked in batch mode using all published
   interfaces. Options are captured in normal SPF/Pro dialogs and passed to
   XDB. Results are then presented to the user as panels or as messages
   depending on the context.

   The arrangement of options in Custom Dialog for XDB is designed to echo
   the organization of XDB itself. For example F1 on the XDB main menu is
   Create/Alter. Option 1 in Custom Dialog for XDB is also Create/Alter.

   The main menu of Custom Dialog for XDB gives access to all the main
   features of the tool. Here is a brief summary of the facilities. Further,
   more detailed, information can be obtained by selecting an option and
   selecting HELP from that panel.

    SPF/Pro(1) ----------------------- Custom Dialog for XDB ------------------ 4.0
    OPTION ===>

       Custom Dialog for XDB Main Menu

       0  XDB             - Access XDB Main Menu
       1  CREATE/ALTER    - Create/Alter Menu (location, table, or index)
       2  DATA ENTRY      - Invoke XDBEDIT (similar to DB/ProEdit)
       3  SPUFI           - SQL Processing Using File Input
       4  DCLGEN          - Invoke XDBDCLGE to gen. COBOL copybooks
       5  QMT             - Invoke XDBQMT (similar to QMF) - IF INSTALLED
       6  IMPORT          - Invoke XDBIMPOR to load data and SQL
       7  EXPORT          - Invoke XDBEXPOR to unload data and SQL
       8  Select Location - Alter current location
       9  XDB Profile     - Invoke XDBPROFI for profile and config information
      10  DATA DICTIONARY - Invoke XDBDATAD for data dictionary information
      11  Error messages  - XDB and DB2 error codes and messages
       F  File-AID/PC     - Invoke File-AID/PC for DB2 - IF INSTALLED

      Location    : SYSTEM
      Application : E:\XDBOPSYS\TUTORIAL\

      Select one option and press Enter or press END to exit.


   

   The XDB/DB2 options are listed below. The help topics are selected by
   number:

                                                        continued ...


#  18.1 {Access XDB Main Menu}

   If you require direct access to the XDB menu, this option simply invokes
   XDB in native mode. The user should have some familiarity with XDB in
   order to do this.

   By selecting this option XDB is loaded in 'native' mode. The familiar XDB
   main menu appears. The function key assignments are as XDB has defined
   them - this means that F3 is not END, instead ESC must be used to exit
   back to SPF/Pro. Menu options are:

                                             continued ...


#  18.2 {Create/Alter Menu}

   The Create/Alter menu lists three options. These are:

    SPF/Pro(1) ---------------- Custom Dialog for XDB Create/Alter ------------ 4.0
    OPTION ===>

       1  Location - Interactive Create/Alter Table
       2  Index    - Interactive Create/Alter Index
       3  Table    - Interactive Create/Alter Table

    A location must be created before objects are defined for development. Once
    it is created it must be pointed to via D.8.

    Tables and indexes will be created (by default) in the current location.








      Location    : SYSTEM
      Application : E:\XDBOPSYS\TUTORIAL\

      Select one option and press Enter or press END to exit.


   

   These three utilities work interactively to emulate the CREATE LOCATION,
   CREATE TABLE and CREATE TABLE statements.

   A LOCATION is similar in function to a DB2 subsystem. It has its own
   Catalog and can contain a number of databases, tables and indexes. It
   contains, by default, a number of databases, DSNDB04 (default database),
   DSNDB06 (system catalog), XDBACF (access control facility tables) and
   DSNDDF (local and remote locations).

   A new SQL statement is available which can be executed from SPUFI to
   define define a location. The syntax is:

    CREATE LOCATION name IN path
     [ SORT SEQUENCE EBCDIC | INSENSITIVE | SENSITIVE | USER ]
     [ FORWARD LOG name ]
     [ XDB SYSTEM TABLES ] ;

   Note:  EBCDIC sensitivity is set for the Location not for the User as
   previously. The XDB SYSTEM TABLES option allows for version 2.41 XDB
   tables.

   A TABLE is identical in XDB and DB2. It can be defined as usual with a
   CREATE TABLE statement in SPUFI as normal or Option D.1.2 allows
   interactive definition of the table.

   An INDEX is identical in XDB and DB2. It also can be defined as usual with
   a CREATE INDEX statement in SPUFI as normal or Option D.1.3 allows
   interactive definition of the table.

#  18.3 {XDB Data Entry}

   The data entry utility is designed to allow tables to be viewed and
   modified directly. Simple predicates can be specified to limit the number
   of rows which listed. Rows can be listed in single line (formatted screen
   layout) or multiple line mode.

   When this option is selected XDBEDIT is invoked directly. This means that
   function key assignments are those defined by XDB. F3 will not return
   control to SPF/Pro, however ESC will.

   Use of data entry is similar in function to the DB/ProEdit utility tool
   found in some mainframe environments.

#  18.4 {SPUFI - SQL Processing Using File Input}

   The SPUFI panel is comprised of three distinct phases:

   *  Edit SQL statements

   *  Execute SQL statements

   *  Browse results

   On the panel the fields are completed as follows:

    SPF/Pro(1) -------------------- Custom Dialog for XDB SPUFI --------------- 4.0
    COMMAND ===>

    ENTER NAME OF INPUT SQL DATASET:
       DRIVE ===> E:
       PATH  ===> \master
       PATH  ===> \source
       PATH  ===> \sql
       NAME  ===> *.sql

    OUTPUT FILE SPECIFICATION:
    ===> e:\work\results.out

    DIRECTIVES:

      Edit SQL        ===> Y (Y-yes, N-no)   Echo SQL commands ===> N (Y-yes, N-no)
      Execute SQL     ===> Y (Y-yes, N-no)
      Browse Results  ===> Y (Y-yes, N-no)


    Location    : SYSTEM
    Application : E:\XDBOPSYS\TUTORIAL\

    Press ENTER to continue END to exit with no action


   

   INPUT SQL DATASET

      The path and name of a file which contains SQL statements.  If the file
      does not exist, it is created. Usual file extension is .SQL. Blank
      offers a selection list.

   OUTPUT FILE SPEC

      The name of the results file. If it already exists, it is over-written,
      if it does not it is created.

   DIRECTIVES

      The directives control the behavior of the SPUFI emulator.

      EDIT SQL

         Cause edit to be invoked. Initially set to 'Y'.

      EXECUTE SQL

         Run XDBSQL in batch mode. Initially set to 'Y'.

      BROWSE RESULTS

         Browse the output file. Initially set to 'Y'.

   As each SQL statement is encountered it is separated and written to a
   temporary file called \XDB-n.SQL (where 'n' is the number of the SQL
   statement). Each of these files is passed, in turn, to XDBSQL in batch
   mode (/B). If the SQL statement is a SELECT, the output is sent to
   \XDB-n.RES. If SQL errors are found, they are be placed in \XDB-n.ERR.
   These files are found in the \TMP directory wherever XDB is installed.

   When all the SQL statements have been executed the files are combined into
   the designated output file. Additional 'break' lines are added to this
   file to improve the layout and to more closely reflect the mainframe look
   of SPUFI output files.

   SQL and DB2 errors are both reported. A full description of these errors
   is available via help panel D.11.

#  18.5 {DCLGEN}

   Data Control Language COBOL Copybook Generation (DCLGEN) creates a
   copybook for inclusion in COBOL programs which use embedded SQL. The
   copybooks contain a DECLARE TABLE and a record layout.  To use:

    EXEC SQL INCLUDE
        name
    END-EXEC

   where 'name' is the name of a file (extension .CPY usually) on the COBDIR
   path.

    SPF/Pro(1) --------------- Custom Dialog for XDB DCL Generation ----------- 4.0
    COMMAND ===>

    TABLE NAME               ===> CUSTOMER_ID_LIST

    FIELD PREFIX             ===>                    (if required)
    REAL OR NUMBERED PREFIX  ===> R                  (R-real, N-numbered)

    STRUCTURE NAME           ===> CUST-ID-LST        (default = 'DCL-table')

    COBOL COPYBOOK NAME      ===> E:\MASTER\COPY\CUST0001.CPY








    Location    : SYSTEM
    Application : E:\XDBOPSYS\TUTORIAL\

    Press ENTER to continue END to exit with no action


   

   The DCLGEN panel needs the following information:

   Table name

      The name of a table in the current location. If the table is in another
      location, the location should be changed via Option D.8.

   Field prefix

      A prefix for the column names.

   Real or numbered prefix

      Should the column names be used (real) or sequential numbers.

   Structure name

      The 01 level name to be used. Defaults to DCL-table name.

   COBOL copybook name

      The name of the copy book (usually name.CPY). This file is placed in
      the \XDB\DB2WB\COBCPY directory.

   Example of DCLGEN options:

   Assuming a sample table created as follows:

      CREATE TABLE SAMPLE(FIELD1 CHAR(10), FIELD2 SMALLINT, ...);

   The generated copy books are in one of the following formats:

                                            continued ...


#  18.6 {QMT - Query Management Tool}

   The Query Management Tool is an XDB utility (similar to QMF from IBM)
   which allows interactive definition of queries and report layouts for
   regularly used table interrogations.

   Access from the menu launches QMT directly. Function key assignments are
   not carried over into QMT. To return to SPF/Pro, press [ESC].

   It provides 5 main functions, Query (to run SQL queries and create simple
   report layouts), Form (to customize report layouts), Report (display a
   report), Chart (convert reports into graphs and charts) and Procedure
   (create programs to automatically run reports and forms).  Additional
   miscellaneous utilities are also provided. Import and export utilities
   allow transfer of QMT queries to and from QMF.

   QMT is an optional product which can be installed alongside XDB. It
   provides a QMF like facility which can be used to automate the selection
   of data in to reporting and interactive applications.

   QMT can import and export the underlying data used by QMF on the
   mainframe.

   If QMT is not installed, an error is reported.

#  18.7 {IMPORT}

   The Import panel of this custom dialog provides a simple interface to the
   XDBIMPOR utility which takes a file in DSNTIAUL format and uses it to
   populate a table either by replacing or appending the rows.

    SPF/Pro(1) ------------------- Custom Dialog for XDB Import --------------- 4.0
    COMMAND ===>

    ENTER NAME OF DSNTIAUL UNLOADED DATAFILE:
       DRIVE ===> E:
       PATH  ===> \master
       PATH  ===> \download
       PATH  ===>
       NAME  ===> *.dnl

    SYSTEM FILE SPECIFICATION:

    ===>

    DIRECTIVES:

      TABLE NAME     ===> CUSTOMER_ID_LIST
                             (name in format: [location.][authid.]table )
      REPLACE/APPEND ===> R  (R-replace, A-append) Replace rows or append to table
      NULLS/BLANKS   ===> N  (N-nulls, B-blanks) Treat empty flds as null or blanks

    Location    : SYSTEM
    Application : E:\XDBOPSYS\TUTORIAL\

    Press ENTER to continue END to exit with no action

   

   DSNTIAUL files can be produced on the mainframe from DB2 tables and down
   loaded or produced from XDB tables using the export utility (Option D.7).

   Panel fields:

   Unloaded datafile

      The path and name of the file containing the unloaded data

   System file

      Alternate path and name of the unloaded data file

   Directives:

      Table name

         The name of a table in the current location

      Replace/Append

         Specify whether rows are to replace those already there or be
         appended

      Nulls/Blanks

         Specify whether empty fields are to be treated as NULL or blanks

#  18.8 {EXPORT}

   The Export panel of this custom dialog provides a simple interface to the
   XDBEXPOR utility which produces a file in DSNTIAUL format. Additionally
   export can generate the SQL DDL statements to CREATE the
   table/index/synonyms.

    SPF/Pro(1) ------------------- Custom Dialog for XDB Export --------------- 4.0
    COMMAND ===>

    Export DSNTIAUL data ===> Y (Y/N)   |  Export SQL DDL source ===> Y (Y/N)
    ENTER TARGET DSNTIAUL FILE:         |  ENTER TARGET SQL DDL FILE:
       DRIVE ===> E:                    |     DRIVE ===> F:
       PATH  ===> \master               |     PATH  ===> \MASTER
       PATH  ===> \upload               |     PATH  ===> \SOURCE
       PATH  ===>                       |     PATH  ===> \SQL
       NAME  ===> *.upl                 |     NAME  ===> CUST0001.DDL
                                        |
    SYSTEM FILE SPECIFICATION:          |  SYSTEM FILE SPECIFICATION:
    ===>                                |  ===>
                                        |

    DIRECTIVES:                         | DIRECTIVES:
    Table name        ===> CUSTOMER_ID_ | Table name        ===> user.master
    (format:[location.][authid.]table)  | (format:[location.][authid.]table)
    Replace or Append ===> R (R/A)      | Replace or Append ===> R (R/A)
    ------------------------------------+ SQL Statements to generate (Y/N):
    Locn: SYSTEM                        | CREATE TABLE ===> Y INSERT  ===> N
    Appl: E:\XDBOPSYS\TUTORIAL\         | CREATE INDEX ===> Y COMMENT ===> Y

    Press ENTER to continue END to exit with no action


   

#  18.8.1 {DSNTIAUL Export Options:}

   Export DSNTIAUL data

      Specify "Y" to invoke this option.

   Target DSNTIAUL file

      Path and file name for exported data

   System file

      Alternate path and file name for exported data

   Directives:

      Table name

         The name of a table in the current location. If the table is not in
         the current location, use the location name to prefix the table
         name. If two tables exist for different users, include the Authid as
         well.

      Replace or Append

         Replace data in unloaded file or add to the end

#  18.8.2 {SQL DDL Export Options:}

   Export SQL DDL source

      Specify "Y" to invoke this option.

   Target SQL DDL file

      Path and file name for exported SQL DDL

   System file

      Alternate path and file name for SQL DDL

   Directives:

      Table name

         The name of a table in the current location. If the table is not in
         the current location, use the location name to prefix the table
         name. If two tables exist for different users, include the Authid as
         well.

      Replace or Append

         Replace SQL statements in the file or add to the end

      SQL Statements to Gen

         Select with 'Y' the options required for generation.  Options are
         CREATE TABLE, CREATE INDEX and COMMENT. If required, the INSERT DML
         statements can be produced for table loading via SPUFI.

#  18.9 {Select Location}

   When using XDB it is necessary to specify a Location and an Application
   Path which tell the RDBMS where the database files are to be found and
   where to find/place generated objects such as unloaded data and SQL DDL.

    SPF/Pro(1) -------------------- Custom Dialog for XDB Path ---------------- 4.0
    OPTION===>

       Select the required location and application path :

       Location         ===> SYSTEM

       Application Path ===> E:\XDBOPSYS\TUTORIAL\

       Enter the desired location and application path. These values will be used
       to update CONFIG.XDB.

       The location is the name of a valid location as defined in the catalog.
       The application path is the name of a valid directory for use by XDB.







    Press ENTER to continue END to exit with no action



   

   By invoking this option the program XDBPATH is executed. This in turn
   updates the CONFIG.XDB file containing this information.  Consequently,
   when XDB is started, the location and application path set here apply to
   XDB also.

   The Location is similar to a DB2 location (or DB2 sub-system) in that it
   has its own catalog and is usually associated with a separate development
   area, as with Development, Testing and Live sub-systems on the mainframe.

   The Application Path is the name of a directory which XDB uses as the
   default location for finding SQL and data files.

#  18.10 {Profile and Configuration Options}

   By selecting this option the XDB program XDBPROFI is invoked. This program
   gives access to a number of configuration options. These are listed below:

   Install Colors

      Colorization option

   Locations and Paths

      Change the default location, application path, temporary file path and
      XDB directory.

   Text Editor

      Define an alternate text editor

   Printer

      Specify the correct printer driver to use

   Sort Sequence

      Define the default sort sequence for the data

   Escape Character

      Define the character to use in front the "?" character to have it
      accepted as text.

   Abort Character

      Define the key to be used to exit XDB modules

   Prompt for Exit Conf.

      Define when exit prompts should appear in XDB modules

   Compatibility

      Select which dialect of SQL to support. Choices are XDB, DB2, ANSI, SAA
      and SQL/DS

   Date Picture

      Choices are USA (MM/DD/YYYY), European (DD.MM.YYYY), ISO (YYYY-MM-DD),
      Japanese Industrial Standard Christian Era (YYYY-MM-DD) and User
      Defined local standard.

   Edit Months

      Edit the month names from the default names in English

   Weekday Format

      Choose between 2, 3 or 4 characters for weekdays.

   Time Picture

      Choices are USA (HH:MM AM/PM), European (HH.MM.SS 24h), ISO (HH.MM.SS
      24h) and Japanese Industrial Standard Christian Era (HH.MM.SS 24h), or
      User Defined local standard.

   Money Picture

      Modify the default picture. This allows modification of the suppression
      options. Adding a national language character after the picture allows
      local currency presentation.

   Decimal Picture

      Modify the default picture of -zzzzzzzz,zzz.99.

   Floating Point Places

      Define the number of decimal places for Float columns

   Time Zone

      Specify number of hours variable from GMT.

   Change Password

      Define Users, Authids and Passwords

   Backward Logging

      Toggles backward logging on/off to allow/disallow the use of ROLLBACK
      within XDB.

   Isolation Level

      Choose between EXCLUSIVE USE (lock entire database), REPEATABLE READ
      (Read locks retained to COMMIT point), CURSOR STABILITY (Read locks
      maintained until next row read), LOCK CURRENT (lock only current row),
      DIRTY READ (No locking - read-only) or SNAPSHOT READ (access works on a
      database snapshot).

   Autocommit

      Toggles autocommit on/off. Autocommit causes all SQL statements to
      commit when they have successfully executed.

   XDB Server Name

      Select the name of the XDB server.

   Communication Protocol

      Choose the comms protocol. Choose between NETBIOS, Named Pipes, TCP/IP
      or Windows Local.

   Primary Authid

      Primary authorization identifier, usually your name.

   User defined options

      The user can add additional menu options to the XDB main menu via this
      option. These additional options can be third party or locally
      developed applications such as report writers and specialized editors.

#  18.11 {Data dictionary}

   This provides you with an interactive method of displaying the current
   situation in the catalog on a table by table or location wide basis.

#  18.12 {Error messages}

   The majority of XDB error messages and SQLCODES can be viewed with this
   option. This allows you to look up error codes online when they occur.

    SPF/Pro(1) ----- Custom Dialog for XDB DB2 Error Messages ---- ROW 0001 OF 1496
    OPTION ===>

    Location    : SYSTEM

    Application : E:\TUTORIAL\

      Scroll the list to locate the error.

       Error   Message
    ------------------------------------------------------------------------------
       +100    ROW NOT FOUND FOR FETCH, UPDATE OR DELETE, OR THE RESULT OF A QUERY
       +162    TABLESPACE [name] HAS BEEN PLACED IN CHECK PENDING
       +218    THE SQL STATEMENT REFERENCING A REMOTE OBJECT CANNOT BE EXPLAINED.
       +304    A VALUE WITH DATA TYPE [name] CANNOT BE ASSIGNED TO A HOST VARIABLE
       +402    LOCATION [name] IS UNKNOWN
       +403    THE LOCAL OBJECT REFERENCED BY THE CREATE ALIAS STATEMENT DOES NOT E
       +558    THE WITH GRANT OPTION IS IGNORED BECAUSE GRANT IS TO PUBLIC
       +560    THE WITH GRANT OPTION IS IGNORED FOR UPDATE (COLUMN-LIST)
       +561    THE ALTER AND INDEX PRIVILEGES CANNOT BE GRANTED TO PUBLIC AT ALL LO
       +625    THE DEFINITION OF TABLE [name] HAS BEEN CHANGED TO INCOMPLETE
       +802    EXCEPTION ERROR [name] HAS OCCURRED DURING [name] OPERATION ON [name]
       -007    STATEMENT CONTAINS THE ILLEGAL CHARACTER [name]
       -060    INVALID [name] SPECIFICATION: [name]
       -084    UNACCEPTABLE SQL STATEMENT

   

#  18.13 {Fileaid-PC/DB2}

   Compuware's Fileaid-PC/DB2 can be invoked if it is installed.

   When invoked Fileaid-PC appears in the DB2 mode, and this can be toggled
   to VS (VSAM) or DB2 (if installed) modes by use of F2=Change Environment
   command.

   Fileaid-PC is a self contained program, not part of SPF/Pro.  Its panels
   are not modifiable nor are function key settings passed from SPF/Pro to
   Fileaid-PC.


#  19. {Changes (Option C)}

   SPF/Pro includes a set of panels that list changes between the release you
   are running and the previous release.  If you have been regular user of
   the previous release you should check this information before using the
   new release extensively.  If you are not familiar with the previous
   release, the information on these panels is not significant.

   When you select the Changes Option, SPF/Pro displays a panel that
   functions like a table of contents. It lists the changes in the version
   you are running by number. You can select topics by number, or press [F3]
   or [SPF-Enter] to return to the main menu.

#  19.1 {Changes Main Panel}

   There are two basic ways to access the Changes panel:

   *  When you start SPF/Pro, the first screen it presents is the Primary
      Option Panel Menu.  Select option C - Changes, and SPF/Pro displays the
      Changes panel.

   *  At any time, you can use the jump feature to move directly to the
      changes panels.  Move your cursor to the command line, type =C and
      press [SPF-Enter].

   Changes are listed by topic.  Each topic identifies a general area of
   change between your release and the previous one. If you want to read a
   detailed explanation of a particular change, select it by number.  (Type
   the number on the command line and press [SPF-Enter].)

   Once you select a topic and display a text panel, two keys control the way
   you move through the remaining panels:

   [SPF-Enter]

      Moves you to the next panel.  After you have reviewed all of the text
      panels, you are returned to the Main Panel. At this point you can leave
      Changes, or take a second look at one of the topics.

   [F3] returns you to the Primary Option Menu from any CHANGES panel.


#  20. {Tutorial (Option T)}

   SPF/Pro includes on-line documentation in clear text.  Selecting Primary
   Option "T" invokes a dialog which lets you access the online documentation
   by topic or search for topics which contain a particular text string.

   Online documentation is provided in files with the .HLP extension residing
   in SPFPRO\HELP:

   You can also get into the online documentation directly by clicking on the
   HELP menu or from any panel by issuing the HELP primary command (or press
   [F1]).


#  21. {Find, Change, and Exclude}

   The FIND, CHANGE, and EXCLUDE commands are highly generalized and very
   powerful.  They allow you to search for, and operate upon, a specific
   character string or pattern throughout an entire file.  You can make
   changes stepwise or globally.

   Two other commands repeat the functions. RFIND repeats the last FIND using
   the same parameters. RCHANGE repeats the last CHANGE.

   FIND highlights any string that is found.  CHANGE highlights any string
   that is changed.

#  21.1 {Basic Search and Change Format}

   The basic format of FIND, CHANGE and EXCLUDE commands is:

   FIND     string-1            [search-limits]
   CHANGE   string-1  string-2  [search-limits]
   EXCLUDE  [string-1]          [search-limits]

   Find finds a string. Change changes a string.  Exclude excludes the line
   containing the string from view.

   The string-1 parameter always specifies the search character string. The
   string-2 parameter specifies the replacement character string. These
   strings are usually very simple to specify. In addition to simple strings,
   SPF/Pro provides some very powerful facilities to handle special
   situations.

   The string parameters may be followed by several parameters that tell
   SPF/Pro where the search should begin and how it should proceed.  These
   parameters specify:

   *  Search forward or backward from the current cursor location.

   *  Search all lines in the file.

   *  Search only a specific block of lines.

   *  Exclude or include "excluded" lines from the search.

   *  Restrict the search to certain columns.

#  21.2 {Find - Change Relationship}

   The relationship between Find and Change can be used to solve a common
   problem. Suppose that you want to change all of the characters "1.0" to
   "2.0" in your documentation because you just changed version numbers. But
   also assume that you don't know if all of the characters "1.0" in your
   file refer to a version number.

   By using the relationship between FIND and CHANGE you can find each
   instance of "1.0" and then decide whether to change it or leave it alone.

   First, scroll to the top of the file. Then, issue the following command:

   CHANGE 1.0 2.0

   Then press [F5] to find the next "1.0".  This is where the subtle but
   powerful interaction begins; the RFIND command applied by [F5] uses the
   parameters specified in the pending CHANGE primary command.  Now having
   found the first instance of "1.0", if you wish to change it, press [F6].

   If you don't want to change it, press [F5] again to continue to the next
   "1.0".

   Note:  This example assumes you have not redefined [F5] or [F6].

#  21.3 {Find - Exclude Relationship}

   The problem described in the previous sub-section can also be solved using
   the relationship between the FIND and EXCLUDE commands.

   The first relationship this solution uses is that the FIND command makes
   excluded lines containing the find string visible.

   The second relationship this solution uses is that one parameter of the
   change command limits the change to non-excluded lines.

   Now for the solution:

   First, use the EXCLUDE primary command to exclude all lines:

   EXCLUDE ALL

   Note:  You could also use the X or XX edit line commands to accomplish the
   same thing.

   Second, use the FIND primary command the make all "1.0" lines visible.

   FIND 1.0 ALL

   Third, use the X line command selectively to exclude lines containing
   "1.0" that you do not want to change.  Now, only lines containing "1.0"
   that you want to change are visible.

   Next, use the CHANGE primary command to change only non-excluded lines
   containing "1.0" to "2.0".

   CHANGE 1.0 2.0 ALL NX

   Finally, use the RESET primary command to make all lines visible.

   RESET EXCLUDE

   To review:

   *  All these commands are entered in the primary command field or by
      function key.

   *  To exclude all lines (make them invisible): EXCLUDE ALL

   *  To find all lines with a particular string (make them visible): FIND
      string ALL

   *  To find an instance of a particular string: FIND string

   *  To find the next instance of a particular string: RFIND ([F5])

   *  To alter an instance of a string to a new value: C string1 string2

   *  To step through the file considering each instance of a target string
      for possible change: RFIND ([F5]) then RCHANGE ([F6])

#  21.4 {Specifying Strings}

   FIND, CHANGE, and EXCLUDE commands include strings as parameters.

   The first string, string-1 is a search string.  The second string,
   string-2 is a replacement string.  SPF/Pro provides several flexible and
   powerful methods for specifying these strings.

#  21.4.1 {Simple Strings}

   If a search string is specified without quotes and does not contain
   blanks, commas, or asterisks, it is a simple string.  Simple strings are
   case insensitive. For example:

   FIND AB

   would find any combination of the letters A and B in upper or lower case:
   AB, ab, aB, or Ab.

#  21.4.2 {Delimited Strings}

   If a string contains blanks, commas, or asterisks, it must be enclosed in
   quotes to insure proper processing. When a string is enclosed in single or
   double quotes, it is a delimited string. For example:

   FIND 'all good men'

   If single or double quotes are part of the string, it must be enclosed in
   the opposite quote type.  For example:

   CHANGE  "they can't"  "they won't" all
   CHANGE  '"hello all"'  '"good-bye all"'

   If you wish to specify an empty string (null), enter two adjacent quotes.
   For instance, if you want to delete all occurrences of "FREE" from your
   file, issue the following command:

   CHANGE  FREE '' ALL

#  21.4.3 {Character Strings}

   Character strings are case sensitive. The comparison is made using exactly
   the string specified and no other. For example:

   FIND C'AB'

   finds AB; does not find ab, aB, or Ab.

#  21.4.4 {Hex Strings}

   If you want to find or change hexadecimal strings, you must specify the
   hex delimiter character X followed immediately by hexadecimal digit pairs
   in quotes. For example:

   FIND X'2C'



   You can search for generic characters such as "any number", or "any
   non-blank" using picture strings. A picture string is specified with the P

   prefix character followed by the picture string in quotes. For example,
   P"... picture string ...".  The picture string may contain any combination
   of picture characters and normal text characters.

   As an example let's say you want to find all references to error messages
   in a particular set of document source files and that the messages have
   the form "ERRnnn" where "nnn" is any three digit number.  To find and
   display exclusively all lines containing an error message:

   EXCLUDE ALL     (make all lines invisible)
   FIND P'ERR###'  (make "ERRnnn" lines visible)

   With the foregoing example in mind, the following picture strings may be
   specified in string-1:

   P'='

      Any character

   P'^'

      Any non-blank character

   P'.'

      Any non-ASCII character (decimal 0 - 31, 127 - 255)

   P'#'

      Any numeric character (0 - 9)

   P'-'

      Any non-numeric character

   P'@'

      Any alphabetic character

   P'<'

      Any lower case alphabetic character

   P'>'

      Any upper case alphabetic character

   P'$'

      Any special character (neither numeric nor alphabetic)

   In the CHANGE command when picture strings are used, string-2 must conform
   to the following rules:

   *  string-1 and string-2 must be same length

   *  string-2 picture chars are limited to:

   P'='

      The character in string-1 is to be unchanged.

   P'<'

      If the character in string-1 is alphabetic upper-case, change it to
      lower-case.

   P'>'

      If the character in string-1 is alphabetic lower-case, change it to
      upper-case.

   Picture strings may be any combination of picture characters and normal
   text characters.  The following command finds any string that:

   *  begins with a blank

   *  is followed by two numerics

   *  is followed by a blank character

   *  and ends with a non-numeric

   FIND P' ## -'

   The following command changes all characters in columns 56-60 to blanks.

   CHANGE p'=' ' ' 56 60 all

   The following command would change all characters to upper case.

   change all P'=' P'>'

#  21.4.6 {Asterisk (*) Strings}

   String-1 or string-2 can be specified as a single asterisk (*). In that
   case, the values from the corresponding string in the previous FIND,
   CHANGE, or EXCLUDE command are used.

#  21.5 {Limiting Search and Replace Functions}

#  21.5.1 {Range Search}

   The search for string-1 may be limited to a specific range of lines. To do
   this, include the line labels of the first and last line of the range of
   lines to be searched. Both labels must be used.  If a search is limited to
   a single labeled line, enter that label twice, as the first and last line
   of the range.

   Line labels are created using the "." line command.  The system provides
   some built-in labels for commonly used file positions:

   .ZF

      The first line of the file.

   .ZFIRST

      The first line of the file.

   .ZL

      The last line of the file.

   .ZLAST

      The last line of the file.

   .ZCSR

      The cursor line.

   For example, the following command finds all occurrences of the word "boy"
   between the lines labeled .A and .B.

   find boy .a .b all

   The following example changes the first occurrence of "this" to "that"
   between the first line of the file and the line on which the cursor is
   positioned.

   change this that .zf .zcsr

#  21.5.2 {Direction of Search}

   Additional operands are provided to control the starting point and the
   direction of a search:

   NEXT

      Start at the current cursor location and search forward to find the
      next string-1 match.

   ALL

      Start at the top of data line and search forward to find all matches
      with string-1 until the bottom of data line is reached.

   FIRST

      Start at the top of data line and search forward to find the first
      string-1 match.

   LAST

      Start at the bottom of data line and search backward until a string-1
      match is made.

   PREV

      Start at the current cursor location and search backward until a
      string-1 match is made.

   If the direction of search is forward (NEXT, ALL or FIRST specified), then
   RFIND and RCHANGE ([F5] and [F6]) moves the cursor forward from one
   occurrence of string-1 to the next.

   If the direction of search is backward (LAST or PREV specified), then
   RFIND and RCHANGE ([F5] and [F6]) moves the cursor backward from one
   occurrence of string-1 to the previous.

   If either "TOP OF DATA REACHED" or "BOTTOM OF DATA REACHED" messages are
   displayed, RFIND and RCHANGE ([F5] and [F6]) may be used to "wrap around"
   the file to search through the unsearched portion.

   Note: If you want to search for a string that contains one of the
   FIND/CHANGE/EXCLUDE keywords like "next" or "all", the words must be
   enclosed within quotes:

   FIND "all the king's men"
   CHG "next time" "last time" ALL

#  21.5.3 {String Matching Parameters}

   Another set of parameters allow you to limit the matching of characters to
   words, prefixes of words, or suffixes of words.  They are only used after
   the string is found.

   To make this explanation simpler, let's first define word-character:

   A-Z, a-z, 0-9, #, $, and @

   A word then is any string of one or more characters that is preceded and
   followed by a non-word-character. For example,

   " word "

   is a word. So is

   "(word)"

   With these examples in mind the following "word" related parameters may be
   used to further constrain searches:

   CHARS

      The search is successful whenever the specified string is found
      regardless of what precedes or follows it.  This is the SPF/Pro
      default.

   PREFIX

      The search is successful only if the string is preceded by a
      non-word-character and is followed by a word-character.

   SUFFIX

      The search is successful only if the string is preceded by a word-
      character and is followed by a non-word-character

   WORD

      The search is successful only if the string is preceded and followed by
      a non-word-character.

   PREFIX, SUFFIX, and CHARS may be abbreviated "PRE", "SUF", and "CHAR",
   respectively.

   In the following examples, with string-1 set to "DO", underscored strings
   would be found; non-underscored strings would be ignored:

   CHARS

      DO DONT ADO ADOPT 'DO' +ADO (DONT) ADO-

   PREFIX

      DO DONT ADO ADOPT 'DO' +ADO (DONT) ADO-

   SUFFIX

      DO DONT ADO ADOPT 'DO' +ADO (DONT) ADO-

   WORD

      DO DONT ADO ADOPT 'DO' +ADO (DONT) ADO-

#  21.5.4 {Search Excluded Lines}

   In addition to labeled lines, a search may be limited to previously
   excluded or non-excluded lines. If this operand is not specified, all
   lines are searched.

   X

      Search excluded (invisible) lines only.

   NX

      Search non-excluded (visible) lines only.

   For example,

   change me my all x

   would change "me" to "my" on all excluded lines.

#  21.5.5 {Column Search}

   The search for string-1 may also be limited to specified columns. Two
   numeric operands may be specified. The first specifies the column in which
   the search is to begin; the second specifies the column in which the
   search is to end. The two numbers must be separated by at least one blank
   space.

   *  If neither column-1 nor column-2 are specified, the search is limited
      to the current BOUNDS setting.

   *  If only column-1 is specified, the search is limited to that column for
      the length of string-1.

   For example, the following command finds all occurrences of ABC anywhere
   between columns 1 and 30.

   FIND ABC 1 30 ALL

   The following command finds all occurrences of ABC beginning in column 5
   exclusively.

   FIND ABC 5 ALL

   The following command changes the next occurrence of ABC in columns 8 to
   10 to DEF.

   CHG ABC DEF 8 10

   An even more efficient way to specify the same request is

   C ABC DEF 8

#  21.6 {UNDO/REDO}

   You can optionally specify that EDIT maintain a journal of alterations
   made to your file during an edit session. At any time you can undo the
   last alteration by issuing the UNDO primary command. Repeating the UNDO
   command causes successive levels of alterations to be undone.

   Having undone a particular alteration, you may then redo it by invoking
   the REDO primary command. Repeating the REDO command causes successive
   levels of undo to be redone.

   After an UNDO has been performed, restoring a previous state, it is
   possible to REDO the operation which was just undone.  However, if any
   changes are made after the UNDO but before REDO, those changes are
   recorded, eliminating the ability to REDO the last UNDO. The following
   sequence demonstrates this point:

   UNDO ... no changes ... REDO      REDO OK.
   UNDO ... changes ... REDO         REDO not OK.


#  22. {Program Source Colorization}

   When using SPF/Pro to write and maintain programs it can be helpful to
   colorize reserved words in the source of the programming language being
   used. This helps in understanding the program providing for more efficient
   authoring.

   SPF/Pro supports a simple method of specifying program source colorization
   which can be applied to the reserved words of any programming language.
   Some languages that can be easily colorized with SPF/Pro are COBOL,
   FORTRAN, PL/1, ADA, "C", PASCAL, MODULA, and other similar languages.

   Languages that make extensive use of punctuation and other special
   characters are not well suited to the reserved word colorization technique
   used by SPF/Pro. An example of this type of language would be APL.

   There are three basic components to colorization:

   1. A control file specifying the reserved words by color class.

   2. A binding of color classes to actual colors via the 0.4 Display
      Characteristics panel.

   3. A binding of the control file to a particular file type via the
      COLORMAP profile command.

   The basic premise of this support is that there are language specific
   reserved words which when colorized provide meaning to the program author.
   Further it is assumed that there may be more than one class of reserved
   words which might take on different colors.

#  22.1 {Creating Colorization Control File}

   To specify language colorization, you must create a control file in the
   SPFPRO\PROFILES directory for each language you expect to colorize.

   Colorization control files are in the form:  name.CLR  -  where "name" is
   a name of the programming language. For example, you would create
   COBOL.CLR for the COBOL programming language and C.CLR for the "C"
   programming language.

   The control file consists of records. Each record tells SPF/Pro how to
   colorize a specific element of the language in question.  Following are
   detailed description of each record type and its respective syntax.

   Reserved Word Case

      Specify how the case of the reserved words should be processed.  The
      consideration is whether the compiler recognizes reserved words in
      upper case, lower case, or mixed case:

      CASE = ASIS    (must match file exactly)

          or

      CASE = IGNORE  (compare ignoring case)

   Reserved Word Classes

      Specify up to four classes of reserved words as follows:

      WORD_COLOR1 = "word1", "word2", ... , "wordn"
      WORD_COLOR2 = "word1", "word2", ... , "wordn"
         ...
      WORD_COLOR4 = "word1", "word2", ... , "wordn"

      You can specify multiple words on the same line as shown above or you
      can specify them one word per line:

      WORD_COLOR1 = "word1",
                    "word2",
                      ...
                    "wordn"

      How you decide which reserved words go together in a class is up to
      you.  For simplicity you could put all the reserved words in a single
      class which uses a single color.

      Literal values specified in colorization control records must be
      enclosed in single or double quotes.

   Source Comments

      Specify how source comments should be processed.  For comments that
      begin in any column, that may span multiple lines, and may end in any
      column, specify a begin and end comment sequence as follows:

      BLOCK_COMMENT = "/*", "*/"    ("C" example)

      Only one BLOCK_COMMENT record is allowed.

      For comments that begin in any column, and run from that column to the
      end of the line, specify only a begin sequence as follows:

      LINE_COMMENT = "/*"    (COBOL example)
      LINE_COMMENT = "//"    (C and C++ example)

      For comments that begin in a specific column, and run from that column
      to the end of the line, specify a begin sequence and column number as
      follows:

      LINE_COMMENT = "*", "7"    (COBOL example)

      You can have as many LINE_COMMENT records as you wish designating
      different comment schemes supported by your particular compiler.

   Quoted Strings

      Specify how quoted strings should be processed:

      STRING_DELIMITERS = '"', "'"

      Most programming languages recognize strings and other literals by way
      of either a single quote or double quote delimiter. There are
      exceptions and they can be added as required. For example, DBASE
      recognizes square brackets as string delimiters ([]).

      Note that in the example above, we used the single quote to enclose the
      double quote character, and vice versa.

   Reserved Word Parsing

      Specify how reserved words should be parsed.  A reserved word is
      considered started by the left edge of the line, a blank, or any
      non-alpha or non-numeric character.  A reserved word is considered
      ended by the right edge of the line, a blank, or any non-alpha or
      non-numeric character.

      Under some circumstances you may not want a non-alpha character to
      cause a word break. For example, if the underscore character is
      commonly used in variable names, you do not want the text next to that
      character to be a reserved word candidate. You can specify characters
      which should not cause a word break as follows:

      NO_BREAK_CHAR = "_"

      You can specify as many no-break characters as desired within the
      quoted string.

   Special Characters

      Specify any individual characters that have particular meaning in the
      language being colorized. You can specify as many individual characters
      as desired in a single quoted string. The following example is from the
      "C" language colorization file:

      SPECIAL_CHARS = "(){};."

#  22.2 {Attaching Specific Colors to a Control File}

   The control file itself has no specific color assignments.  These are done
   separately so that you can re-assign colors without altering the control
   file.

   In parameter option panel 0.4 specify the colors corresponding to the
   control records in your "name.CLR" file.

#  22.3 {Activating Colorization}

   After creating a colorization control file and assigning colors via panel
   0.4, you must bind the colorization control file to a specific file type
   by setting the COLORMAP profile variable to the colorization file name
   (not including the extension).

   Get into EDIT on a program source file of the type you want to colorize.
   While in EDIT, invoke the COLORMAP primary command to bind the color map
   to the file type:

   COLORMAP  name    ("name" part of "name.CLR")

   To discontinue colorization:

   COLORMAP  NONE

   Below is a small portion of the "C" colorization control file supplied
   with SPF/Pro. If you want to see the complete version of any of the
   program colorization control files, look in SPF/Pro directory in files
   *.CLR.

   You can set colorization ON or OFF globally on Option Panel 0.5.

   From colorization control file C.CLR:

   CASE = ASIS

   WORD_COLOR1 = "#define",
                 "#if",
                 "#else",
                 "#endif"

   WORD_COLOR2 = "if",
                 "else",
                 "for",
                 "while",
                 "switch"

   WORD_COLOR3 = "char",
                 "int",
                 "short",
                 "long"

   BLOCK_COMMENT = "/*", "*/"

   LINE_COMMENT = "//"

   SPECIAL_CHARS = "(){};."


#  23. {General Primary Commands}

   SPF/Pro includes a number of commands that can be issued from any menu or
   panel. Commands in this group are known as general commands.

   All commands in this group are primary commands.  You issue primary
   commands in the command field or through PF keys.  (Notice that many
   general commands are included in the default set of PF key assignments.)

   The table below summarizes the general commands.  Following the table,
   there is detailed information about each of the general commands.

      Command     Function

      =           Jump directly to specified panel
      BROWSE      Browse a file
      COLOR       Display the current color settings (also COLOUR)
      CRETRIEV    go to primary cmd field, then retrieve last cmd
      CURSOR      Move cursor to the primary command field
      DOS         Execute external command (also CMS, CP, TSO)
      EDIT        Edit a file
      END         Return to the previous panel
      EOF         Clear entry field (assign to PF key)
      FF          Write Form-feed to active printer
      FONT        Change font (same as 0.F)
      FSPLIT      Create another full screen task
      HELP        Invoke HELP feature
      KEYBOARD    Change keyboard map (same as 0.K)
      KEYS        Display the PF key definitions
      LPRINT      Change the logical printer assignment
      PANELID     Display the panel ID
      PFSHOW      Toggle the display of the PF keys
      PRINT       Print the contents of the current screen
      REDIT       Bring up the Most Recent Edits list for inline use
      RETRIEVE    Redisplay a previous primary command
      RETURN      Return directly to the Primary Option Panel
      SPLIT       Split the screen horizontally at the cursor
      SPLITV      Split the screen vertically at the midpoint
      SWAP        Swap control to the other task
      USER        Execute user application (same as Option 4)
      VSPLIT      Split the screen vertically at the cursor

#  23.1 {= (Jump)}

   Purpose

   Use this command to move directly to any SPF/Pro panel.  Issue this
   command from any SPF/Pro panel.

   Format

   =x[.x]

   Remarks

   After you become familiar with SPF/Pro features and panels, you will find
   it faster to bypass the menu system and use this short-hand way of
   identifying the panel you want to work with.  The parameters for this
   command are simply the primary and secondary (if it applies) option
   numbers for the panel you want to move to.

   When you jump to a panel the current context is reset to the target panel.
   Thus when you exit via [F3], you are positioned to the Primary Option
   panel.

   Note:  If you are in a custom dialog, JUMP treats the panel which
   originated of the custom dialog as the base for the jump destination.

   Example

   =0

   This command would move you to Panel 0, the Parameter Options panel.

   =0.2

   This command would move you to Panel 0.2, the Printer Characteristics
   panel.

#  23.2 {BROWSE}

   Purpose

   Use this command to browse a file.

   Format

   BROWSE  file-spec

   Remarks

   The BROWSE primary command can be used anywhere.  When BROWSE is invoked,
   the current context is preserved.  When you exit BROWSE, you return to
   where you were when you invoked BROWSE.

   Note:  If you invoke BROWSE via "=1" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

   Example

   BROWSE  SAMPLE.COB

#  23.3 {COLOR}

   Purpose

   Use this command to display and change the current color settings.

   Format

   COLOR
   COLORS
   COLOUR

   Remarks

   This command displays the COLOR DEFINITIONS, which allows you to review
   and change the colors assigned to various display elements.

   The COLOR primary command can be used anywhere.  When COLOR is invoked,
   the current context is preserved.  When you exit COLOR, you return to
   where you were when you invoked COLOR.

   Note:  If you invoke COLOR via "=0.4" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

#  23.4 {CRETRIEV}

   Purpose

   Use this command to position to the primary command field and then
   redisplay previous commands.

   Format

   CRETRIEV  [ BACK ]

   Remarks

   The first execution of CRETRIEV, places the cursor in the primary command
   field; no further action is taken.  The second execution of CRETRIEV with
   no intervening primary commands, retrieves the last primary command
   executed.

   You can optionally specify BACK to alter the direction of retrieval.

   Note:  You can also use the RETRIEVE primary command which positions to
   the primary command field and retrieves the last command in a single step.

#  23.5 {CURSOR}

   Purpose

   Same as [HOME] key.  Use this command to move to the command field.

   Format

   CURSOR

   Remarks

   This command is only practical when issued with a PF key; it is not
   initially assigned to a PF key.

   The [HOME] key performs this function without [SPF-Enter] processing.

#  23.6 {DOS}

   Purpose

   Use this command to execute an operating system command or program.

   Format

   DOS [operating-system-command | program-name]
   CMS
   CP
   TSO

   Remarks

   When you issue the command, SPF/Pro turns control over to operating
   system, for execution of the command or program you specified.  Varied
   forms are provided for convenience; they all send the command to operating
   system.

   SPF/Pro dialog variables (Z...) in command parameters are automatically
   expanded.

   If no system command is specified, the entry panel for Primary Option 6
   (COMMAND) is displayed.

   Example

   To display the current directory:

   DOS DIR

   To change the current directory:

   DOS CD directory-name

   To invoke Lotus 1-2-3:

   DOS 123

   To compile the last source file edited:

   DOS COBOL &ZDSN

#  23.7 {EDIT}

   Purpose

   Use this command to edit a file.

   Format

   EDIT  file-spec
         [file-spec2]
         [file-spec...]

   Remarks

   The EDIT primary command can be used anywhere.  When EDIT is invoked, the
   current context is preserved.  When you exit EDIT, you return to where you
   were when you invoked EDIT.

   You can specify multiple file specifications. This creates a select list
   of all matching files.

   Note:  If you invoke EDIT via "=2" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

   Example

   EDIT  SAMPLE.COB

   EDIT  *.COB

   EDIT  *.COB *.CPY

   EDIT  (with no parms brings up Panel 2)

#  23.8 {END}

   Purpose

   Same as [F3] key.  Use this command to end the current function and return
   to the preceding panel.

   Format

   END

   Remarks

   If exiting the Primary Option Panel, SPF/Pro is terminated.

   If exiting the Primary Option Panel, when two or more split sessions are
   present, the active session terminates and the adjacent peer session
   becomes active.

   If exiting edit and AUTOSAVE is on, the modified file is saved.

#  23.9 {EOF}

   Purpose

   This command may be assigned to a PF key to clear an entry field.

   Format

   EOF

   Remarks

   Has same effect as CTRL-DEL erase-end-of-field.

#  23.10 {FF}

   Purpose

   Send a Form Feed command to the current logical printer.

   Format

   FF

   Remarks

   None.

#  23.11 {FONT}

   Purpose

   Change display fonts.

   Format

   FONT

   Remarks

   This command behaves identically to Option 0.F except that when you exit
   the dialog via the END command (normally [F3]), you return to the panel
   you were in when you issued the FONT command.

#  23.12 {FSPLIT}

   Purpose

   Use this command to start another full screen SPF/Pro session.

   Format

   FSPLIT

   Remarks

   Issuing FSPLIT saves the current session, starts another session, and
   swaps it into view.  The maximum number of sessions that may be started is
   set in Terminal Option 0.1.

   To swap among full screen sessions, enter the SWAP command (normally
   [F9]).

   Once a full screen session is established, it can then be split either
   horizontally or vertically (see SPLIT, SPLITV, and VSPLIT).

#  23.13 {HELP}

   Purpose

   Same as [F1] key. Use this command to display online help.

   Format

   HELP

   Remarks

   This command works one of the following ways:

   *  After an error has caused display of a short message, requesting HELP
      displays the corresponding long message which provides additional
      information.

   *  After the long message has been displayed, requesting HELP again
      displays Context Sensitive HELP for the feature you are using.

   *  If no error has occured, requesting HELP displays Context Sensitive
      HELP for the feature you are using.

   *  Specifying Primary Option Tutorial displays the online help starting at
      the Table of Contents.

#  23.14 {KEYBOARD}

   Purpose

   Change or edit the keyboard map.

   Format

   KEYBOARD
   KEYB

   Remarks

   This command behaves identically to Option 0.K except that when you exit
   the dialog via the END command (normally [F3]), you return to the panel
   you were in when you issued the KEYBOARD command.

#  23.15 {KEYS}

   Purpose

   Use this command to display and change the current PF key settings.

   Format

   KEYS

   Remarks

   This command displays PF Key Definitions, which allows you to review and
   change the commands and PFSHOW labels assigned to your PF keys.

   The KEYS primary command can be used anywhere.  When KEYS is invoked, the
   current context is preserved.  When you exit KEYS, you return to where you
   were when you invoked KEYS.

   PF key mappings and PFSHOW labels may also be set via Keyboard Option 0.K.

   Note:  If you invoke KEYS via "=0.3" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

#  23.16 {LPRINT}

   Purpose

   Use this command to change the assignment of the logical printer.

   Format

   LPRINT  [logical-printer-name]

   Remarks

   This command changes the logical printer assignment.  If no logical
   printer name is specified, the 0.2 list is presented.

   The LPRINT primary command can be used anywhere.  When LPRINT is invoked,
   the current context is preserved.  When you exit LPRINT, you return to
   where you were when you invoked LPRINT.

   Note:  If you invoke LPRINT via "=0.2" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

   Example

   LPRINT  format1

#  23.17 {PANELID}

   Purpose

   Use this command to toggle the display of the panel ID.

   Format

   PANELID  [ ON | OFF ]

   Remarks

   This command turns panel ID display ON or OFF. If no parameter is
   specified, it toggles the present panel ID display state.  When PANELID is
   ON, the panel ID is displayed in the upper left corner of all SPF/Pro
   panels.

#  23.18 {PFSHOW}

   Purpose

   Use this command to set the display mode of the PF keys, the display
   position, or the number of display lines.

   Format

   PFSHOW  [ ON | OFF ]  [ TOP | BOT ]  [ nn ]

   Remarks

   Specifies whether the PF keys are to be displayed or not, where they are
   to be displayed, and how many lines of keys are to be displayed (12 keys
   per line).  If no parameter is specified, the ON/OFF state of the PF keys
   is toggled.

   If TOP or BOT is specified, it is remembered so that subsequent toggling
   of the PFSHOW state keeps the proper display position.  If neither is
   specified, BOT is assumed.

   If a number is specified, it is remembered so that subsequent toggling of
   the PFSHOW state keeps the proper number of display lines.

   When the PF keys are visible, you can activate them by placing the mouse
   cursor on a particular key and double-clicking the left mouse button.

#  23.19 {PRINT}

   Purpose

   Use this command to print the current screen, or part or all of the
   current file.

   Format

   PRINT [ALL ]
   PRI   [PART]

   Remarks

   The printout is sent to the file or device specified in panel 0.2, Printer
   Characteristics.

   If no parameter is specified, the full screen is printed.

   For EDIT or BROWSE, if ALL is specified, the entire file contents are
   printed.

   For EDIT, if PART is specified, the block of lines identified by CC is
   printed.

#  23.20 {REDIT}

   Purpose

   Use this command to bring up the Most Recent Edits list for inline use.

   Format

   REDIT

   Remarks

   If you want to preserve the current context and do a quick edit of a file
   on the Most Recent Edits list, use this command.

#  23.21 {RETRIEVE}

   Purpose

   Same as [F12] key.  Use this command to redisplay previous commands.

   Format

   RETRIEVE  [ BACK ]

   Remarks

   You can press the PF key assigned to this command repeatedly to redisplay
   up to 10 of the previous commands you have issued.

   You can optionally specify BACK to alter the direction of retrieval.

#  23.22 {RETURN}

   Purpose

   Same as [F4] key.  Use this command to return directly to the Primary
   Option Panel.

   Format

   RETURN

   Remarks

   Issuing this command is the same as issuing multiple END commands to reach
   the Primary Option Panel.  If you are in edit, and AUTOSAVE is on, the
   file is saved as if END had been issued.

   If you are in a recursive EDIT or BROWSE, this command returns you to the
   original EDIT or BROWSE session respectively.

   Note:  If you are in a custom dialog, RETURN only goes back to the panel
   which originated of the custom dialog.

#  23.23 {SPLIT}

   Purpose

   Same as [F2] key.  Use this command to split the screen horizontally into
   two complete SPF/Pro sessions.  The split point is determined by the
   cursor position.

   Format

   SPLIT

   Remarks

   Issuing SPLIT does one of three things:

   1. If only one session has been started, SPF/Pro saves the current
      session, splits the screen horizontally at the current cursor position,
      starts a second session, and makes it the active session.

   2. If a second session has been started, SPF/Pro splits the screen
      horizontally at the current cursor position, and swaps to the other
      session.

   3. If the current session is split vertically, it is switched to a
      horizontal split.

   Note:  To swap between horizontally split sessions, enter the SWAP command
   (normally [F9]).

   SPLIT only affects the current full screen session.

#  23.24 {SPLITV}

   Purpose

   Use this command to split the screen vertically at the midpoint into two
   complete SPF/Pro sessions.

   Format

   SPLITV

   Remarks

   If only one session has been started, SPF/Pro saves the current session,
   splits the screen vertically at the midpoint, starts a second session, and
   makes it the active session.

   If a second session has been started, SPF/Pro splits the screen vertically
   at the midpoint, and swaps to the other session.

   To swap between vertically split sessions, enter the SWAP command
   (normally [F9]).

   SPLITV only affects the current full screen session.

#  23.25 {SWAP}

   Purpose

   Same as [F9] key.  Use this command to move among split screen sessions.

   Format

   SWAP

   Remarks

   Sessions are activated according to the rules listed below:

   *  If only one session is active, SWAP is treated as an FSPLIT.

   *  If you are in FSPLIT mode, SPF/Pro activates the next session in the
      ring and swaps it into view.

   *  If you are in SPLIT mode,

      -  If the second task occupies less than five lines of the screen,
         SPF/Pro swaps the positions and line counts of the sessions.

      -  If the second task occupies more than five lines of the screen,
         SPF/Pro activates the second task and moves the cursor to it,
         without changing the split point.

   *  If you are in VSPLIT mode,

      -  If the second task occupies less than ten columns of the screen,
         SPF/Pro swaps the positions and column counts of the sessions.

      -  If the second task occupies more than ten columns of the screen,
         SPF/Pro activates the second task and moves the cursor to it,
         without changing the split point.

   *  If you are in SPLITV mode, the split is at the midpoint, SPF/Pro
      activates the second task and moves the cursor to it, without changing
      the split point.

#  23.26 {USER}

   Purpose

   Use this command to execute a user application.

   Format

   USER  [user-application-name]

   Remarks

   This command executes a user application.  If no user-application-name is
   specified, Primary Option 4, Foreground list is presented.

   The USER primary command can be used anywhere.  When USER is invoked, the
   current context is preserved.  When you exit USER, you return to where you
   were when you invoked USER.

   If no application name is specified, the entry panel for Primary Option 4
   (FOREGROUND) is displayed.

   Note:  If you invoke USER via "=4" jump, the current context is not
   preserved. On exit you are returned to the Primary Option Menu.

   Example

   To invoke the Micro Focus compiler for the current edit file:

   USER MFCOMP

#  23.27 {VSPLIT}

   Purpose

   Use this command to split the screen vertically into two complete SPF/Pro
   sessions.  The split point is determined by the cursor position.

   Format

   VSPLIT

   Remarks

   If only one session has been started, SPF/Pro saves the current session,
   splits the screen vertically at the current cursor position, starts a
   second session, and makes it the active session.

   If a second session has already been started via VSPLIT (or SPLITV),
   SPF/Pro swaps to the other session.

   To swap between vertically split sessions, enter the SWAP command
   (normally [F9]).

   VSPLIT only affects the current full screen session.

#  24. {File Select List Primary Commands}

   This section covers basic ways of using file select lists.

   When you type a file specification that includes wild-card characters (*
   or ?) on an entry panel, SPF/Pro creates a file select list matching your
   specification.

   The current directory is displayed above all file select lists.  When all
   files in the list reside in the same directory, the path information is
   not included in the individual list entries.  When multiple paths are
   present, they are displayed to the right of the ATTRIBUTES field in each
   entry.

   Note:  SPF/Pro file select lists differ somewhat from the ISPF/PDF file or
   member list.  This is due to differences in the respective file systems.
   For more information on PC file systems, including directories and
   subdirectories, see the respective operating system User's Reference.

   The remainder of this chapter details the select list primary commands,
   which are summarized in the table at the end of this section.

      File Select List Primary Commands

      BOT        Position to bottom of list
      CHANGE     Change one string to another in one or more files
      CONFIRM    Display delete-confirmation screen
      DOWN       Scroll view of list down
      ERRORFILE  Set active error file name
      EXCLUDE    Exclude files specified, include all others
      FIND       Find a string in one or more files
      IMACRO     Set active IMACRO
      INCLUDE    Include files specified, exclude all others
      INSERT     Add files specified to the list
      LOCATE     Locate a specific list entry
      LRECL      Set active max record length
      MD         Make subdirectory in current select list
      PROFILE    Set active file profile
      REFRESH    Refresh list based on original file specification
      SAVELIST   Save select list under a symbolic name
      SEARCH     alias for FIND
      SELECT     Select a file or directory
      SORT       Sort the list
      TOP        Position to top of list
      UP         Scroll view of list up
      XMACRO     Set active XMACRO

#  24.1 {BOT}

   Purpose

   This is a primary command.  Use this command to position to the bottom of
   the select list.  This command also operates on file displays.

   Format

   BOTTOM
   BOT

   Remarks

   None.

#  24.2 {CHANGE}

   Purpose

   This is a primary command.  Use this command to change occurences of a
   character string in all files in a file select list.

   Format

   CHANGE str1 str2 [NEXT ][CHARS ][col1[col2]]
   CHG              [ALL  ][PREFIX]
   C                [FIRST][SUFFIX]
                    [LAST ][WORD  ]
                    [PREV ]

   Remarks

   When CHANGE is used in file select lists, it creates a sublist of all
   files containing the target string (str1).

   *  If ALL is specified, the files are automatically altered and the number
      of changes per file is displayed in the select list MESSAGE field.
      Only the files which contained the target string appear in the list.

   *  If ALL is not specified, CHANGE automatically jumps into edit on the
      first file in the list and changes the first occurence of the string.
      At this point you can press F5 (RFIND) and F6 (RCHANGE) to repeat the
      specified change on a per file basis as desired.  Press F3 (END) to
      exit the changed file, and automatically jump into the next file in the
      CHANGE list.

   See page     for a detailed description of all parameters and examples of
   use.

   Note: RANGE, X, and NX parameters are not supported in select lists.

#  24.3 {CONFIRM}

   Purpose

   This is a primary command.  Use this command to change the current setting
   for delete confirmation.

   Format

   CONFIRM [ON ]
           [OFF]

   Remarks

   When delete confirmation is ON, SPF/Pro asks you to confirm delete
   requests made in select lists via the delete line command.

   You can also set delete confirmation on the File List Utility entry panel.
   See the DELETE command for more information.

   Example

   CONFIRM OFF

#  24.4 {DOWN}

   Purpose

   This is a primary command.  Use this command to move toward the bottom of
   the file select list.  Same as [F8] key.  This command also applies to
   file displays.

   Format

   DOWN [PAGE]
        [HALF]
        [CSR ]
        [DATA]
        [MAX ]
        [nnnn]

   Remarks

   There are three ways to specify how much SPF/Pro moves when you issue the
   command:

   1. Issue the command without a scroll amount.  In this case the SCROLL
      field determines the amount scrolled.  The SCROLL field is in the upper
      right corner of the screen.

   2. Issue the command with a scroll amount.  Type the command and the
      amount, or type the amount and press the appropriate PF key.

   3. Change the SCROLL field and execute step 1.

   Note:  Scroll amounts can be abbreviated. For example, P for PAGE, M for
   MAX, etc.

   Example

   [F8]

   Move down by amount specified in SCROLL field.

   DOWN 8

   Move down eight lines.

   Type 8 in command field, then press [F8]

   Also, move down eight lines.

#  24.5 {ERRORFILE}

   Purpose

   This is a primary command.  Use this command to set the name of the active
   error file.  This command also applies to file displays.

   Format

   ERRORFILE  file-name

   Remarks

   If you can direct your compiler to assign a specific name to its error
   message file and append error messages as each file compiles, then you can
   have SPF/Pro automatically incorporate the error messages for a specific
   file into that file when you edit it from the select list.

   Example

   The following example directs that error messages in errorfile MSVC.LOG be
   incorporated into any file which is edited from this select list.

   ERRORFILE MSVC.LOG

#  24.6 {EXCLUDE}

   Purpose

   This is a primary command.  Use this command to exclude a specific group
   of files from the current select list.

   Format

   EXCLUDE  file-spec
   EXC      [ file-spec2 ]
   EX       [ file-spec... ]

   Remarks

   Standard operating system wild card characters are accepted.

   Individual files or blocks of files can be excluded using the x or xx line
   commands respectively.

   You can specify multiple file specifications. This creates a select list
   of all matching files.

   Example

   EXCLUDE TEST1.BAK

   EXCLUDE *.BAK

   EXCLUDE *.BAK *.TMP

#  24.7 {FIND}

   Purpose

   This is a primary command.  Use this command to search all files in the
   list for a string, word or characters, creating a sublist of files that
   contain the target string.

   Format

   FIND str1 [NEXT ][CHARS ][col1[col2]]
   F         [ALL  ][PREFIX]
             [FIRST][SUFFIX]
             [LAST ][WORD  ]
             [PREV ]

   Remarks

   After the list is created, FIND automatically jumps into the first file in
   the list and positions to the target string.  Press F3 (END) to exit the
   current file, and automatically jump into edit on the next file in the
   list.

   See page     for a detailed description of all parameters and examples of
   use.

   Note: RANGE, X, and NX parameters are not supported in select lists.

#  24.8 {IMACRO}

   Purpose

   This is a primary command.  Use this command to set the IMACRO profile
   variable.  This command also applies to file displays.

   Format

   IMACRO  macro-name

   Remarks

   The IMACRO specified is executed before each edited file.

#  24.9 {INCLUDE}

   Purpose

   This is a primary command.  Use this command to include a specific group
   of files from the current select list and exclude all others.

   Format

   INCLUDE  file-spec
   INC      [ file-spec2 ]
            [ file-spec... ]

   Remarks

   This is the inverse of EXCLUDE.  Standard operating system wild card
   characters are accepted.

   You can specify multiple file specifications. This creates a select list
   of all matching files.

   Example

   INCLUDE TEST1.COB

   INCLUDE *.COB

   INCLUDE *.COB *.CPY

#  24.10 {INSERT}

   Purpose

   This is a primary command.  Use this command to add a specific group of
   files to the current select list.

   Format

   INSERT  file-spec

   Remarks

   New files are inserted in proper sort sequence.  Standard operating system
   wild card characters are accepted.

   Example

   INSERT *.OBJ

#  24.11 {LOCATE}

   Purpose

   This is a primary command.  Use this command to locate a specific file in
   a select list.  This command also applies to file displays.

   Format

   LOCATE [FNAME]  [full name (name + extension)]
   LOC    [NAME]   [name (no extension)]
   L      [EXT]    [extension (no name)]
          [SIZE]   [file size (bytes)]
          [DATE]   [modification date (mm-dd-yy)]
          [TIME]   [modification time (hh:mm[a|p])]

   Remarks

   If found, the list is scrolled to position the requested entry at the top.

   If a keyword is specified, the search is made as directed.

   If a keyword is not specified, the search is made based on the last sort
   order of the select list.  For example, if the last sort was by date, the
   search parameter is assumed to be a date.

      If you have not sorted the select list, the last sort order is the
      default specified in the Editor Options panel.

   A number of keywords from mainframe environments are accepted as synonyms
   for SPF/Pro keywords:

   BYTES = SIZE
   TRACKS = SIZE
   CREATED = DATE
   REFERRED = DATE
   DIRECTORY = FNAME
   ORIGINAL = FNAME
   BASE = NAME
   FNAME = NAME

   Note:  For the purposes of the LOCATE command, Option 0.2 (Printer Setup),
   0.7 (Profiles), and 4 (Foreground) are considered to be in NAME sequence.

   Example

   LOCATE PRIMOPT1

   The example command positions the select list to the PRIMOPT1 entry.  If
   an exact match is not found, it positions to the nearest entry.

#  24.12 {LRECL}

   Purpose

   This is a primary command.  Use this command to set the LRECL profile
   variable.  This command also applies to file displays.

   Format

   LRECL  number

   Remarks

   The maximum record length is used at load time to check incoming records,
   and used during edit to limit the length of modified or new records for
   any file edited from the select list.

#  24.13 {MD}

   Purpose

   This is a primary command.  Use this command to make a new subdirectory in
   the current select list.

   Format

   MD  directory-name

   Remarks

   The new subdirectory is created in the path displayed at the top of the
   select list.

   Example

   MD SUB2

#  24.14 {PROFILE}

   Purpose

   This is a primary command.  Use this command to set the PROFILE profile
   variable.  This command also applies to file displays.

   Format

   PROFILE  profile-name

   Remarks

   The active profile is used in conjunction with any file edited from the
   select list.

#  24.15 {REFRESH}

   Purpose

   This is a primary command.  Use this command to refresh the select list
   using the original file specification.

   Format

   REFRESH

   Remarks

   If you SPLIT and the operate on files in the same directory that an
   earlier SPF task is opened on, the file list may become obsolete. It is
   also possible to obsolete a file list by executing non-SPF functions in
   parallel with SPF.

#  24.16 {SAVELIST}

   Purpose

   This is a primary command.  Use this command to save the current select
   list under a symbolic name for later use.

   Format

   SAVELIST  [name]
   SAVE

   Remarks

   SAVELIST presents a panel which requests a LIST NAME (if not provided) and
   DESCRIPTION.  Saved lists are accessed via Option 3.F, GROUP LIST. When
   you invoke Group List, you get a select list of saved names. You then
   select the desired name and the associated list is presented.

   Example

   SAVELIST project1

#  24.17 {SEARCH}

   Purpose

   This is a primary command.  Use this command to search all files in the
   current select list for a specific string. A sublist is created containing
   only the files which contain the specified string.

   Format

   SEARCH  [text] [CAPS | ASIS]

   Remarks

   If text is not specified, a panel is presented allowing you to specify
   multiple strings in either CAPS or ASIS form.

   If text is specified, you can optionally specify whether the search is
   ASIS or CAPS form.  If the search form is not specified, CAPS is assumed.

   This feature is most typically used to find all source modules which
   access a particular variable name or all text files referring to a
   particular subject.

   After using a list created by SEARCH you can return to the original
   context via [F3].

   Note:  SEARCH is fast but is limited to simple searches for raw text.  If
   you need more context on your search criteria, use the FIND command with
   its more general and powerful capabilities.

   Example

   Here are some examples of use:

   SEARCH  ...exact-text...  ASIS

   SEARCH  'text with blanks'

   SEARCH  textnoblanks

   SEARCH

   Specifying SEARCH without parameters results in the search panel being
   presented. You can specify up to four ASIS and four CAPS text arguments.
   If a searched file contains ANY of the specified arguments, it is included
   in the resulting sublist.

#  24.18 {SELECT}

   Purpose

   This is a primary command.  Use this command to select a list entry.

   Format

   SELECT [entry-name]
   SEL
   S

   Remarks

   Select is used in a variety of contexts:

   *  In Option 1, BROWSE, selects file to browse.

   *  In Option 2, EDIT, selects file to edit or creates a new file when a
      non-existent filename is specified.

   *  In Option 0.2, Printer Setup, selects printer setup by name.

   *  In Option 0.4, Color Definitions, selects color scheme by name.

   *  In Option 0.7, File Profiles, selects file profile to edit by name.

   *  In Option 0.K, Keyboard Mapping, selects keyboard scheme by name.

   *  In Option 4, Foreground, selects user program by name.

   If you issue this command without specifying a file, the top entry in the
   list is selected.

   If you select a subdirectory, a select list for the subdirectory is
   presented.  You can return to the original select list by pressing [F3].

   Example

   SELECT PROGRAM.COB

   This command opens PROGRAM.COB for Edit or Browse, depending on the mode
   you are in.  If the file doesn't exist, and you are in edit mode, SPF/Pro
   opens a new file with the specified name.

#  24.19 {SORT}

   Purpose

   This is a primary command.  Use this command to sort a select list.

   Format

   SORT   [FNAME]
          [NAME]
          [EXT]
          [SIZE]
          [DATE]
          [TIME]

   Remarks

   Sorting can help you find a file, review the contents of a directory, or
   set up the select list for a LOCATE command.

   Sort keywords are as follows:

   FNAME

      Sort by full name (name + extension).

   NAME

      Sort by name (no extension).

   EXT

      Sort by extension (no name).

   SIZE

      Sort by file size (bytes).

   DATE

      Sort by modification date (mm-dd-yy).

   TIME

      Sort by modification time (hh:mm[a|p]).

   A number of keywords from mainframe environments are accepted as synonyms
   for SPF/Pro keywords:

   BYTES = SIZE
   TRACKS = SIZE
   CREATED = DATE
   REFERRED = DATE
   DIRECTORY = FNAME
   ORIGINAL = FNAME
   BASE = NAME
   FNAME = NAME

   Sorting the select list before issuing a LOCATE makes the locate more
   efficient.  For example, if you issue a LOCATE DATE command on an unsorted
   select list, SPF/Pro locates the first occurrence of the date, but other
   files with the same date will be elsewhere in the select list. If you sort

   the list by date before issuing the command, after SPF/Pro locates the
   first occurrence of the specified date; adjacent files with the same date
   are also displayed.

   Note:  Sort buttons are provided on file selection lists.

   Example

   SORT EXT

   The command above sorts the select list by extension.  Files are grouped
   by extension, and the extensions are sorted into alphabetical order.

   SORT NAME DATE

   The command above sorts the select list first by name, and then by date
   within name.

#  24.20 {TOP}

   Purpose

   This is a primary command.  Use this command to position to the top of the
   select list.  This command also operates on file displays.

   Format

   TOP

   Remarks

   None.

#  24.21 {UP}

   Purpose

   This is a primary command.  Use this command to move toward the top of a
   file display or select list.  Same as [F7] key.  This command also applies
   to file displays.

   Format

   UP [PAGE]
      [HALF]
      [CSR ]
      [DATA]
      [MAX ]
      [nnnn]

   Remarks

   There are three ways to specify how much SPF/Pro moves when you issue the
   command:

   1. Issue the command without a scroll amount.  In this case the SCROLL
      field determines the amount scrolled.  The SCROLL field is in the upper
      right corner of the screen.

   2. Issue the command with a scroll amount.  Type the command and the
      amount, or type the amount and press the appropriate PF key.

   3. Change the SCROLL field and execute step 1.

   Note:  Scroll amounts can be abbreviated. For example, P for PAGE, M for
   MAX, etc.

   Example

   [F7]

   Move up by amount specified in SCROLL field.

   UP 8

   Move up eight lines.

   Type 8 in command field, then press [F7]

   Also, move up eight lines.

#  24.22 {XMACRO}

   Purpose

   This is a primary command.  Use this command to set the XMACRO profile
   variable.  This command also applies to file displays.

   Format

   XMACRO  macro-name

   Remarks

   The macro name specified is executed after each edited file.


#  25. {Select List Line Commands}

      Select List Line Commands

      B  Browse a file
      C  Copy a file
      D  Delete a file
      E  Edit a file
      G  Execute program or batch file
      I  Display information about a file
      K  Convert file format
      M  Move a file
      N  New, select file with new SPF task
      P  Print a file
      R  Rename a file
      S  Select a file
      T  Create a recursive sublist
      U  Apply a user command to a file
      X  Exclude a file from the list

   IMPORTANT INFORMATION RELATING TO SELECT LIST LINE COMMANDS:

   1. The block form of all select list line commands are supported.  For
      example, D = delete entry (or file), DD = delete block, etc.

   2. Block line commands may not overlap with other block line commands or
      individual line commands.

   3. Block line commands do not apply to directories (i.e. directories are
      ignored if they occur within a block.)

   4. Iteration counts are not supported on select list line commands.

#  25.1 {B (Browse)}

   Purpose

   This is a line command.  Use this command to open a file for Browse.

   Format

   B

   Remarks

   Type a B next to the file you want to Browse.  This command is accepted in
   3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   If you select a subdirectory, SPF/Pro displays a select list for the
   subdirectory.  You can return to the original select list by pressing
   [F3].

   Example

   __ NAME  EXT   SIZE    DATE     TIME   ATTRS

   __ MM23  DOC   2222  01-25-91  10:56a  A...
   __ MM23  SRC   2345  12-01-90  09:55a  A...
   B_ MM26  SRC   5123  10-25-90  01:23p  A...

      This command opens file MM26.SRC for Browse.

#  25.2 {C (Copy)}

   Purpose

   This is a line command.  Use this command to copy a file.

   Format

   C

   Remarks

   Type a C next to the file you want to copy.  COPY presents a panel
   requesting information on the target file.  This command is accepted in
   3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   If you copy a subdirectory, SPF/Pro copies all files and subdirectories in
   the selected subdirectory.

   Note:  If the target file already exists, you have to specify the
   OVERRIGHT FILE option in the COPY dialog.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   C_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command copies file MM26.SRC.

#  25.3 {D (Delete)}

   Purpose

   This is a line command.  Use this command to delete a file.

   Format

   D

   Remarks

   Type a D next to the file you want to delete.  If 0.6 field CONFIRM DELETE
   OF FILES = Y, DELETE presents a panel requesting confirmation of the
   delete operation.  This command is accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   If you delete a subdirectory, all files and subdirectories within that
   subdirectory are deleted.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   D_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command deletes file MM26.SRC.

#  25.4 {E (Edit)}

   Purpose

   This is a line command.  Use this command to edit a file.

   Format

   E

   Remarks

   Type an E next to the file you want to edit.  This command is accepted in
   3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   If you select a subdirectory, SPF/Pro displays a select list for the
   subdirectory.  You can return to the original select list by pressing
   [F3].

   Note:  In 3.x you can use primary command EDIT to create a new file, by
   selecting a new but valid filename.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   E_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command opens file MM26.SRC for Edit.

#  25.5 {G (Go)}

   Purpose

   This is a line command.  Use this command to execute a program or batch
   file.

   Format

   G

   Remarks

   Type a G next to the program (.EXE) or batch file (.BAT, .CMD) that you
   want to execute.  The contents of the primary command field are passed as
   parameters to the program or batch file being executed.  This command is
   accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MYAPP EXE 2222  01-25-91  10:56a  A...
   __ FOO BAT   2345  12-01-90  09:55a  A...
   G_ NEWS BAT  5123  10-25-90  01:23p  A...

      This command executes batch file NEWS.BAT.

#  25.6 {I (Information)}

   Purpose

   This is a line command.  Use this command to display attribute information
   about a file.

   Format

   I

   Remarks

   Type an I next to the file for which you want information displayed.  This
   command is accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   I_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command displays information for file MM26.SRC.

#  25.7 {K (Convert)}

   Purpose

   This is a line command.  Use this command to convert a file from one file
   format to another.

   Format

   K

   Remarks

   The file format change is effected by using different input and output
   file profiles.

   Type a K next to the file you want to convert.  Convert presents a panel
   with INPUT and OUTPUT file sections:

   *  The INPUT section is primed with the file which you identified for
      conversion. You can also specify the input file profile name.

   *  The OUTPUT section allows you to specify the output file name, the
      output file profile name, and the maximum output record length.

   This command is accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   K_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command converts file MM26.SRC.

#  25.8 {M (Move)}

   Purpose

   This is a line command.  Use this command to move a file.

   Format

   M

   Remarks

   Type an M next to the file you want to move.  MOVE presents a panel
   requesting information on the target file.  This command is accepted in
   3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   If you move a subdirectory, SPF/Pro moves all files and subdirectories in
   the selected subdirectory.

   Note:  If the target file already exists, you have to specify the
   OVERRIGHT FILE option in the MOVE dialog.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   M_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command moves file MM26.SRC.

#  25.9 {N (New)}

   Purpose

   This is a line command.  Use this command to select a file entry and
   launch a new SPF task to process the selection.

   Format

   N

   Remarks

   Normally when you select a file, the select operation invokes either EDIT
   or BROWSE on the file and stacks the select list for later use.  With NEW,
   a new SPF task is launched to directly EDIT or BROWSE the selected file.
   In this mode, the select list remains active and can be used to launch
   other file EDITS in parallel.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   N_ MM26 SRC  5123  10-25-90  01:23p  A...

   This command launches a new SPF task to directly Edit or Browse file
   MM26.SRC leaving the select list active.

#  25.10 {P (Print)}

   Purpose

   This is a line command.  Use this command to print a file or directory.

   Format

   P

   Remarks

   Type a P next to the file or directory you want to print.  If you "p" a
   file, the contents of the file are printed.  If you "p" a directory, a
   listing of the file names in that directory is printed.  This command is
   accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   It is possible to set up a variety of output destinations and formats
   using option 0.2.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   P_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command prints file MM26.SRC.

#  25.11 {R (Rename)}

   Purpose

   This is a line command.  Use this command to rename a file.

   Format

   R

   Remarks

   Type an R next to a file you want to rename.  RENAME presents a panel
   requesting information on the target file.  This command is accepted in
   3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   R_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command renames file MM26.SRC.

#  25.12 {S (Select)}

   Purpose

   This is a line command.  Use this command to select a a list entry for
   action.

   Format

   S

   Remarks

   Type an S next to the entry you want selected.  There are a variety of
   contexts in which select is operative.

   *  In Option 0.x, many of the parameter options are presented as lists in
      which you select a specific parameter entry to operate on.

   *  In Option 1, BROWSE, select applies the browse function to the file.

   *  In Option 2, EDIT, select applies the edit function to the file.

   *  In Option 3.x, many of the utility options present a file list from
      which you select a file to operate on.

   *  In Option 4, FOREGROUND, you pick a user application to run from a
      list.

   If you select a subdirectory, SPF/Pro displays a select list for the
   subdirectory. You can return to the original select list by pressing [F3].

   Note:  In edit mode, you can use primary command SELECT to create a new
   file, by selecting a new but valid filename.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   S_ MM26 SRC  5123  10-25-90  01:23p  A...

   This command selects file MM26.SRC for Edit or Browse, depending on the
   mode you are in.

#  25.13 {T (Tree)}

   Purpose

   This is a line command.  Use this command to create a list of directories
   below the selected directory.

   Format

   T

   Remarks

   Type a T next to the subdirectory you want to have recursively searched
   for lower level directories. All lower level directories are listed in a
   single flat sublist.  This command is accepted in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   You can not put a T on a normal file.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   T_ SOURCE     10-25-90  01:23p
   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   __ MM26 SRC  5123  10-25-90  01:23p  A...

      This command creates a flat sublist of all directories below
      subdirectory SOURCE.

#  25.14 {U (User)}

   Purpose

   This is a line command.  Use this command to apply a user command to a
   file.  User commands are set up in FOREGROUND, Option 4.

   Format

   U

   Remarks

   Type a U next to the file you want to apply the user command to.  USER
   presents a panel allowing you to select the desired user command.  Global
   variable &ZDSN is automatically set to the file name of the selected file
   prior to invocation of the user command.  This command is accepted in 3.x
   select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   U_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command applies a user command to file MM26.SRC.

#  25.15 {X (Exclude)}

   Purpose

   This is a line command.  Use this command to exclude a file from the
   select list.

   Format

   X

   Remarks

   Type an X next to the file you want to exclude.  This command is accepted
   in 3.x select lists.

   If 0.6, EXTENDED LINE COMMANDS = Y, this command is accepted in all select
   lists.

   Unlike edit, the RESET command does not bring excluded lines back into
   view.  If you want the entry back, just redisplay the file select list.

   Example

   __ NAME EXT  SIZE    DATE     TIME   ATTRS

   __ MM23 DOC  2222  01-25-91  10:56a  A...
   __ MM23 SRC  2345  12-01-90  09:55a  A...
   X_ MM26 SRC  5123  10-25-90  01:23p  A...

      This command excludes file MM26.SRC from the select list.

#  26. {Browse Primary Commands}

   The BROWSE function has no line commands.

   The following table summarizes the browse primary commands detailed in the
   remainder of this chapter.

      Command                  Function

      BOT       Position to bottom of file
      COLORMAP  Set active color map
      COLUMNS   Displays a line that identifies column positions
      DISPLAY   Sets non-displayable char for EBCDIC file display
      DOWN      Scroll view of file down
      FIND      Searches for a string, word, or character
      HEX       Displays text in HEX mode
      LEFT      Scroll view of file left
      LOCATE    Positions the file at a line number
      RESET     Resets columns display and excluded lines
      RFIND     Repeat last FIND command
      RIGHT     Scroll view of file right
      SCOPY     Copy selection to cut buffer
      SCREATE   Create a new file from current selection
      SPRINT    Print the current selection
      SREPLACE  Replace a file with current selection
      SXCLUDE   Exclude lines touched by current selection
      TOP       Position to top of file
      UP        Scroll view of file up

#  26.1 {BOT}

   Purpose

   Use this command to position to the bottom of the file.

   Format

   BOTTOM
   BOT

   Remarks

   None.

#  26.2 {COLORMAP}

   Purpose

   Use this command to set the active colormap for the current file type.

   Format

   COLORMAP  file-extension

   Remarks

   The colormap file is an ASCII file which contains control records which
   tell SPF/Pro how to colorize a particular file type.

   Example

   COLORMAP COBOL

   The example sets binds the COB colormap to the current file type.

   Colormaps supplied with SPF/Pro include:

   ASM
   COBOL
   C
   CPP
   PAN
   PASCAL
   PL1

#  26.3 {COLUMNS}

   Purpose

   The COLUMNS command displays a line which identifies the current column
   positions.

   Format

   COLUMNS
   COLS
   COL

   Remarks

   To remove the COLUMNS line, use the RESET command.

#  26.4 {DISPLAY}

   Purpose

   Sets the character to display in place of non-displayable EBCDIC
   characters. This command is only available in BROWSE mode.

   Format

   DISPLAY  char
   DISPL    NONE
   DISP
   DIS

   Remarks

   By default, non-displayable EBCDIC characters (ie: bytes within packed
   fields) are displayed as blanks. The DISPLAY command allows you to select
   the character to display for each non-displayable character. Also HEX ON
   displays the hex value of each character.

   Example

   DISPLAY '.'

   Specifies that the period (.) character should be displayed in place of
   any non-displayable character.

   DISPLAY NONE

   Specifies that the IBM-PC Graphics Characters should be displayed at their
   respective code points. This choice shows a unique graphic character for
   each non-displayable EBCDIC character.

   DISPLAY ' '

   Returns to the original state of displaying a blank character in place of
   any non-displayable character.

#  26.5 {DOWN}

   Purpose

   Use this command to scroll the view of the file down.

   Format

   DOWN  [ PAGE ]
         [ HALF ]
         [ CSR  ]
         [ DATA ]
         [ MAX  ]
         [ nnn  ]

   Remarks

   See page 226 for a detailed description of the parameters and examples.

#  26.6 {FIND}

   Purpose

   This command searches a file for a specific string or word.

   Format

   FIND str1 [NEXT ] [CHARS ] [col1[col2]]
   F         [ALL  ] [PREFIX]
             [FIRST] [SUFFIX]
             [LAST ] [WORD  ]
             [PREV ]

   Remarks

   FIND command parameters are free form and may be entered in any order. The
   only exception is that col2 must follow col1.

   Usually, the FIND command is issued with only the str1 parameter. In that
   case, SPF/Pro searches for the next instance of str1 starting at the
   current cursor location.  If the line is not currently displayed on the
   screen, SPF/Pro scrolls the file so that it is.

   In order to find the next string with the same value, press [F5] (RFIND).

   Although the rest of the optional parameters of FIND are not used as
   frequently, together they provide a very powerful search capability.

   The FIND command in browse is almost exactly the same as the FIND command
   in edit. The only differences are:

   *  The "X" and "NX" parameters are not valid in browse.

   *  The browse version does not have a range parameter.

   *  If col1 and col2 are not specified, the browse version searches the
      entire data width. This contrasts with the edit version which defaults
      to the columns defined by the BOUNDS command.

   Because of the similarities, the parameters for the FIND command are fully
   documented as part of the edit chapter. So, if you want to do any of the
   following:

   *  specify character strings containing blanks or quotes

   *  do case sensitive/insensitive searches

   *  search for hexadecimal strings

   *  find a line containing a string that you specified in a previous FIND

   *  match string dependent on location within a word

   *  change the direction of searching

   *  restrict searching to specific columns

   Example

   FIND ABC

   A search begins at the cursor position for "ABC".

   FIND ABC 1 20

   The search is confined to columns 1 - 20.

   FIND 'ABC D' FIRST

   Search for the first occurrence of "ABC D".

   Note:  Quotes (' or ") must surround the string when it contains embedded
   blanks.

   FIND ABC LAST

   Search for the last occurrence of ABC.

   FIND ABC ALL

   Find all occurrences of ABC and position the cursor at the first
   occurrence.

#  26.7 {HEX}

   Purpose

   This command enables or disables file display in HEX mode.

   Format

   HEX  [ON ]
        [OFF]

   Remarks

   When HEX display mode is ON, three lines of data are displayed for each
   line in your file. The first line contains the original data in ASCII
   format.  The next two lines display the same data in vertical hexadecimal
   format.  A separator line is generated between line groups as a visual
   queue.

#  26.8 {LEFT}

   Purpose

   This is a primary command.  Use this command to move toward the left edge
   of the displayed text.  Same as [F10] key.

   Format

   LEFT [PAGE]
        [HALF]
        [CSR ]
        [DATA]
        [MAX ]
        [nnnn]

   Remarks

   There are three ways to specify how much SPF/Pro moves when you issue the
   command:

   1. Issue the command without a scroll amount.  In this case the SCROLL
      field determines the amount scrolled.  The SCROLL field is in the upper
      right corner of the screen.

   2. Issue the command with a scroll amount.  Type the command and the
      amount, or type the amount and press the appropriate PF key.

   3. Change the SCROLL field and execute step 1.

   Note:  Scroll amounts can be abbreviated. For example, P for PAGE, M for
   MAX, etc.

   Example

   [F10]

   Move left by amount specified in SCROLL field.

   LEFT 8

   Move left eight columns.

   Type 8 in command field, then press [F10]

   Also, move left eight columns.

#  26.9 {LOCATE}

   Purpose

   This command scrolls the screen to a specific line number.

   Format

   LOCATE line-number
   LOC
   L

   Remarks

   Locate scrolls the file to a specific line number.

   Example

   LOC 472

   Line 472 is displayed at the top of screen.

   Different line numbering modes may result in the line number field being
   different than the requested line. For example, if you are numbering by
   10, the displayed line number for ordinal line number 472 would be 004720
   not 000472.

#  26.10 {RESET}

   Purpose

   This command resets the columns display and excluded lines.

   Format

   RESET
   RES

   Remarks

   None.

#  26.11 {RFIND}

   Purpose

   Same as [F5] key.  Use this command to repeat the last FIND command.

   Format

   RFIND

   Remarks

   This command functions in BROWSE, EDIT, and file select lists.

#  26.12 {RIGHT}

   Purpose

   This is a primary command.  Use this command to move toward the right edge
   of the displayed text.  Same as [F11] key.

   Format

   RIGHT [PAGE]
         [HALF]
         [CSR ]
         [DATA]
         [MAX ]
         [nnnn]

   Remarks

   There are three ways to specify how much SPF/Pro moves when you issue the
   command:

   1. Issue the command without a scroll amount.  In this case the SCROLL
      field determines the amount scrolled.  The SCROLL field is in the upper
      right corner of the screen.

   2. Issue the command with a scroll amount.  Type the command and the
      amount, or type the amount and press the appropriate PF key.

   3. Change the SCROLL field and execute step 1.

   Note:  Scroll amounts can be abbreviated. For example, P for PAGE, M for
   MAX, etc.

   Example

   [F11]

   Move right by amount specified in SCROLL field.

   RIGHT 8

   Move right eight columns.

   Type 8 in command field, then press [F11]

   Also, move right eight columns.

#  26.13 {SCOPY}

   Purpose

   Use this command to copy the current selection to the clipboard.

   Format

   SCOPY

   Remarks

   Selections are made with the mouse.  The selection is not deleted from the
   file.

#  26.14 {SCREATE}

   Purpose

   Use this command to create an original external file with the contents of
   the selection.

   Format

   SCREATE  [ file-name ]

   Remarks

   Selections are made with the mouse.  The selection is not deleted from the
   file.  If you don't specify a file name, a dialog panel is presented which
   enables you to enter the target file name.

   If the file already exists, SCREATE will not overwrite it.  To overwrite
   the file with the selection use SREPLACE.

#  26.15 {SPRINT}

   Purpose

   Use this command to print the current selection.

   Format

   SPRINT

   Remarks

   For all selection types, only selected characters are printed.

#  26.16 {SREPLACE}

   Purpose

   Use this command to create or replace an external file with the contents
   of the selection.

   Format

   SREPLACE  [ file-name ]

   Remarks

   Selections are made with the mouse.  The selection is not deleted from the
   file.  If you don't specify a file name, a dialog panel is presented which
   enables you to enter the target file name.

   If the file already exists, SREPLACE will overwrite it.  To avoid
   overwriting the file with the selection, use SCREATE.

#  26.17 {SXCLUDE}

   Purpose

   Use this command to exclude all the lines which are touched by the
   selection.

   Format

   SXCLUDE

   Remarks

   Selections are made with the mouse.

#  26.18 {TOP}

   Purpose

   Use this command to position to the top of the file.

   Format

   TOP

   Remarks

   None.

#  26.19 {UP}

   Purpose

   Use this command to scroll the view of the file up.

   Format

   UP  [ PAGE ]
       [ HALF ]
       [ CSR  ]
       [ DATA ]
       [ MAX  ]
       [ nnn  ]

   Remarks

   See page 244 for a detailed description of the parameters and examples.


#  27. {Edit Primary Commands}

   The commands listed in this chapter are edit primary commands. In general
   they operate over the entire range of the file, rather than upon a single
   line or group of lines. Edit primary commands are entered in the primary
   command field rather than in the line command area of individual lines.

#  27.1 {Edit Primary Command Summary}

   The following table summarizes the edit primary commands detailed in the
   remainder of this chapter.

      Command     Function

      &          Keep command displayed after it is executed
      :          Treat primary command as line command
      AUTOLIST   Create a source listing after END or [F3]
      AUTONUM    Renumber STD, COBOL, or BASIC upon save
      AUTOSAVE   Turn autosave on/off
      BOT        Position to bottom of file
      BOUNDS     Set/reset current bounds
      BUILTIN    Not supported
      CANCEL     Cancel or disregard edit changes
      CAPS       Turn upper case conversion on or off
      CHANGE     Change a string of data
      CHARSET    Set the character set to EBCDIC or ASCII
      COLORMAP   Bind program colorization file to file type
      COMPARE    SUPERC compare current file to external file
      COPY       Copy a file into the current file
      COUNTSAVE  Set number of ENTERs before SAVE (also SAVECOUNT)
      CREATE     Create a new file
      CUT        Cut lines marked with CC or MM to cut buffer
      DATA       Insert data at the current cursor position
      DEFINE     Enable/disable specific macros by name
      DELETE     Delete a group of lines
      DOWN       Scroll view of file down
      END        End edit session; return to prior menu
      ERRORFILE  Insert compiler errors as message lines
      EXCLUDE    Exclude lines from viewing
      FIND       Find a string of data
      FLIP       Invert sense of excluded lines
      HEX        Turn HEX display on or off
      IMACRO     Set initial macro name in the edit profile
      LCOMMAND   Turn line command field ON or OFF
      LEFT       Scroll view of file left
      LEVEL      Set/reset modification level
      LOCATE     Locate a given line
      LRECL      Set logical record length
      MODEL      Access program source templates
      MOVE       Move a file into the current file
      NOTE       Not supported
      NULLS      Not supported
      NUMBER     Turn numbering mode on or off
      PACK       Not supported
      PASTE      Insert lines from cut buffer
      PROFILE    Display current profile information
      RCHANGE    Repeat last CHANGE command
      RECOVERY   Set UNDO support ON or OFF
      REDO       Redo the last alteration which was undone
      RENUM      Renumber the current file
      REPLACE    Replace a file on disk
      RESET      Reset all pending line commands
      RFIND      Repeat last FIND command
      RIGHT      Scroll view of file right
      RMACRO     Not supported
      SAVE       Save a file on disk
      SAVECOUNT  Set number of ENTERs before SAVE (also COUNTSAVE)
      SCOPY      Copy the selection to the clipboard
      SCREATE    Create a new file from the selection
      SCUT       Copy selection to clipboard, then delete it
      SDELETE    Delete the selection
      SORT       Sorts records or columns
      SPASTE     Paste contents clipboard at cursor position
      SPRINT     Print the current selection
      SREPLACE   Replace an existing file with the selection
      STATS      Turn stats on or off
      STOLOWER   Convert selection to all lower case chars
      STOUPPER   Convert selection to all upper case chars

      SXCLUDE    Exclude all lines touched by the selection
      TABS       Turn tabs on or off
      TOP        Position to top of file
      UNDO       Undo the last alteration
      UNNUM      Reset numbers to blanks
      UP         Scroll view of file up
      XMACRO     Sets exit macro name in the edit profile
      VERSION    Not supported

#  27.1 {& (Keep Command)}

   Purpose

   Keep edit primary command in primary command field after execution.

   Format

   &edit-primary-command

   Remarks

   To keep any edit primary command in the primary command field after
   execution is complete, prepend the ampersand (&) character to the command.

#  27.2 {: (Line Command)}

   Purpose

   Treat the command entered in the primary command field as a line command.
   Apply it to the current line.

   Format

   :primary-command

   Remarks

   To apply a line command to the current line without actually typing on
   that line, type colon followed by the line command in the primary command
   field (or in PF key map).

   Example

   If you want to delete a single line using a PF key, you would assign
   that PF key the value:

   :d

#  27.3 {AUTOLIST}

   Purpose

   Turns automatic listing generation on or off.  Creates a source listing
   after changes have been made and saved.

   Format

   AUTOLIST [ON ]
            [OFF]

   Remarks

   If AUTOLIST is on when the edit session ends, a listing of the file is
   generated.

   If AUTOLIST is off when the edit session ends, a listing of the file is
   not generated.

#  27.4 {AUTONUM}

   Purpose

   Turns automatic renumbering on or off.

   Format

   AUTONUM  [ON ]
   AUTO     [OFF]

   Remarks

   If AUTONUM is on and NUMBER is on, lines are renumbered when the file is
   saved.

   If AUTONUM is off or NUMBER is off, lines are not renumbered when the file
   is saved.

#  27.5 {AUTOSAVE}

   Purpose

   Determines whether the file is automatically saved when the edit session
   ends.

   Format

   AUTOSAVE  [ON ]
             [OFF [PROMPT ]]
             [OFF [NOPROMPT]]

   Remarks

   If AUTOSAVE is on, the file is saved when the edit session ends via the
   END primary command.

   If AUTOSAVE is off, and PROMPT is in effect, and the file was modified, a
   prompt is displayed at END.  You may enter either SAVE or CANCEL at this
   time. SAVE saves the file, then exits. CANCEL exits without saving the
   file.

   If AUTOSAVE is off and NOPROMPT is in effect, the file is not saved at
   END. In this case END behaves exactly the same as CANCEL.

#  27.6 {BOT}

   Purpose

   Use this command to position to the bottom of the file.

   Format

   BOTTOM
   BOT

   Remarks

   None.

#  27.7 {BOUNDS}

   Purpose

   Sets the left and right column boundaries and saves them in the Edit
   Profile.

   Format

   BOUNDS [left-column  right-column]
   BNDS
   BND

   Remarks

   Left-column identifies the left column boundary and right-column
   identifies the right column boundary. The same column cannot be specified
   for both boundaries. Either column may be specified as an asterisk (*);
   the existing column boundary is used.

   If the BOUNDS command is entered without operands, the boundaries are set
   to their default columns. If numbering is set to COBOL, the default left
   bound is column 7. In all other cases, the default left bound is column 1.
   If numbering is set to STD, the default right bound is 72. In all other
   cases, the default right bound is equal to the maximum record length.

   Column boundaries are used to limit the scope of:

   1. Left and right line shift commands.

   2. Left and right line scroll commands.

   3. FIND, CHANGE, and EXCLUDE commands.

   4. SORT command.

   5. TE, TS, and TF line commands.

   6. O, OO line command.

   BOUNDS allows scrolling to the bounds extents. A left scroll stops at the
   left bound, a right scroll stops at the right bound.  An additional scroll
   request causes scrolling beyond the bounds.

   Bounds may also be changed by displaying the boundary definition line with
   the BNDS line command.

   The bounds are automatically adjusted to exclude the sequence-number
   fields whenever NUMBER is turned on.

   Example

   To reset bounds to defaults:

   BOUNDS

   To set the left boundary to 1 and the right boundary to 72:

   BOUNDS 1 72

#  27.8 {CANCEL}

   Purpose

   Cancels editing of current file.

   Format

   CANCEL
   CAN

   Remarks

   Any changes made during an edit session are cancelled.

   Note:  If the SAVE command was used before CANCEL, edit changes made up to
   the SAVE are not cancelled.

#  27.9 {CAPS}

   Purpose

   Controls the CAPS mode.

   Format

   CAPS [ON ]
        [OFF]

   Remarks

   If on is specified, data entered is set to upper case.

   If off is specified, data entered is left "as is".

#  27.10 {CHANGE}

   Purpose

   Searches the file for a character string then replaces it with another
   character string.  Strings which are changed are highlighted.

   Format

   CHANGE str1 str2 [range][NEXT ][CHARS ][X ][col1[col2]]
   CHG                     [ALL  ][PREFIX][NX]
   C                       [FIRST][SUFFIX]
                           [LAST ][WORD  ]
                           [PREV ]

   Remarks

   Generally CHANGE is entered with only the two required parameters: str1
   and str2. In this case, SPF/Pro searches for the next instance of str1
   starting at the current cursor location. When str1 is found it is replaced
   with str2.  SPF/Pro searches for str1 within the current BOUNDS (see page
   294 for more on this).

   You can press [F6] to repeat the change on the next occurrence of str1.

   The most common parameter used is ALL which replaces all occurrences of
   str1 rather than just the next one.

   The remaining optional parameters are not used as frequently. Together
   they provide a very flexible and powerful extension to the basic search
   and replace capability.

   CHANGE has common parameters with FIND and EXCLUDE; these parameters are
   fully documented once at the beginning of this chapter. So, if you want
   to:

   *  specify character strings containing blanks or quotes

   *  do case sensitive/insensitive searches

   *  find and replace hexadecimal strings

   *  find or replace a string that you just specified in a previous FIND,
      CHANGE, EXCLUDE command

   *  match strings dependent on its location within a word

   *  change the direction of searching

   *  restrict searching to a range of lines

   *  affect searching by whether lines are currently "excluded" or not

   *  cause searching in columns other than that currently specified in the
      BOUNDS command

   CHANGE parameters are free form and may be entered in any order. The only
   exceptions are:

   1. If entered, col2 must follow col1.

   2. Str2 must follow str1.

   Str1 and str2 are required; all other parameters are optional.

   If CHANGE strings are not the same length, SPF/Pro automatically shifts
   characters on the right of the string.  In doing this, it tries to meet
   the following objectives:

   *  It will not shift any characters to the right of the current right
      bound.

   *  It will not shift any non-blank characters between the right of the
      string and the right bound.

   If str1 is longer than str2, SPF/Pro shifts characters on the right of
   str2 to the left until it finds a blank or reaches the right bound.
   There, it inserts the number of blanks equal to the shift amount.

   If str1 is shorter than str2, SPF/Pro shifts characters on the right of
   str2 to the right to make room for str2.  While doing so, it attempts to
   avoid shifting non-blank characters.  It does this by replacing adjacent
   blank characters with a single blank.  If there are insufficient blanks
   between the end of the string and the right bound, an error flag is placed
   in the line command area:

   ==ERR>

   When a CHANGE is successfully made, a change flag is placed in the line
   command area:

   ==CHG>

   To remove change and error flags use the RESET primary command.

   Example

   To change string "this" to string "that":

   change this that

   To change string "something" to a null string (""):

   CHANGE something ''

   To change string "ABC" to string "XYZ" in columns 1 through 20 inclusive:

   CHANGE ABC XYZ 1 20

   To change the first occurrence of string "ABC" to "DEF" commencing the
   search at the start of the file:

   CHANGE abc def first

   To change all occurrences of string "ABC" to "XYZ":

   CHANGE ABC XYZ ALL

   To change string "ABC" to "XYZ" only in excluded lines:

   CHANGE ABC XYZ X

   To change string "ABC" to "XYZ" only in non-excluded lines:

   CHANGE ABC XYZ NX

   To change all blanks to hyphens in columns 1 to 5, between lines labeled
   .B and .E, but only in excluded lines:

   CHG ALL ' ' '-' 1 5 .B .E X

#  27.11 {CHARSET}

   Purpose

   Sets the character set to either EBCDIC or ASCII.

   Format

   CHARSET  [ EBCDIC | ASCII ]

   Remarks

   The character set determines how character code points are interpreted.
   If you download a file from the mainframe without conversion, its
   characters are EBCDIC. It can be edited without conversion by setting the
   character set to EBCDIC. DOS files are natively in ASCII. This value can
   also be set in the file profile via panel 0.7.

#  27.12 {COLORMAP}

   Purpose

   Binds a program colorization control file to a particular file type.

   Format

   COLORMAP  name | NONE

   Remarks

   To activate program colorization for the current file type, specify the
   name of the program colorization file (no extension).  To de-activate
   program colorization for the current file type, specify NONE.

   You can enable or disable program source colorization globally via Option
   Panel 0.5.

#  27.13 {COMPARE}

   Purpose

   Use this command to compare the file being edited to an external file.
   After compare is complete, the differences are integrated into the current
   file as "==INS>" and "==DEL>" lines.

   Format

   COMPARE  [ file-name ]

   Remarks

   If "file-name" is not specified, an entry panel is presented which allows
   you to specify an individual file or generate a select list from which you
   can select an individual file.

   See SUPERC Utility (3.I) for details on other fields in the SUPERC entry
   panel.

#  27.14 {COPY}

   Purpose

   Copies a file from disk into the file being edited.

   Format

   COPY [filename] [BEFORE label] [range]
                   [AFTER  label]

   Remarks

   If filename is specified, the file is copied from the same drive and
   subdirectory as the current file.

   If filename is not specified, a file-specification menu is presented.  On
   this menu, you can specify any drive and subdirectory.

   If the file-specification menu is presented, the file to be copied is
   specified in either SPF/Pro FILE DEFINITION or FILE NAME.

   A Select List menu is presented if you specify wild-card characters ("*"
   or "?"). In the select list you can select a file to copy by placing an S
   to the left of the file name or press [F3] to cancel the request.

   There are two ways to specify where the copied text is to be inserted.
   First, a edit line command can be used to mark the appropriate line with A
   (after) or B (before). Second, an option can be given as part of the COPY
   command to place the records AFTER or BEFORE a line that has been
   previously labeled.

   If a range of line numbers is not specified, the entire file is copied.

   Note:  CUT and PASTE primary commands can also be used to move or copy
   lines between files. See page     and page     for details.

   Example

   To copy DEMO.DOC from the same drive/subdirectory as the current file to a
   point in the file indicated by the A or B line command:

   COPY DEMO.DOC

   To display a select list of all DEMO document candidates that could be
   copied:

   COPY DEMO*.DOC

   To copy a file specified on a subsequent menu to a point after the line
   labeled ".A":

   COPY AFTER .A

#  27.15 {COUNTSAVE}

   Purpose

   Use this command to cause files being edited to be automatically saved
   based on the number of times that [SPF-Enter] has been pressed.

   Format

   COUNTSAVE  nnn

   Remarks

   If 0 is specified, files being edited are not automatically saved.

   If 1 or greater is specified, files being edited are automatically saved
   every "nnn" presses of [SPF-Enter].

   Same as SAVECOUNT.

#  27.16 {CREATE}

   Purpose

   Creates a new file using all or part of the file being edited.

   Format

   CREATE [filename] [range]
   CRE

   Remarks

   If filename is specified, the file is created in the same drive and
   subdirectory as the current file.

   If filename is not specified, a file-specification menu is presented. On
   this menu, you can specify any drive and subdirectory.

   If the menu is presented, the file to be created is specified in either
   SPF/Pro FILE DEFINITION or FILE NAME.

      Note: Using wild-card characters ("*" and "?") in the file
      specification is not valid.

   There are two ways to specify which lines are to go to the new file:

   *  Mark text to be copied/moved with the COPY (C, Cn, CC) or MOVE (M, Mn,
      MM) line commands.  Using COPY line commands does not affect the
      current file.  Using MOVE line commands deletes the marked lines from
      the current file after the new file is created.

      Note:  See COPY and MOVE line commands on page    , page    , page    ,
      and page    , for additional information.

   *  Specify a range of lines as part of the CREATE command. The range is
      specified with beginning and ending labels.  The source line range
      parameter is not supported as it is on COPY.

   If the file already exists, CREATE will not overlay it.  See page     for
   details on how to create a new file which replaces an existing file.

   Example

   To create DEMO.DOC in the same drive/subdirectory as the current file
   using records identified by CC line commands:

   CREATE DEMO.DOC

   To create a file specified on a subsequent menu using lines beginning at
   line labeled ".B" and ending at line labeled ".E":

   CREATE .B .E

#  27.17 {CUT}

   Purpose

   Use this command to copy or move a block of lines to the clipboard.

   Format

   CUT  [ APPEND ]

   Remarks

   First mark the block of lines to be cut with either CC or MM line
   commands. After the lines have been cut, they can be pasted another edit
   file.

   If APPEND is specified, the cut lines are appended to the current contents
   of the clipboard, otherwise the cut lines replace the current contents of
   the clipboard.

   Note:  If you have selected text with the mouse, use SCUT, SCOPY, and
   SPASTE.

   Example

   To cut the block of lines marked with CC or MM:

   CUT

#  27.18 {DATA}

   Purpose

   Use this command to insert data at the current cursor position.

   Format

   DATA string

   Remarks

   Normally the DATA command and its associated text is assigned to a
   function key. The data is inserted (or overtyped) at the current cursor
   position just as if you had typed it in through the keyboard. This is
   particularly convenient when you want to repeatedly insert some text
   throughout a document or program source.

   Example

   Use KEYS to assign the paragraph markup tag to [F1].  Then press [F1]
   whenever you want to insert the paragraph markup in a document.

   PF1 ===> DATA 

An easier method is to simply define the value of a PF key as a quoted string: PF1 ===> "

" # 27.19 {DEFINE} Purpose Use this command to enable, disable, or alias specific macros or primary commands. Format DEFINE name [MACRO CMD ] | [CMD MACRO ] DEF [ALIAS name2 ] [NOP ] [RESET ] [DISABLED ] Remarks The command is primarily used to manage the selective invocation of macros and primary commands. name Specifies the name that is used to invoke the macro or primary command. MACRO CMD Specifies that the name parameter identifies a macro. This is the default and thus need not be specified. Note: SPF/Pro does not support the direct invocation of programs and thus the ISPF MACRO PGM parameter is not supported. ALIAS When name and ALIAS name2 are both specified, name is an alias of name2. NOP Specifies that name is a NOP (no operation). Any aliases are also set to NOP. RESET Specifies that name be reset, that is, restored to its default state. For example if name were previously NOPed, it would be returned to operational status. DISABLED Specifies that name be disabled. Disablement is identical to NOP except that the state can not be reversed with the RESET option. You must exit to the Primary Option Menu to restore the disabled macro to operational status. Command tables are also accessible via Option Panel 3.J. Example To define that QQ is an alias for the CANCEL primary command: DEFINE QQ ALIAS CANCEL To restore the CANCEL primary command to its original status: DEFINE CANCEL RESET To define that the MOVE primary command is to have no operation (NOP): DEFINE MOVE NOP To define that the MOVE primary command is to have no operation (NOP): DEFINE MOVE NOP To define that the COPY primary command is to be disabled (like NOP): DEFINE COPY DISABLED # 27.20 {DELETE} Purpose Removes one or more lines from the file being edited. Format DELETE ALL [ X | NX ] [ range ] DEL Remarks You can delete one of the following: * All excluded lines (DELETE ALL X). * All non-excluded lines (DELETE ALL NX). * Lines within a range (DELETE ALL .B .E) * Excluded lines within a range (DELETE ALL X .B .E) * Non-excluded lines within a range (DELETE ALL NX .B .E) Note: If you have selected text with the mouse, use SDELETE. Example To delete all lines that contain a non-ASCII character: RESET X (make all lines visible) EXCLUDE ALL P'.' (exclude lines with non-ASCII) DELETE ALL X (delete all excluded lines) To delete all lines between lines labeled ".B" and ".E": DELETE ALL .B .E # 27.21 {DOWN} Purpose Same as [F8] key. Use this command to move toward the bottom of the file. Format DOWN [PAGE] [HALF] [CSR ] [DATA] [MAX ] [nnnn] Remarks There are three ways to specify how much SPF/Pro moves when you issue the command: 1. Issue the command without a scroll amount. In this case the SCROLL field determines the amount scrolled. The SCROLL field is in the upper right corner of the screen. 2. Issue the command with a scroll amount. Type the command and the amount, or type the amount and press the appropriate PF key. 3. Change the SCROLL field and execute step 1. Note: Scroll amounts can be abbreviated. For example, P for PAGE, M for MAX, etc. Example [F8] Move down by amount specified in SCROLL field. DOWN 8 Move down eight lines. Type 8 in command field, then press [F8] Also, move down eight lines. # 27.22 {END} Purpose Terminates the edit session and returns you to the prior menu. Format END Remarks Normally you would use END to exit and save any changes you have made to the edited file. Saving is conditioned by the AUTOSAVE profile variable which is manipulated by the AUTOSAVE primary command. If you do not want to save changes made in this edit session, use the CANCEL primary command in place of END. The default key mapping places the END command on [F3]. If you are in Edit and SAVE has been disabled due to a system error, END will not exit the Editor. Use CANCEL instead. Example To end the current edit session and save changes: END # 27.23 {ERRORFILE} Purpose This command merges the content of a compiler error message file with the file being edited. Format ERRORFILE [filename] ERROR EF Remarks Error messages are merged as NOTEs into the file being edited at the line position where the error occurred. You can also use the /R command line option to merge compiler error messages with the associated source file. The following message formats are supported: Micro Focus COBOL Realia COBOL Borland C++ Zortech C++ Microsoft (all languages) Example The following examples merge error message file ERROR.OUT with the active edit file: ERRORFILE ERROR.OUT ERRORFILE C:\COBOL\DEMOS\ERROR.OUT # 27.24 {EXCLUDE} Purpose Allows you to exclude selected lines from view. Format EXCLUDE str1 [range][NEXT ][CHARS ][col1[col2]] EXC [ALL ][PREFIX] EX [FIRST][SUFFIX] X [LAST ][WORD ] [PREV ] Remarks Excludes one or more lines containing str1. String edge characteristics may also be specified. The number of lines excluded is controlled by the search direction and scope. The search for str1 can be limited to a range of lines. Parameters may be entered in any order. One exception is that col1 must precede col2. The lines containing a match on str1 are excluded from view just as if an X line command was entered on those lines. Of all of the possible combinations of parameters, the following two are most frequently: * "EXCLUDE str1 ALL" excludes all lines that match str1. It is often followed with a CHANGE ... NX command to change non-excluded lines only. Or the inverse, a CHANGE ... X command to change excluded lines only. * EXCLUDE ALL excludes all lines from view. This is usually followed by a FIND command which makes only a subset of lines visible. After the subset lines are visually verified, a CHANGE ... NX is used to change them. Although the rest of the optional parameters are not used as frequently, together they provide a very powerful search capability. EXCLUDE has common parameters with CHANGE and FIND; these parameters are fully documented once at the beginning of this chapter. So, if you want to: * specify character strings containing blanks or quotes * do case sensitive/insensitive searches * search for hexadecimal strings * exclude a line containing string that you just specified in a previous FIND, CHANGE, EXCLUDE command * match strings dependent on its location within a word * change the direction of searching * restrict searching to a range of lines * affect searching by whether lines are currently "excluded" or not * cause searching in columns other than that currently specified in the BOUNDS command Once lines are excluded, they can be returned to view (not excluded) in one of 4 ways: 1. The RESET command makes all excluded lines visible. 2. The FIND command makes excluded lines containing the find string visible. 3. The S (Show) line command makes lines visible based on their indentation level. (See page .) 4. The FIRST and LAST line commands make one or more excluded lines (at beginning or end of a block of excluded lines) visible. Note: If you have selected text with the mouse, use SXCLUDE. Example This example excludes all ELSE strings in columns 1 to 4 between lines labeled .E and .S: EXC ALL ELSE 1 4 .E .S # 27.25 {FIND} Purpose Searches a file for a string, word or characters. Strings which are found are highlighted. Format FIND str1 [range][NEXT ][CHARS ][X ][col1[col2]] F [ALL ][PREFIX][NX] [FIRST][SUFFIX] [LAST ][WORD ] [PREV ] Remarks FIND command parameters are free form and may be entered in any order. The only exception is that col2 (if entered) must follow col1. The str1 parm is required; all others are optional. Usually, the FIND command is issued with only the str1 parameter. In that case, SPF/Pro searches for the next instance of str1 starting at the current cursor location. SPF/Pro only searches for str1 within the current BOUNDS specification. (See page 294) If the line is not currently displayed on the screen, SPF/Pro scrolls the file so that it is displayed. If the line is currently excluded, it is made visible. Although the rest of the optional parameters are not used as frequently, together they provide a very powerful search capability. FIND has common parameters with CHANGE and EXCLUDE; these parameters are fully documented once at the beginning of this chapter. So, if you want to: * specify character strings containing blanks or quotes * do case sensitive/insensitive searches * search for hexadecimal strings * find a line containing string that you just specified in a previous FIND, CHANGE, EXCLUDE command * match a string dependent on its location within a word * change the direction of searching * restrict searching to a range of lines * affect searching by whether lines are currently "excluded" or not * cause searching in columns other than that currently specified in the BOUNDS command * search for a string in one or more files in a select list Example Find the next occurrence of string "ABC" starting at the current cursor position: FIND ABC Find the next occurrence of string "ABC" between columns 1 and 20: FIND ABC 1 20 Find next occurrence of string "one of a kind": FIND 'one of a kind' Find the last occurrence of string "ABC": FIND ABC LAST Find all occurrences of string "ABC": FIND ABC ALL Find the next occurrence of string "ABC" in excluded lines: FIND ABC X Find the next occurrence of string "ABC" in non-excluded lines: FIND ABC NX Find the first occurrence of string "ABC" from the start of the file: FIND ABC FIRST Find the next occurrence of word "pages" between the lines labeled .start and .end: FIND pages word .start .end Note: This search starts at the current cursor position and scans forward. This search is also delimited by the range, .start to .end. You must be conscious of both of these facts, as well as the current cursor location, in order to predict precisely how this command works. Confusion results when the cursor resides between the two labels. In that case, searching does not start at the first label. Instead, it starts at the current cursor location. This example finds the first hyphen (-) in columns 1 to 5 between lines labeled .E and .S, but only in those lines that are excluded. FIND FIRST '-' 1 5 .E .S X # 27.26 {FLIP} Purpose Invert the sense of excluded lines. Format FLIP Remarks Makes excluded lines non-excluded, and non-excluded lines excluded. This is useful when you want to exclude all lines which contain a particular string. Example To exclude all lines containing string EMPLOYEE-NUMBER: EXCLUDE ALL FIND EMPLOYEE-NUMBER ALL FLIP # 27.27 {HEX} Purpose Enables or disables hexadecimal display mode. Format HEX [ON ] [OFF] Remarks In HEX mode, three lines of data are displayed for each line in the file. The first shows data in standard ASCII form. The next two lines show the same data in vertical hexadecimal representation. Either the data lines or the hex lines may be altered. Simply overtype the change you wish on either ASCII character line or the hexadecimal lines. If a conflict exists, the hex lines are used. WARNING: using Hex 1A (decimal 26) as a data character in a file can cause inadvertent file truncation as this is the DOS EOF Character. If you enter this character and save the file, the file is saved "as is"; however, if you then edit the file AND your file profile honors the DOS EOF character, the file is truncated at the point where the first Hex 1A is encountered. To use the Hex 1A character, in 0.7 (File Profile) set the FILE TERMINATOR option to NO. # 27.28 {IMACRO} Purpose Saves the name of an initial macro in the current edit profile. Format IMACRO [name] [NONE] Remarks You can specify either: name The name of the initial macro to be executed when editing a file that matches this file's type. The IMACRO is executed before any data is displayed. Specify NONE to reset the IMACRO value. Example To set STARTUP as the initial macro: IMACRO STARTUP To reset the edit profile to no initial macro: IMACRO NONE # 27.29 {LCOMMAND} Purpose Specifies whether the line command field is present or not. Format LCOMMAND [ ON | OFF ] LCMD Remarks If on is specified, the line command field is present. If off is specified, the line command field is not present. In this case it is necessary to map specific line command actions to PF keys (or other control keys) to be able to execute those line commands. See the KEYS primary command or Keyboard Option 0.K for a description of how to map PF keys and other key sequences to specific line commands. # 27.30 {LEFT} Purpose Same as [F10] key. Use this command to move toward the left edge of the displayed text. Format LEFT [PAGE] [HALF] [CSR ] [DATA] [MAX ] [nnnn] Remarks There are three ways to specify how much SPF/Pro moves when you issue the command: 1. Issue the command without a scroll amount. In this case the SCROLL field determines the amount scrolled. The SCROLL field is in the upper right corner of the screen. 2. Issue the command with a scroll amount. Type the command and the amount, or type the amount and press the appropriate PF key. 3. Change the SCROLL field and execute step 1. Note: Scroll amounts can be abbreviated. For example, P for PAGE, M for MAX, etc. Example [F10] Move left by amount specified in SCROLL field. LEFT 8 Move left eight columns. Type 8 in command field, then press [F10] Also, move left eight columns. # 27.31 {LEVEL} Purpose Assigns a modification level to the current file. Format LEVEL number LEV Remarks If STATS mode is on, and STD number mode is on, the modification level is stored in positions 79 and 80 for any lines that are modified during the edit session. In addition, the modification level is replaced for any record that already has a modification level number that is greater than the number specified. Normally, the level number is one greater than the largest number found in these columns before editing starts. This command allows you to choose a different number. If LEVEL number 0 is specified, all lines are reset to LEVEL 0 when the file is saved. # 27.32 {LOCATE} Purpose Used to position the file to a specific line number or a specific type of generic line. Format LOCATE line-number | label LOC L LOCATE [NEXT ] [LABEL ] [range] LOC [PREV ] [COMMAND ] L [FIRST] [ERROR ] [LAST ] [CHANGE ] [SPECIAL ] [EXCLUDED] Remarks The first format scrolls the file so that the line with the specified line number or label is at the top of the display. If the command contains any parameters other than line number or label, SPF/Pro assumes that it is the second format. The operands NEXT, PREV, FIRST and LAST are used to control the direction of search: NEXT start at the cursor line and search forward (this is the default) PREV start at the cursor line and search backward FIRST start at the front of the file and search forward LAST start at the end of the file and search backward The next optional parameter specifies a particular line type to be located: LABEL (or LAB) search for a line with a label COMMAND (or COM) search for a line with a pending line command ERROR (or ERR) search for a line with an error flag ( ==ERR>) CHANGE (or CHG) search for a line with a change flag (==CHG>) SPECIAL (or SPE) search for a line marked with =PROF>, =MASK>, =TABS>, =BNDS>, ==MSG>, or =NOTE=) EXCLUDED (or X) search for an excluded line In addition, the second form of this command can include a range specification to restrict the locate to a range of lines. Example Put line 472 at top of screen: LOC 472 Scroll to the next line that has a label: LOC LABEL Locate the first line of the file: L .ZFIRST Locate the next special line: LOCATE SPE Locate the first error line (==ERR>): L ERR FIRST Locate the next line with a label: LOC NEXT LABEL Locate the next excluded line between labels .START and .END: L X .START .END Locate the first excluded line between labels .E and .S: L FIRST .E .S X # 27.33 {LRECL} Purpose Used to set the logical record length profile variable. Format LRECL nnn [ TRUNC ] Remarks Sets the maximum logical record length for records in a particular file type. You can also set this value with the profile options panel 0.7. If you have a corrupted file, and want to truncate records which exceed the desired LRECL, specify TRUNC along with the LRECL value. The TRUNC parameter only applies to the current file in EDIT. # 27.34 {MODEL} Purpose Use this command to incorporate program source templates for a particular programming language into the file you are editing. Format MODEL [source-template-name] Remarks The typical use for the MODEL command is to directly incorporate a template for a particular construct of a programming language into your program source. This can be accomplished in a variety of ways: * If you know the name of the template you simply enter the MODEL primary command with the template name as the only parameter. You must also place an "A" or "B" line command at the insert point. For example, MODEL IF * If you are not sure of the template name, enter the MODEL primary command with no parameters to bring up a list of available templates. Select the desired template from the list and it will be inserted. * The MODEL primary command determines which templates to present based on the file extension. For example, if you are editing PROG1.COB, the MODEL command will present the templates for the COBOL language; if you are editing PROG1.C, the MODEL command will present the templates for the "C" language. * If you are editing a file type which is not known to MODEL, for example, PROG1.XYZ, it will present a list of all known types from which you can select the desired language. From that point onward, the selected template group will be associated with type ".XYZ". In all cases, once a source template is selected, it is inserted after the "A" or before the "B" insert point. Included with many templates are NOTE line annotations which explain the usage for the selected template. NOTE lines are dismissed with the RESET primary command. # 27.35 {MOVE} Purpose Moves a file from disk into the current file. Format MOVE [filename] [BEFORE label] [AFTER label] Remarks Works the same as the COPY primary command (see page 303) but it removes the file after it has been copied into the current file. The source line range parameter is not supported as it is on COPY. # 27.36 {NUMBER} Purpose Sets NUMBER mode on or off and specifies the numbering method. Format NUMBER [ON ] [STD] [COBOL] [DISPLAY] NUM [OFF] Remarks COBOL and DISPLAY may be abbreviated COB and DIS, respectively. If no number type is specified, STD is assumed. When number mode is turned on, the NUMBER command verifies that all lines have valid numbers in ascending sequence. If any lines are either unnumbered or out of sequence, it renumbers all lines. Otherwise, it does not alter existing sequence numbers. If STD is specified (or defaulted), sequence numbers are generated in columns 73 to 80. This option is invalid for files with records longer than 80 characters. If COBOL is specified, sequence numbers are generated in columns 1 to 6. If DISPLAY is specified, COBOL sequence numbers are shown on the screen. This has the same effect as pressing [F9] immediately after entering edit mode. If STATS is on, and number is STD, sequence numbers are placed in columns 73 to 78, and a level number is placed in columns 79 and 80. The level number is incremented by one each time the file is edited. When a line is inserted or changed, the level number is placed in columns 79 and 80. See page 323 for other ways to set the level number. Note: For file types .COB, .CBL, and .CPY, when loading the file, each record is examined to determine whether it contains sequence numbers in either the COBOL or STANDARD number columns. If all lines have valid numbers in ascending sequence, edit assumes the data is numbered and turns number mode on. Otherwise, edit turns number mode off. If the initial setting of the number mode differs from the previous setting in the profile, a message is displayed indicating that edit has changed the mode. Example Turn on STD numbering: NUMBER Turn on COBOL numbering and cause sequence numbers to be visible: NUMBER COBOL DISPLAY Turn on STD numbering: NUMBER STD Turn on STD and COBOL numbering: NUMBER STD COBOL # 27.37 {PASTE} Purpose To retrieve the current contents of the cut buffer. Format PASTE Remarks For PASTE to function, you must mark the destination for the paste block with the "A" or "B" line command. The cut buffer contents are not altered by PASTE so you may do multiple PASTEs of the same cut buffer data. Note: If you have selected text with the mouse, use SCUT, SCOPY, SPASTE. Example To retrieve the block of lines in the cut buffer: PASTE # 27.38 {PROFILE} Purpose Displays the current edit profile. It can also be used to choose an edit profile for a different extension or lock the current profile. Format PROFILE name [number] PROF number PRO LOCK PR UNLOCK Remarks name Specifies the profile name that you would like to change to. If the specified name does not exist, a new profile is created using the parameters that are in effect when the ISREDIT PROFILE command is processed. number The number of profile lines to display. You can specify any number from 1 to 8. The default is 4, the maximum is 8. If you don't want to see the profile lines, enter RESET or PROFILE 0. LOCK Save and lock the profile. All current modes and options are saved and marked so that they can not be overwritten. Each time that an edit session is begun, the locked profile is re-called exactly as it was when it was locked. Changes made during a new edit session affect only the current edit session, and not subsequent sessions. UNLOCK Unlock the current edit profile so that it can be changed. The following information is displayed: NAME Current file extension RECORD FORMAT Length-delimited/Data-delimited RECORD LENGTH 1 - 64000 RECOVERY On/Off NUMBER On/Off/STD/COB/DISP CAPS On/Off HEX On/Off TABS On/Off/Std/All/Character CHARSET ASCII or EBCDIC AUTOSAVE On/Off/Prompt/Noprompt AUTONUM On/Off AUTOLIST On/Off STATS On/Off PROF Lock/Unlk IMAC IMACRO Name XMAC XMACRO Name PACK Not supported (always OFF) COLORMAP name or OFF # 27.39 {RCHANGE} Purpose Same as [F6] key. Use this command to repeat the last CHANGE command. Format RCHANGE Remarks This command only functions in File Select Lists, EDIT, and BROWSE. See page 297 for details. # 27.40 {RECOVERY} Purpose Specifies whether UNDO support is on or off. Format RECOVERY [ ON | OFF ] Remarks If on is specified, UNDO/REDO support is activated. If off is specified, UNDO/REDO support is de-activated. This command is identical to UNDO ON/OFF. # 27.41 {REDO} Purpose Specifies that one or more EDIT operations which were undone should be re-done. This is the opposite of UNDO. Format REDO [ nnn | ALL ] Remarks In the normal use of EDIT, you make numerous changes to a file. When undo processing is on, each change is recorded in a journal which may subsequently be used to undo a change. Having undone a change, you may want to redo it. This is when the REDO command comes into play. For each undo with no intervening changes, you can apply REDO. If no parameters are specified, only the last posted undo is redone. If a number is specified, redo is applied to the specified number of posted undos. In the event that the number of posted undos is smaller than the specified number, only the posted undos are redone. If ALL is specified, all posted undos are redone. # 27.42 {RENUM} Purpose Turns on NUMBER mode and re-sequences all lines starting with 100 incrementing by 100. If the number of lines in the file is so great as to use all available numbers when numbering by 100, the number increment is automatically reduced to 10. Format RENUM [ COBOL ] [ STD ] [ DISPLAY ] REN Remarks RENUM forces a re-sequence. It does not preserve existing sequence numbers. Parameters COBOL, STD, and DISPLAY are identical to the NUMBER command. If numbers are not visible, press [F9] or [F10] scroll keys. For more information, see NUMBER command on page 329. # 27.43 {REPLACE} Purpose Replaces an existing file using all or part of the file currently being edited. Format REPLACE [filename] [range] REPL REP Remarks The REPLACE primary command works identically to the CREATE primary command with the exception that if the file already exists, it is replaced. # 27.44 {RESET} Purpose Resets special lines, flagged lines, pending line commands, current selection, and FIND/CHANGE highlighting. The effect is that line command fields are cleared and line numbers are displayed. Format RESET [LABEL] [COMMAND] [ERROR] [CHANGE] RES ..... [SPECIAL] [EXCLUDED] [range] Remarks The following parameters allow limiting the effect of this command: LABEL (or LAB) clear labels COMMAND (or COM) clear pending line commands ERROR (or ERR) clear error flags (==ERR>) CHANGE (or CHG) clear change flags (==CHG>) SPECIAL (or SPE) delete "special" lines flagged with =PROF>, =MASK>, =TABS>, =BNDS>, ==MSG>, or =NOTE=) EXCLUDED (or X) make excluded lines visible If none of the above parameters is specified, all except labeled lines are reset. In addition, the RESET command can include a range specification to restrict the action to a range of lines. Example To clear ==CHG> flags and redisplay excluded lines between the start of the file and the current cursor location: RESET CHG X .ZFIRST .ZCSR # 27.45 {RFIND} Purpose Same as [F5] key. Use this command to repeat the last FIND command. Format RFIND Remarks Remarks This command only functions in File Select Lists, EDIT, and BROWSE. See page 316 for details. # 27.46 {RIGHT} Purpose Same as [F11] key. Use this command to move toward the right edge of the displayed text. Format RIGHT [PAGE] [HALF] [CSR ] [DATA] [MAX ] [nnnn] Remarks There are three ways to specify how much SPF/Pro moves when you issue the command: 1. Issue the command without a scroll amount. In this case the SCROLL field determines the amount scrolled. The SCROLL field is in the upper right corner of the screen. 2. Issue the command with a scroll amount. Type the command and the amount, or type the amount and press the appropriate PF key. 3. Change the SCROLL field and execute step 1. Note: Scroll amounts can be abbreviated. For example, P for PAGE, M for MAX, etc. Example [F11] Move right by amount specified in SCROLL field. RIGHT 8 Move right eight columns. Type 8 in command field, then press [F11] Also, move right eight columns. # 27.47 {SAVE} Purpose Saves the current file without terminating the edit session. Format SAVE SAV S Remarks To save the file under a different drive, directory, or name, see the CREATE command. The SAVE command replaces the disk based file with the memory based file. Lines are automatically renumbered if AUTONUM and NUMBER are on. If SAVE cannot rewrite the data because of an I/O error, or insufficient space, a message is displayed and an alarm is sounded. You can then attempt to save the data in another file by taking the following steps: 1. Enter primary command: CREATE .ZFIRST .ZLAST or REPLACE .ZFIRST .ZLAST 2. The Move/Copy Utility menu should be presented to you. Fill in a new data set name and press [SPF-Enter]. If the original disk is out of space, specify a different drive. Note: "Special" lines ( =PROF>, =MASK>, =TABS>, =BNDS>, ==MSG>, or =NOTE=) are not saved and do not have to be reset. # 27.48 {SAVECOUNT} Purpose Use this command to cause files being edited to be automatically saved based on the number of times that [SPF-Enter] has been pressed. Format SAVECOUNT nnn SAVEC Remarks If 0 is specified, files being edited are not automatically saved. If 1 or greater is specified, files being edited are automatically saved every "nnn" presses of [SPF-Enter]. Same as COUNTSAVE. # 27.49 {SCOPY} Purpose Use this command to copy the current selection to the clipboard. Format SCOPY Remarks Selections are made with the mouse. The selection is not deleted from the file. You can subsequently use SPASTE to paste the clipboard contents into the file. # 27.50 {SCREATE} Purpose Use this command to create an original external file with the contents of the selection. Format SCREATE [ file-name ] Remarks Selections are made with the mouse. The selection is not deleted from the file. If you don't specify a file name, a dialog panel is presented which enables you to enter the target file name. If the file already exists, SCREATE will not overwrite it. To overwrite the file with the selection use SREPLACE. # 27.51 {SCUT} Purpose Use this command to copy the current selection to the clipboard and then delete it from the file. Format SCUT Remarks Selections are made with the mouse. # 27.52 {SDELETE} Purpose Use this command to delete the current selection. Format SDELETE Remarks Selections are made with the mouse. The [DEL] key also deletes the current selection. # 27.53 {SORT} Purpose Performs two kinds of sorting: * sorts full records * sorts individual columns of data without affecting the remainder of the record Format SORT [range] [X ] [sort-field_1 ... sort-field_n] [NX] Remarks If you specify a range, only the lines within that range are sorted. To do this, label the first and last lines. Then use these labels in a range specification. Sort can also be limited to excluded (X) or non-excluded (NX) lines. Each of the sort fields has the following format: [A] [start-column[end-column]] [D] If "A" is specified (or defaulted), data is ordered in ascending sequence. If "D" is specified, data is ordered in descending sequence. In addition to "A" or "D", the columns to be sorted can be specified. If they are not specified, the default is the current BOUNDS. Start-column specifies the left-most position and end-column specifies the right-most position of the sort field. Start-column must precede end-column. In addition, neither specification can be outside the current BOUNDS. The above parameters indicate which columns SPF/Pro should compare when ordering data. These parameters are common to computer based sorting programs. There is an aspect of SORT which is unique to SPF/Pro. When the BOUNDS are set to less than the full record, only the data within the bounds is sorted. The effect is that the sorted data is re-ordered while the data to the left or right of the bounds is not. Thus the record content is changed from its original form. In the normal case, where the BOUNDS are at their default settings, SPF/Pro sorts the entire record. In this case, it works much like the SORT command in operating system. Warning: SORT is a very powerful command; its use requires care. It is easy to destroy a file by issuing SORT with the BOUNDS set incorrectly. Example Sort full records, columns 5 - 15 inclusive, in ascending order: BOUNDS SORT 5 15 Sort full records, columns 1 to right bound, from lines .A to .B inclusive in descending order: BOUNDS SORT D .A .B Sort full records, major field column 5 to right bound, in descending order, minor field columns 1 and 2 in ascending order: BOUNDS SORT D 5 A 1 2 Sort full records, non-excluded lines only, in ascending order: BOUNDS SORT A NX Sort partial record, columns 30 to 45, in ascending order: BOUNDS 30 45 SORT columns 1 - 29, and 46 to end of record are not re-ordered. Sort full records in ascending order: SORT Sort full records in descending order: SORT D Sort full records, column 5 to right bound, in ascending order: SORT 5 Sort full records, column 5 to right bound, in descending order: SORT 5 D # 27.54 {SPASTE} Purpose Use this command to paste the contents of the clipboard into the file at the current cursor position. Format SPASTE [ INSERT | OVERLAY ] [ LINE | STREAM | BLOCK ] Remarks If no parameters are specified, the contents of the clipboard are pasted into the file in the same mode as they were SCUT or SCOPYed. If the clipboard contents were not created by SPF/Pro they are pasted with "insert" and "stream" modes. The optional parameters are supplied to allow you to force the paste mode regardless of the SCUT or SCOPY mode that produced the clipboard contents. # 27.55 {SPRINT} Purpose Use this command to print the current selection. Format SPRINT Remarks For all selection types, only selected characters are printed. # 27.56 {SREPLACE} Purpose Use this command to create or replace an external file with the contents of the selection. Format SREPLACE [ file-name ] Remarks Selections are made with the mouse. The selection is not deleted from the file. If you don't specify a file name, a dialog panel is presented which enables you to enter the target file name. If the file already exists, SREPLACE will overwrite it. To avoid overwriting the file with the selection, use SCREATE. # 27.57 {STATS} Purpose The STATS command is used to request the generation of statistics (level stamping) when standard numbering is on. Format STATS [ON ] [OFF] Remarks When STATS is on and line numbering is standard (STD), columns 79 and 80 contain a level number. Each time SPF/Pro starts editing such a file, it finds the largest level number and adds one to it. Unless this number is overridden by a LEVEL command, it places this new number in the level number field of any record that is changed or inserted. By using this, you can tell which records have been updated and relatively when the update took place. # 27.58 {STOLOWER} Purpose Use this command to convert all the alpha characters in the selection to lowercase. Format STOLOWER Remarks Selections are made with the mouse. # 27.59 {STOUPPER} Purpose Use this command to convert all the alpha characters in the selection to uppercase. Format STOUPPER Remarks Selections are made with the mouse. # 27.60 {SXCLUDE} Purpose Use this command to exclude all the lines which are touched by the selection. Format SXCLUDE Remarks Selections are made with the mouse. # 27.61 {TABS} Purpose Enables or disables logical and hardware tabs. Defines the logical tab character. All tab stops are defined with the TABS line command. See page for details. Format TABS [ON ] [tab-character] TAB [OFF] [ STD | ALL ] Remarks Set tabs ON to enable logical and hardware tabs. Set tabs OFF to disable logical and hardware tabs. Software tabs are always ON and do not interact with the TABS primary command. The tab character is used for logical tabs only. For tabs ON, the operation of hardware tabs is determined by the STD and ALL keywords. If STD is specified, hardware tab columns which are occupied by text are ignored. That is when [TAB] is pressed, it skips over any hardware tab column which contains a non-blank character. If ALL is specified, when [TAB] is pressed, it stops at all hardware tab positions regardless of the contents of the line. If neither STD or ALL is specified, STD is assumed. # 27.62 {TOP} Purpose Use this command to position to the top of the file. Format TOP Remarks None. # 27.63 {UNDO} Purpose Use this command to undo alterations made to a file during EDIT. Format UNDO [ ON | OFF ] [ nnn | ALL ] [ CLEAR ] Remarks In the normal use of EDIT, you make numerous changes to a file. When undo processing is on, each change is recorded in a journal which may subsequently be used to undo a change. If no parameters are specified, the last recorded alteration is undone. If a number is specified, the last "nnn" recorded alterations are undone. If ALL is specified, all recorded alterations are undone. If ON is specified, UNDO support is activated. If OFF is specified, UNDO support is de-activated. When setting UNDO on or off, the state is kept in a file profile variable associated with the file type of the file being edited. For convenience, SPF/Pro also supports a global variable which can be used to override the file profile setting for all file types. You can set the global UNDO state in Options panel 0.5. If CLEAR is specified, the UNDO recording area is cleared and a new UNDO journal is started. After an UNDO you may want to redo the undone alteration. To redo undone alterations, see the REDO primary command. # 27.64 {UNNUM} Purpose Turns off NUMBER mode and clears sequence numbers. Format UNNUM UNN Remarks This command blanks out STANDARD and COBOL sequence numbers. To blank out sequence numbers when NUMBER mode is off, first enter the NUMBER command with the proper options. Then enter the UNNUM command. Note: This command is valid only when NUMBER mode is on. # 27.65 {UP} Purpose Same as [F7] key. Use this command to move toward the top of the file. Format UP [PAGE] [HALF] [CSR ] [DATA] [MAX ] [nnnn] Remarks There are three ways to specify how much SPF/Pro moves when you issue the command: 1. Issue the command without a scroll amount. In this case the SCROLL field determines the amount scrolled. The SCROLL field is in the upper right corner of the screen. 2. Issue the command with a scroll amount. Type the command and the amount, or type the amount and press the appropriate PF key. 3. Change the SCROLL field and execute step 1. Note: Scroll amounts can be abbreviated. For example, P for PAGE, M for MAX, etc. Example [F7] Move up by amount specified in SCROLL field. UP 8 Move up eight lines. Type 8 in command field, then press [F7] Also, move up eight lines. # 27.66 {XMACRO} Purpose Saves the name of an exit macro in the current edit profile. Format XMACRO [name] [NONE] Remarks You can specify either: name The name of the exit macro to be executed before exiting a file that matches this file's type. The XMACRO is executed just before the file is written to disk after a SAVE or END command. Specify NONE to reset the XMACRO value. Example To set ENDUP as the exit macro: XMACRO ENDUP To reset the edit profile to no exit macro: XMACRO NONE # 28. {Edit Line Commands} Line commands provide a more discrete method of dealing with the data in your file than do the primary commands. They allow a you to add, delete, repeat, overlay, move, or copy individual lines or blocks of lines. They can change indentation, exclude or include lines, and position data within columns. Line commands are entered in columns 1 through 6 of each display line. This field is called the sequence number field or the line command area, depending on your preference. Single character line commands, such as C, M, and D operate on individual lines. Double character line commands, such as CC, MM, and DD, operate on blocks of lines. A number may follow a line command to indicate the number of times that the command is to be applied to a line or block. For example, "D" deletes a single line; "D3" deletes three lines. Line commands are not applied (executed) until [SPF-Enter] is pressed. So for example you could repeat a line (with R), delete a different line (with D) and insert a new line (with I) all at once when [SPF-Enter] is pressed. New empty lines are indicated by a sequence number field of all single quotes (''''''). You can enter line commands over the single quotes. In text entry mode (see page ), after you have entered all the desired text and no line numbers exist, press [SPF-Enter]. Unused new lines at the end of the new text block are deleted and the remaining lines are assigned sequence numbers. You may then enter line commands as desired. The following rules apply to all edit line commands: * Several line commands may be entered at a given time as long as [SPF-Enter] has not been pressed. After [SPF-Enter] is pressed, line commands are validity checked; error messages are displayed if conflicts or ambiguities exist. Line commands are processed from top to bottom, so it is possible to have only one error message displayed when multiple errors exist. * Line commands may be entered at any position in the sequence number field. Generally, only one or two characters are needed. * Some line commands are not executed when [SPF-Enter] is pressed. For example, copy (C) and move (M) commands are not executed unless a corresponding destination is specified with the after (A) or before (B) line command. * Block commands like CC, MM, and DD won't execute until the beginning and end of the block have been marked. * The following commands may be entered on the top of data line: I[n] Insert "n" blank lines after this line. A Move or Copy line[s] after this line. TE Start text entry mode. * The following commands may be entered on the bottom of data line: B Move or copy line[s] before this line. * The [SPF-Enter] key activates all line commands. * If you have entered a line command which did not execute correctly, and you decide not to continue with it, you can either type blanks over it, or use the RESET primary command to reset all pending line commands. On the detailed command description pages which follow, operands listed within brackets [ ] are optional. Beneath the name of some commands is an abbreviated form which may be used instead of the full command name. # 28.1 {Line Command Summary} The following table summarizes the edit line commands which are detailed in the remainder of this chapter. Command Function < Data shift left. << Block data shift left. > Data shift right. >> Block data shift right. ( Column shift left. (( Block column shift left. ) Column shift right. )) Block column shift right. A After. B Before. BNDS Display/set bounds. C Copy. CC Block copy. COLS Display columns. D Delete. DD Block delete. F Display first excluded line(s). I Insert. L Display last excluded line(s). LC Set a line to lowercase. LCC Set a block of lines to lowercase. M Move. MM Move block. MASK Display/set mask. MD Make a NOTE or MSG line into a data line. MDD Make a block of NOTE or MSG lines into data lines. O Overlay. OO Overlay block. R Repeat. RR Repeat block. S Show structure excluded line(s). TABS Display/set tabs. TE Text entry. TF Text flow. TJ Text join. TS Text split. UC Set a line to uppercase. UCC Set a block of lines to uppercase. X Exclude. XX Exclude block. . Label assignment. # 28.1 {< (Data Shift Left)} Purpose Shifts a single line to the left without affecting program source labels or comments. A common format for computer program source is: * Labels start in column 1 * Op codes, operands, or reserved words start in any column greater than one and are separated by single blanks. * Comments follow op codes, operands, or reserved words and are separated from them by two or more blanks. The premise of data shift is that it shifts the op codes, operands, or reserved words without affecting the labels or comments. Format <[number] Remarks This command may be specified with or without a number. The number indicates how many columns to shift the data. The default shift is 2 columns. Shifting occurs within column boundaries (see Bounds line command on page for details). Non-blank characters are never deleted or truncated. If a shift is requested that would move data beyond the current bounds, the data is moved only to the current bounds, and an error flag is entered on the shift line. The error flag may be deleted by using the RESET primary command. 1. Scanning starts in the left boundary column. 2. The first blank character is found. 3. The next non-blank character is found. 4. The next double blank characters are found. 5. Data from step 3 to 4 are shifted left one column at a time as required to satisfy the shift request. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ <40031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ <80031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ ==ERR> IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ # 28.2 {<< (Block Data Shift Left)} Purpose Shifts a block of lines to the left without affecting program source labels or comments. Format <<[number] Remarks This command functions identically to the DATA SHIFT LEFT line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "<<". Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ <<4031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ <<0033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ <<4031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ <<0033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ ==ERR> IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ # 28.3 {> (Data Shift Right)} Purpose Shifts a single line to the right without affecting program source labels or comments. A common format for computer program source is: * Labels start in column 1 * Op codes, operands, or reserved words start in any column greater than one and are separated by single blanks. * Comments follow op codes, operands, or reserved words and are separated from them by two or more blanks. The premise of data shift is that it shifts the op codes, operands, or reserved words without affecting the labels or comments. Format >[number] Remarks The command may be specified with or without a number. The number may be specified on either or both lines, but the largest value is always used if a conflict exists. The default shift is two columns. Shifting occurs within column boundaries (see Bounds line command on page for details). Non-blank characters are never deleted or truncated. If a shift is requested that would move data beyond the current bounds, the data is moved only to the current bounds, and an error flag is entered on the shift line. The error flag may be deleted by using the RESET primary command. How data shift right works: 1. Scanning starts in the left boundary column. 2. The first blank character is found. 3. The next non-blank character is found. 4. The next double blank characters are found. 5. Data from step 3 to 4 is shifted right one column. One of the two blank characters found in step 4 is deleted. The above steps are logically repeated as many times as are required to satisfy the shift request. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ >40032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > >60029 /* Reset all work fields */ 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000029 /* Reset all work fields */ 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ # 28.4 {>> (Block Data Shift Right)} Purpose Shifts a block of lines to the right without affecting program source labels or comments. Format >>[number] Remarks This command functions identically to the DATA SHIFT RIGHT line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with ">>". Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ >>4032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ >>0034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > >>6027 /* Reset all work fields */ 000028 /* Reset all work fields */ >>0029 /* Reset all work fields */ 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000027 /* Reset all work fields */ 000028 /* Reset all work fields */ ==ERR> /* Reset all work fields */ 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ # 28.5 {( (Column Shift Left)} Purpose Shifts the current line to the left without regard to the size or content of the data. Format ([number] Remarks This command may be specified with or without a number. The default shift is 2 columns. Shifting occurs within column boundaries. See the Bounds line command, on page for details. Warning: This command shifts only within BOUNDS which may result in loss of data. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > (50001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > (70001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 g Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. # 28.6 {(( (Block Column Shift Left)} Purpose Shifts a block of lines to the left without regard to the size or content of the data. Format (([number] Remarks This command functions identically to the COLUMN SHIFT LEFT line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "((". Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ((4001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl ((0004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ((1101 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 ((0005 50 4 100 Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Price Cost 000002 000003 $25 $ 75 000004 35 70 000005 50 100 Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ((9001 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 ((0005 50 4 100 Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Number Cost 000002 000003 3 $ 75 000004 2 70 000005 4 100 # 28.7 {) (Column Shift Right)} Purpose Shifts the current line to the right without regard to the size or content of the data. Format )[number] Remarks The command may be specified with or without a number. The default shift is 2 columns. Shifting occurs within column boundaries. See the Bounds line command, on page for details. Warning: This command shifts only within BOUNDS which may result in loss of data. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > )40001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > )16001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Old King Cole was a merry old 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. # 28.8 {)) (Block Column Shift Right)} Purpose Shifts a block of lines to the right without regard to the size or content of the data. Format ))[number] Remarks This command functions identically to the COLUMN SHIFT RIGHT line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "))". Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ))4001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl ))0004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ))2001 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 ))0005 50 4 100 Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 000005 50 4 100 Example =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > ))8001 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 ))0005 50 4 100 Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Price Number 000002 000003 $25 3 000004 35 2 000005 50 4 # 28.9 {A (After)} Purpose Acts as a pointer to designate the line after which moved or copied text is to be placed. Format A Remarks A is used in conjunction with MOVE/COPY/PASTE primary and line commands to indicate the destination of the data. Note: This command is not valid on the bottom of data line, but it is valid on the top of data line. Example A00021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT C00023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET X-T-CT UP BY 1 000023 SET TEMP-INDEX TO X-T-CT 000024 SET X-T-CT UP BY 1 000025 ELSE 000026 PERFORM NNNN-DT-TO-VS-01 000027 MOVE 1 TO DSUB 000028 MOVE DATFLD-BC (DSUB) TO WCCOL 000029 END-IF. In the above example line 23 is copied after line 21. Note that line 21 was not changed. # 28.10 {B (Before)} Purpose Acts as a pointer to designate the line before which moved or copied text is to be placed. Format B Remarks B is used in conjunction with MOVE/COPY/PASTE primary and line commands to indicate the destination of the data. Note: This command is not valid on the top of data line, but it is valid on the bottom of data line. Example 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+3,20 SAY ' 1 - People names' B00024 @ ROW()+2,20 SAY ' 2 - Organization names' M00025 @ ROW()+2,20 SAY ' 3 - Serial number' 000026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' 000029 READ Results 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+3,20 SAY ' 1 - People names' 000024 @ ROW()+2,20 SAY ' 3 - Serial number' 000025 @ ROW()+2,20 SAY ' 2 - Organization names' 000026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' 000029 READ # 28.11 {BNDS (Bounds)} Purpose Displays current column bounds. You can change the bounds by typing over the "<" and ">" characters on the "=BNDS>" line. Format BNDS BND Remarks The left column bound is set at the "<" character. The right column bound is set at the ">" character. Moving either of these two characters changes the bounds. Bounds are used to limit the scope of: 1. Left-shift and right-shift line commands. 2. FIND, CHANGE, and EXCLUDE commands when explicit columns are not specified. 3. TS (text split), and TF (text flow) line commands. 4. The Overlay line command. 5. Left and right scrolling. When scrolling, a left scroll stops at the left bound, and a right scroll stops at the right bound. A subsequent left or right scroll goes beyond the bounds if they are not at the end of the line. Use the RESET primary command, or the D line command to remove the =BNDS> line from the display. Example =COLS> ----+----1----+----2----+----3----+----4----+-- BNDS01 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 000005 50 4 100 Results =COLS> ----+----1----+----2----+----3----+----4----+-- =BNDS> < > 000001 Price Number Cost 000002 000003 $25 3 $ 75 000004 35 2 70 000005 50 4 100 In the above example, a bounds line is displayed before line 1. The less than (<) or greater than (>) characters may be moved to redefine the bounds. You can also change the bounds with the BOUNDS primary command. For additional information, see page 294. # 28.12 {C (Copy)} Purpose Copies one or more lines to another location within the current file. It is also used with CREATE/REPLACE/CUT primary commands to copy lines between files. Format C[number] Remarks This command leaves the original line in place, and makes a duplicate at the new location. Type B or A on the line where the copied line is to be placed and a C on the line to be copied. A number may follow the C to indicate that more than one line is to be copied. This has the same effect as the Block Copy command. To see how lines may be copied between files, see the page 306 and page 331. Example A00021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT C00023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET X-T-CT UP BY 1 000023 SET TEMP-INDEX TO X-T-CT 000024 SET X-T-CT UP BY 1 000025 ELSE 000026 PERFORM NNNN-DT-TO-VS-01 000027 MOVE 1 TO DSUB 000028 MOVE DATFLD-BC (DSUB) TO WCCOL 000029 END-IF. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 B00024 ELSE C30025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 PERFORM NNNN-DT-TO-VS-01 000025 MOVE 1 TO DSUB 000026 MOVE DATFLD-BC (DSUB) TO WCCOL 000027 ELSE 000028 PERFORM NNNN-DT-TO-VS-01 000029 MOVE 1 TO DSUB 000030 MOVE DATFLD-BC (DSUB) TO WCCOL 000031 END-IF. # 28.13 {CC (Block Copy)} Purpose Copies a block of lines to another position within the current file. It is also used with CREATE/REPLACE/CUT primary commands to copy lines between files. Format CC Remarks This command functions identically to the COPY line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "CC". Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 B00024 ELSE CC0025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB CC0027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 PERFORM NNNN-DT-TO-VS-01 000025 MOVE 1 TO DSUB 000026 MOVE DATFLD-BC (DSUB) TO WCCOL 000027 ELSE 000028 PERFORM NNNN-DT-TO-VS-01 000029 MOVE 1 TO DSUB 000030 MOVE DATFLD-BC (DSUB) TO WCCOL 000031 END-IF. # 28.14 {COLS (Columns)} Purpose Displays a line with column numbers. Format COLS COL Remarks Use the RESET primary command, or D line command to to remove the =COLS> line from the display. The columns display line is not part of the data and is not saved at END. Example COLS01 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. Results =COLS> ----+----1----+----2----+----3----+----4----+-- 000001 Old King Cole was a merry old soul 000002 and a merry old soul was he. He called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. # 28.15 {D (Delete)} Purpose Deletes one or more lines from the file. Format D[number] Remarks D alone deletes a single line. An optional number following the delete command specifies the number of consecutive lines to delete. For example, "D3" deletes three lines. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE D00025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE 000025 MOVE 1 TO DSUB 000026 MOVE DATFLD-BC (DSUB) TO WCCOL 000027 END-IF. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE D20025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE 000025 MOVE DATFLD-BC (DSUB) TO WCCOL 000026 END-IF. # 28.16 {DD (Block Delete)} Purpose Deletes a block of lines from the file. Format DD Remarks This command functions identically to the DELETE line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "DD". Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT DD0023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB DD0027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 END-IF. # 28.17 {F (First)} Purpose Displays the first excluded line, or the first N excluded lines of an excluded block. Format F[number] Remarks This command may be specified with or without a number. If no number is specified, the first line of the excluded block is displayed. Warning: This command may be validly entered only on the excluded display line. If it is entered on any other line, an error message is generated. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE F - - - - - - - - 0003 LINE(S) NOT DISPLAYED 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 - - - - - - - 0002 LINE(S) NOT DISPLAYED 000028 END-IF. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE F3 - - - - - - - - 0003 LINE(S) NOT DISPLAYED 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. # 28.18 {I (Insert)} Purpose Inserts one or more temporary blank lines into the file. Format I[number] Remarks If I is entered without a number, one line is inserted. If I is entered with a number, the number of lines specified are inserted. If characters or spaces are entered on the inserted line, and if the cursor is still in the data portion of the last (or only) inserted line when [SPF-Enter] is pressed, another new line is automatically inserted following that line. This allows multiple lines to be entered in a "continuous insert" mode. If you want to retain inserted blank lines you must type at least one character (or blank) on them. If no characters (or blank) are entered on an inserted line, it is deleted when [SPF-Enter] is pressed. Use this technique to terminate "continuous insert". Example 000010 * This is a dBASE III program 000011 DO CASE I00012 CASE action = 'Q' 000013 RETURN 000014 CASE action = '1' 000015 CLEAR 000016 DO ndxname Results 000010 * This is a dBASE III program 000011 DO CASE 000012 CASE action = 'Q' '''''' 000014 RETURN 000015 CASE action = '1' 000016 CLEAR 000017 DO ndxname Example 000010 /* This is a C program */ I30011 main() { 000012 int sum,x,x; 000013 x = 20; 000014 y = 30; 000015 sum = x + y; 000016 printf("The sum of %d and %d = %d", 000017 x, y, sum); 000018 } Results 000010 /* This is a C program */ 000011 main() { '''''' '''''' '''''' 000015 int sum,x,x; 000016 x = 20; 000017 y = 30; 000018 sum = x + y; 000019 printf("The sum of %d and %d = %d", 000020 x, y, sum); 000021 } # 28.19 {L (Last)} Purpose Displays the last excluded line, or the last N excluded lines of an excluded block. Format L[number] Remarks This command may be specified with or without a number. If no number is specified, the last line of the excluded block is displayed. Warning: This command may be validly entered only on the excluded line indicator. If it is entered on any other line, an error message is displayed. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE L - - - - - - - - - 00003 LINE(S) NOT DISPLAYED 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE - - - - - - - - - - 00002 LINE(S) NOT DISPLAYED 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. Example 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE L3- - - - - - - - - 00003 LINE(S) NOT DISPLAYED 000028 END-IF. Results 000021 IF X-T-CT < TABLE-SIZ 000022 SET TEMP-INDEX TO X-T-CT 000023 SET X-T-CT UP BY 1 000024 ELSE 000025 PERFORM NNNN-DT-TO-VS-01 000026 MOVE 1 TO DSUB 000027 MOVE DATFLD-BC (DSUB) TO WCCOL 000028 END-IF. # 28.20 {LC (Lower Case)} Purpose Converts alphabetic characters on a line or group of lines to lowercase letters. Format LC[number] Remarks This command may be specified with or without a number. An optional number following the command specifies the number of consecutive lines to be converted to lowercase letters. Example 000001 OLD KING COLE WAS A MERRY OLD SOUL LC0002 AND A MERRY OLD SOUL WAS HE. HE CALLED 000003 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000004 AND HE CALLED FOR HIS FIDDLERS THREE. Results 000001 OLD KING COLE WAS A MERRY OLD SOUL 000002 and a merry old soul was he. he called 000003 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000004 AND HE CALLED FOR HIS FIDDLERS THREE. Example 000001 OLD KING COLE WAS A MERRY OLD SOUL LC2002 AND A MERRY OLD SOUL WAS HE. HE CALLED 000003 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000004 AND HE CALLED FOR HIS FIDDLERS THREE. Results 000001 OLD KING COLE WAS A MERRY OLD SOUL 000002 and a merry old soul was he. he called 000003 for his cap and he called for his bowl 000004 AND HE CALLED FOR HIS FIDDLERS THREE. # 28.21 {LCC (Block Lower Case)} Purpose Converts alphabetic characters within a block of lines to lowercase letters. Format LCC Remarks This command functions identically to the LOWER CASE line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "LCC". Example LCC001 OLD KING COLE WAS A MERRY OLD SOUL 000002 AND A MERRY OLD SOUL WAS HE. HE CALLED 000003 FOR HIS CAP AND HE CALLED FOR HIS BOWL LCC004 AND HE CALLED FOR HIS FIDDLERS THREE. Results 000001 old king cole was a merry old soul 000002 and a merry old soul was he. he called 000003 for his cap and he called for his bowl 000004 and he called for his fiddlers three. # 28.22 {M (Move)} Purpose Moves one or more lines to another location within the same file. It is also used with CREATE/REPLACE/CUT primary commands to move lines between files. Format M[number] Remarks This command deletes the original lines and moves them to a new location. Type B or A on a line to indicate where the moved line is to be placed. Type an M on the line to be moved. The line marked with M is moved and placed before (B) or after (A) the designated line. A number may follow the M to indicate that more than one line is to be moved. This has the same effect as the Block Move command. To see how lines may be copied between files see the page 306 and page 331. Example 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+3,20 SAY ' 1 - People names' B00024 @ ROW()+2,20 SAY ' 2 - Organization names' M00025 @ ROW()+2,20 SAY ' 3 - Serial numbers' 000026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' Results 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+3,20 SAY ' 1 - People names' 000024 @ ROW()+2,20 SAY ' 3 - Serial numbers' 000025 @ ROW()+2,20 SAY ' 2 - Organization names' 000026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' Example 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' M30023 @ ROW()+3,20 SAY ' 1 - People names' 000024 @ ROW()+2,20 SAY ' 2 - Organization names' 000025 @ ROW()+2,20 SAY ' 3 - Serial numbers' A00026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' Results 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000024 @ ROW()+3,20 SAY ' 1 - People names' 000025 @ ROW()+2,20 SAY ' 3 - Serial numbers' 000026 @ ROW()+2,20 SAY ' 2 - Organization names' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' # 28.23 {MM (Block Move)} Purpose Moves a block of lines to another position within the same file. It is also used with CREATE/REPLACE/CUT primary commands to move lines between files. Format MM Remarks This command functions identically to the MOVE line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "MM". Example 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' MM0023 @ ROW()+3,20 SAY ' 1 - People names' 000024 @ ROW()+2,20 SAY ' 2 - Organization names' MM0025 @ ROW()+2,20 SAY ' 3 - Serial numbers' A00026 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' Results 000020 * This is a part of a dBASE III program 000021 CLEAR 000022 @ 4,15 SAY 'List By:' 000023 @ ROW()+2,20 SAY ' Q - Return to previous menu' 000024 @ ROW()+3,20 SAY ' 1 - People names' 000025 @ ROW()+2,20 SAY ' 3 - Serial numbers' 000026 @ ROW()+2,20 SAY ' 2 - Organization names' 000027 @ ROW()+3,15 SAY 'Press your selection ' ; 000028 GET action PICTURE '!' # 28.24 {MASK (Mask Line)} Purpose Allows a user to define a mask to be used in building a new line. The mask is applied to lines inserted with the Insert (I) line command. Format MASK Remarks A typical use of Mask would be to pre-load comment delimiters in all new lines. This would eliminate extra keying. Until data is entered on a new line, it is considered empty, even though it contains the mask data. If you wish to retain an empty mask line, you must enter at least one blank or space on it. A mask remains in effect (even if it is not displayed) until it is changed. It is used the next time an edit session is begun. Note: Only one Mask may be defined. It is used for all file extensions. Example MASK30 ZEROS: 000031 IF WORK = 0 THEN /* Only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =MASK> /* */ 000030 ZEROS: 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ The mask setting was entered previously. Now, you can change the mask by typing directly on the =MASK> line. Example =MASK> /* */ I00030 ZEROS: 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =MASK> /* */ 000030 ZEROS: '''''' /* */ 000032 IF WORK = 0 THEN /* only if 0 */ 000033 SALES = 0; /* zero sales */ 000034 CUSTOMER = ''; /* blank customer */ 000035 END; /* end if */ The above example shows a new line pre-loaded with comment delimiters. Example =MASK> /* */ I30030 ZEROS: 000031 IF WORK = 0 THEN /* only if 0 */ 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Results =MASK> /* */ 000030 ZEROS: '''''' /* */ '''''' /* */ '''''' /* */ 000034 IF WORK = 0 THEN /* only if 0 */ 000035 SALES = 0; /* zero sales */ 000036 CUSTOMER = ''; /* blank customer */ 000037 END; /* end if */ # 28.25 {MD (Make Data)} Purpose Converts a NOTE or MSG line to a data line. Format MD[number] Remarks This command may be specified with or without a number. An optional number following the command specifies the number of consecutive lines to be converted to data. Example 000001 OLD KING COLE WAS A MERRY OLD SOUL MDOTE= Note line to be data. 000002 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000003 AND HE CALLED FOR HIS FIDDLERS THREE. Results 000001 OLD KING COLE WAS A MERRY OLD SOUL 000002 Note line to be data. 000003 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000004 AND HE CALLED FOR HIS FIDDLERS THREE. # 28.26 {MDD (Block Make Data)} Purpose Converts a block of NOTE or MSG lines to data lines. Format MDD Remarks This command functions identically to the MAKE DATA line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with MDD. Example 000001 OLD KING COLE WAS A MERRY OLD SOUL MDDTE= Note lines to be data. =NOTE= Notes line to be data. MDDTE= Note lines to be data. 000002 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000003 AND HE CALLED FOR HIS FIDDLERS THREE. Results 000001 OLD KING COLE WAS A MERRY OLD SOUL 000002 Notes line to be data. 000003 Notes line to be data. 000004 Notes line to be data. 000005 FOR HIS CAP AND HE CALLED FOR HIS BOWL 000006 AND HE CALLED FOR HIS FIDDLERS THREE. # 28.27 {O (Overlay)} Purpose Overlays data in one or more lines with the data from one or more lines. Format O[number] Remarks The line(s) specified by C, Cn, CC (copy), or M, Mn, MM (move), overlay the line(s) containing the O (overlay) command. Only one line is overlaid unless a number is specified. Only those characters that are within the current BOUNDS participate in the overlay operation. See the BOUNDS line command, on page 381 for details. The number of source and receiving lines need not be the same. If there are more receiving lines, the sources lines are repeated until the receiving lines are used up. If there are more source lines, the extra source lines are ignored. Any blank characters in the receiving lines are overlaid with corresponding characters from the source lines. A move request is changed to a copy if characters cannot be overlaid or if there are more source lines than receiving lines. An error message is generated. Example M00029 /* */ 000030 ZEROS: O30031 IF WORK = 0 THEN 000032 SALES = 0; 000033 CUSTOMER = ''; 000034 END; Results 000029 ZEROS: 000030 IF WORK = 0 THEN /* */ 000031 SALES = 0; /* */ 000032 CUSTOMER = ''; /* */ 000033 END; Example O50030 ZEROS: 000031 IF WORK = 0 THEN 000032 SALES = 0; 000033 CUSTOMER = ''; 000034 END; M50035 /* zero work fields */ 000036 000037 /* zero sales */ 000038 /* blank customer */ 000039 /* end if */ Results 000030 ZEROS: /* zero work fields */ 000031 IF WORK = 0 THEN 000032 SALES = 0; /* zero sales */ 000033 CUSTOMER = ''; /* blank customer */ 000034 END; /* end if */ Example M20030 /* Name */ 000031 /* Address */ O40032 John Doe 000033 123 Palm Street 000034 John Smith 000035 456 First Street Results 000030 John Doe /* Name */ 000031 123 Palm Street /* Address */ 000032 John Smith /* Name */ 000033 456 First Street /* Address */ # 28.28 {OO (Block Overlay)} Purpose Overlays data in one or more lines with the data from one or more lines. Format OO Remarks This command functions identically to the OVERLAY line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "OO". Example M00029 /* */ 000030 ZEROS: OO0031 IF WORK = 0 THEN 000032 SALES = 0; OO0033 CUSTOMER = ''; 000034 END; Results 000029 /* */ 000030 ZEROS: 000034 IF WORK = 0 THEN /* */ 000035 SALES = 0; /* */ 000036 CUSTOMER = ''; /* */ 000037 END; Example OO0001 Quantity Price 000002 1 - 20 $1,000 000003 21 - 50 900 000004 51 - 99 750 OO0005 over 100 500 000006 MM0007 Discount 000008 0% 000009 10% 000010 25% MM0011 50% Results 000001 Quantity Price Discount 000002 1 - 20 $1,000 0% 000003 21 - 50 900 10% 000004 51 - 99 750 25% 000005 over 100 500 50% 000006 # 28.29 {R (Repeat)} Purpose Duplicates a line in place as many times as specified. Format R[number] Remarks If no number is specified, the line is duplicated once. If a number is specified, the line is duplicated as many times as specified by number. Example R00001 100 REM THIS IS A BASIC PROGRAM 000002 110 FOR X = 1 TO 100 000003 120 PRINT "THE NUMBER IS " 000004 130 PRINT X 000005 140 Y = 1 000006 150 NEXT X Results 000001 100 REM THIS IS A BASIC PROGRAM 000002 100 REM THIS IS A BASIC PROGRAM 000003 110 FOR X = 1 TO 100 000004 120 PRINT "THE NUMBER IS " 000005 130 PRINT X 000006 140 Y = 1 000007 150 NEXT X Example R50001 100 REM THIS IS A BASIC PROGRAM 000002 110 FOR X = 1 TO 100 000003 120 PRINT "THE NUMBER IS " 000004 130 PRINT X 000005 140 Y = 1 000006 150 NEXT X Results 000001 100 REM THIS IS A BASIC PROGRAM 000002 100 REM THIS IS A BASIC PROGRAM 000003 100 REM THIS IS A BASIC PROGRAM 000004 100 REM THIS IS A BASIC PROGRAM 000005 100 REM THIS IS A BASIC PROGRAM 000006 100 REM THIS IS A BASIC PROGRAM 000007 110 FOR X = 1 TO 100 000008 120 PRINT "THE NUMBER IS " 000009 130 PRINT X 000010 140 Y = 1 000011 150 NEXT X # 28.30 {RR (Block Repeat)} Purpose Duplicates a block of lines in place as many times as specified. Format RR[number] Remarks This command functions identically to the REPEAT line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "RR". Example 000001 100 REM RR0002 110 FOR X = 1 TO 100 000003 120 PRINT "THE NUMBER IS " 000004 130 PRINT X RR0005 140 NEXT X Results 000001 100 REM 000002 110 FOR X = 1 TO 100 000003 120 PRINT "THE NUMBER IS " 000004 130 PRINT X 000005 140 NEXT X 000006 110 FOR X = 1 TO 100 000007 120 PRINT "THE NUMBER IS " 000008 130 PRINT X 000009 140 NEXT X Example 000001 100 REM RR2002 110 FOR X = 1 TO 100 000003 120 PRINT X RR0004 130 NEXT X Results 000001 100 REM 000002 110 FOR X = 1 TO 100 000003 120 PRINT X 000004 130 NEXT X 000005 110 FOR X = 1 TO 100 000006 120 PRINT X 000007 130 NEXT X 000008 110 FOR X = 1 TO 100 000009 120 PRINT X 000010 130 NEXT X # 28.31 {S (Show)} Purpose Displays excluded line(s) based on the indentation hierarchy of those lines. Format S[number] Remarks This command may be specified with or without a number. The line or lines with the least amount of indentation are displayed first, followed by lines at the next level of indentation and so forth. Warning: This command may be validly entered only on the excluded display line. If it is entered on any other line, an error message is generated. Example 000088 DO CASE S6- - - - - - - - - 00030 LINE(S) NOT DISPLAYED 000110 ENDCASE Results 000088 DO CASE - - - - - - - - - - 00001 LINE(S) NOT DISPLAYED 000090 CASE action = 'X' - - - - - - - - - - 00003 LINE(S) NOT DISPLAYED 000094 CASE action = 'Q' - - - - - - - - - - 00003 LINE(S) NOT DISPLAYED 000099 CASE action = '1' - - - - - - - - - - 00002 LINE(S) NOT DISPLAYED 000102 CASE action = '2' - - - - - - - - - - 00002 LINE(S) NOT DISPLAYED 000105 CASE action = '3' - - - - - - - - - - 00002 LINE(S) NOT DISPLAYED 000108 OTHERWISE - - - - - - - - - - 00001 LINE(S) NOT DISPLAYED 000110 ENDCASE # 28.32 {TABS (Tab Line)} Purpose Displays or modifies the current tab settings. Format TABS TAB Remarks There are three types of tabs in SPF/Pro: hardware Hardware tab stops are defined with the asterisk (*) character on the TABS line. Each time the [TAB] key is pressed, the cursor is advanced to one position to the right of the next hardware tab stop. If the cursor is in the line command field, it is positioned to column 1. This function only works when tabs are set ON with the TABS primary command. See page 357 for details. logical When data is entered with an initial logical tab character, it is positioned to one character to the right of the next hardware tab stop. This function only works when tabs are set ON and a logical tab character has been defined with the TABS primary command. See page 357 for details. software Software tab stops are defined with the underscore(_) or hyphen (-) character. Each time [SPF-Enter] is pressed, the cursor is advanced to the next software tab stop. Software tabs are always ON independent of the TABS primary command. Example In the following example the TABS line command is entered on line 000031. The clear tabs line is displayed immediately above it. The hardware tab character asterisk (*) is entered in columns 9, 19, and 29. =COLS> ----+----1----+----2----+----3----+----4--- =TABS> * * * 000031 /* EXAMPLE SHOWS HARDWARE TAB DEFINITION */ The primary command "TABS ON" is entered. At this point hardware tabs are both defined and ON. With this hardware tab definition and starting with the cursor in the line command field, the cursor is positioned to columns 1, 10, 20, and 30 as the [TAB] is repeatedly depressed. You can enter data at any point after positioning the cursor with [TAB]. Example The next example shows how logical tabs would be used to position data in place of using [TAB] to do the positioning. Enter primary command "TABS ON \" to turn tabs ON and define the logical tab character as backslash (\). With the same hardware tab definition from the above example, enter the "I" line command on line 000031. When the empty null line is presented key in "\aaa \bbb \ccc" starting at column 1. Press [SPF-Enter]. The editor positions the three data strings one position to the right of the respective hardware tab stops. =COLS> ----+----1----+----2----+----3----+----4 =TABS> * * * 000031 /* EXAMPLE SHOWS USE OF LOGICAL TABS */ '''''' \aaa \bbb \ccc Results =COLS> ----+----1----+----2----+----3----+----4 =TABS> * * * 000031 /* EXAMPLE SHOWS USE OF LOGICAL TABS */ 000032 aaa bbb ccc Example The next example shows how to define software tabs and use the [SPF-Enter] key for positioning. The software tab character hyphen (-) is entered in columns 10, 20, and 30. With this software tab definition and starting with the cursor in the line command field, the cursor is positioned to columns 10, 20, and 30 as the [SPF-Enter] key is repeatedly depressed. You can enter data at any point after positioning the cursor with the [SPF-Enter] key. =COLS> ----+----1----+----2----+----3----+----4--- =TABS> - - - 000031 /* EXAMPLE SHOWS SOFTWARE TAB DEFINITION */ # 28.33 {TE (Text Enter)} Purpose Opens space for text entry. This mode is generally used for entering text for publishing applications. Format TE Remarks When text entry mode is begun, line numbers disappear. You may type without worry about reaching line end. The cursor skips from the end of one line to the starting position of the next line automatically. You can type continuously. When the text reaches the right edge of the data area it is folded to the next line. To exit text entry, press [SPF-Enter]. Note: At the end of a page, a new page is automatically displayed and word wrap occurs. Note: Tabs are still functional during text entry. # 28.34 {TF (Text Flow)} Purpose Flows the current paragraph of text to fit within defined BOUNDS. Format TF[number] Remarks This command works in conjunction with the BNDS command, see page 381 for details. It is used to restructure paragraphs after deletions, text splits, insertions etc. The text flow begins on the line that the command is entered and flows text until an end of paragraph condition is reached. The end of paragraph is determined by a blank line, a change in indentation, or the special characters period (.), colon (:), ampersand (&), less than (<), or form feed (CTRL L) at the beginning of a line. Text flow restructures a paragraph by removing trailing blanks. It does not remove leading or embedded blanks. For this reason, it is important to delete words within a line by using [DEL] rather than by typing over words with blanks. Because of this, the first line indent in a paragraph is preserved with Text Flow. If number is specified, it is used as a temporary right bound. Paragraph text is flowed to the extent of this new temporary bound. Note: If the temporary right bound is outside of the current bounds, it is ignored and the current bounds are used. Note: If a word is too large to fit within the current bounds, an error message is presented. # 28.35 {TJ (Text Join)} Purpose Joins the current and following line. This command is, in effect, the reverse of the Text Split command. Format TJ Remarks The text join command operates within the current bounds. Data in the next line (being appended) that is outside the current bounds is deleted. Example TJ0402 The text in the following line 000403 is appended 000404 to the text in the current line. Results 000402 The text in the following line is appended 000403 to the text in the current line. # 28.36 {TS (Text Split)} Purpose Splits a line of text at the cursor location. Format TS[number] Remarks Position the cursor where the line is to be split and press [SPF-Enter]. If a number is not specified, only one blank line appears between the split line segments. If number is specified, that number of blank lines is inserted between the split line segments. The text split command operates within the current bounds and leaves data outside the bounds unchanged. If the cursor is outside the bounds, the request is ignored. Example 000402 If a number parameter is specified, TS0403 new lines will be inserted between the split 000404 text segments. Results 000402 If a number parameter is specified, 000403 new '''''' 000405 lines will be inserted between the split 000406 text segments. # 28.37 {UC (Upper Case)} Purpose Converts alphabetic characters on a line or group of lines to uppercase letters. Format UC[number] Remarks This command may be specified with or without a number. An optional number after the command specifies the number of consecutive lines to be converted to uppercase letters. Example UC0022 If a number is specified, that 000023 number of consecutive lines is converted 000024 to uppercase letters. In this way the 000025 number parameter functions in the 000026 same way as does the Block Upper Case 000027 command. Results 000022 IF A NUMBER IS SPECIFIED, THAT NUMBER 000023 of consecutive lines is converted 000024 to uppercase letters. In this way the 000025 number parameter functions in the 000026 same way as does the Block Upper Case 000027 command. Example UC3022 If a number is specified, that number 000023 of consecutive lines is converted 000024 to uppercase letters. In this way the 000025 number parameter functions in the 000026 same way as does the Block Upper Case 000027 command. Results 000022 IF A NUMBER IS SPECIFIED, THAT NUMBER 000023 OF CONSECUTIVE LINES IS CONVERTED 000024 TO UPPERCASE LETTERS. IN THIS WAY THE 000025 number parameter functions in the 000026 same way as does the Block Upper Case 000027 command. # 28.38 {UCC (Block Upper Case)} Purpose Converts alphabetic characters within a block of lines to uppercase letters. Format UCC Remarks This command functions identically to the UC line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "UCC". Example UCC001 This is the start of the letter. 000002 I think that I would like to change these UCC003 Lines to all uppercase characters. Results 000001 THIS IS THE START OF THE LETTER. 000002 I THINK THAT I WOULD LIKE TO CHANGE THESE 000003 LINES TO ALL UPPER CASE CHARACTERS. # 28.39 {X (Exclude)} Purpose Excludes one or more lines from view. Format X[number] Remarks This command may be specified with or without a number. An optional number after the command specifies the number of consecutive lines to be excluded from view. This command is helpful when trying to view two groups of lines which are far apart in a file. The lines in between can be excluded from the display but are not deleted from the file. The exclude command is often used in conjunction with the FIND and CHANGE primary commands to limit the scope of a search. See FIND, CHANGE, and EXCLUDE primary commands for global operations. Note: Use the RESET primary command redisplay all excluded lines. Example 000010 /* This is a C program */ 000011 main() { X00012 int sum,x,y; 000013 x = 20; 000014 y = 30; 000015 printf("The sum of %d and %d = %d", 000016 x,y,(x+y)); 000017 } Results 000010 /* This is a C program */ 000011 main() { - - - - - - - - - - 00001 LINE(S) NOT DISPLAYED 000013 x = 20; 000014 y = 30; 000015 printf("The sum of %d and %d = %d", 000016 x,y,(x+y)); 000017 } Example 000010 /* This is a C program */ 000011 main() { X600012 int sum,x,y; 000013 x = 20; 000014 y = 30; 000015 sum = x + y; 000016 printf("The sum of %d and %d = %d", 000017 x, y, sum); 000018 } Results 000010 /* This is a C program */ 000011 main() { - - - - - - - - - - 00006 LINE(S) NOT DISPLAYED 000018 } 28.40 {XX (Block Exclude)} Purpose Excludes a block of lines from viewing. Format XX Remarks This command functions identically to the EXCLUDE line command except it operates on a block of lines rather than a single line. It is necessary to mark both the beginning and end of the block with "XX". Example 000010 /* This is a C program */ 000011 main() { XX0012 int sum,x,y; 000013 x = 20; 000014 y = 30; 000015 sum = x + y; 000016 printf("The sum of %d and %d = %d", XX0017 x, y, sum); 000018 } Results 000010 /* This is a C program */ 000011 main() { - - - - - - - - - - 00006 LINE(S) NOT DISPLAYED 000018 } # 28.41 {. (DOT, Label Assign)} Purpose Assigns a label to a line. Normally labels are assigned to lines so that later they may be used as range parameters. Format .label Remarks Labels may be assigned to any non-excluded line. A label is typed in the line command area. It begins with a period (.), and is followed by one to five alphabetic characters. You may not begin a label with the letter "Z". Labels beginning with the letter "Z" are reserved by the system. The following system labels are available at all times: .ZF The first line of the file. .ZFIRST The first line of the file .ZL The last line of the file. .ZLAST The last line of the file. .ZCSR The cursor line. Labels are not part of the data and are not stored by the system at END. Therefore, it is not necessary to RESET or clear them. # 29. {Dialog Development Introduction} SPF/Pro is designed to support the development of Edit Macros and SPF Dialogs which are consumed at the department, division, or company wide level. In the normal course of events, the individual SPF/Pro end user is not inclined to develop sophisticated Edit Macros or SPF Dialogs on a broad basis. The predominant scenario is that of one or more interested and able developers providing macros and dialogs to their constituency of end users. SPF/Pro provides all the functions, features, and run time support needed by end users to exploit locally developed extensions to the base environment. Source is provided for all SPF/Pro panels including the Custom Dialogs for Micro Focus and XDB. Most ISPF panels developed under MVS will run without alteration on SPF/Pro. Modifications to these panels to adapt or extend are easily accomplished. In SPF/Pro we interpret the meaning of many of the MVS ISPF panel definition components within a GUI paradigm automatically. This enables the developer's applications to be rendered in a modern style and with modern behavior without alteration. # 29.1 {Major New Features} * New Display Services - ADDPOP Support - Source for 390 SPF/Pro panels - On screen 'popup' command windows - Extended Selection in Tables - Dialog Test (Panels) * Program Authoring Enhancements - REXX PDS Access API - Configurable Command Tables - DM Function PGM(...) and BACKPGM(...) Support - Improved and extended ISREDIT Support - Improved and extended ISPEXEC Support - Dialog Test (Programs) - Record Level Print Interface - Extended Table Services to include Directory Services This manual is divided into three main sections. In the first section we discuss how to develop an application in SPF/Pro and lead you through the development of a sample REXX procedure using the ISPEXEC interface and in the development of an EDIT MACRO using the ISREDIT interface. Along the way we introduce the tools, such as dialog test and the TTY interface which have been designed to aid the development process. This section also discusses in detail the role of the directory structures to ensure that user developed applications do not collide with SPF/Pro supplied ones. The dialog development tools such as PDS Support, Dialog Test, Command Tables, and the TTY interface are described in detail in the second part. The third section is a reference for the REXX programming language, ISREDIT, and ISPEXEC commands which SPF/Pro supports. This section is also complete reference to the panels and commands designed to aid application development. # 29.2 {Assumptions} In this manual we assume that you are familiar with the normal processes of application development from design and implementation to testing and debugging. We also assume you have a basic knowledge of REXX. We explain any uses of REXX which are specific to Command Technology's implementation or which may be unclear to novice users. Common pitfalls in REXX usage are highlighted where they may occur. The developer is also expected to have reasonable understanding of the workings and behavior of SPF/Pro. # 29.3 {Sample} Solutions to sample problems can be found in the installation directory \SPFPRO\SAMPLES. Each is self documenting. Where a progressive solution is developed the file's extension reflects that as in .001, .002 etc. # 29.4 {Sample Warranty Information} SAMPLE SOURCE CODE AND PANEL DEFINITIONS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. # 30. {Application Building Overview} SPF/Pro provides you with the ability to develop two kinds of applications. The choice is determined by a number of factors of which complexity and competancy are the two most important. The different types of application one can develop are shown below: * REXX Procedure using ISPEXEC commands This kind of application is the most common. It allows you to extend SPF/Pro's functionality and to customize the provided dialogs to exactly meet the needs of their installation. These applications can be as complex as a Source Library management system or as simple as doing some routine File Sizing calculations. * REXX Procedure using ISREDIT commands Edit macros are written in REXX and use ISREDIT commands to communicate with Edit. Edit macros allow you to automate complex and repetitive edit processes and, in effect, create new Edit commands. An edit macro could be designed, for example, to identify all the 'Date' fields in a program source which are in 6 digit format and convert them to 8 digit format in readiness for the end of the century. Alternatively a macro could be designed extract data lines with a particular combination of values into a new file, perhaps separating wholesale from retail sales records. # 30.1 {Sample Application} The sample application is designed to demonstrate the main features of SPF/Pro. We have chosen to implement a simple appointment diary. This enables us to demonstrate panel definitions, table services, GUI panel controls, edit macros, popup menus, and SPF/Pro tools such as PDS management and dialog services, needed to implement the appointment list. # 30.1.1 {Appointment Diary} The appointment diary should be an option added to the Applications Menu and also should be available from the command line anywhere in SPF/Pro by typing command DIARY. You should have the ability to make entries into the diary and to be able to modify them and delete them. Duplicate entries should not be allowed. The diary should provide a number of sorting options, such as date/time, location, subject. If required, you should be able to print out selective parts of the diary. Where possible you should be able to use the mouse for control of the appointment list. You should also be able to quickly create a report heading and sample layout for a meeting report following a concluded meeting. Ideally a new edit session would be started and by typing a simple command, REPORT for example, a skeleton report would be generated using the most recent appointment details as the heading content. # 30.1.2 {Development Stages} SPF/Pro applications need to be developed with the same care as in any other environment. SPF/Pro makes it easy to develop, modify, or enhance very sophisticated dialog applications. It lends itself to prototyping and demonstration very well. In our discussion we look at the application, select an implementation strategy, design the solution, implement it, test it, and finally debug it. In our example we will: * develop and test the panel * create a REXX procedure to display the panel * test the panel using interactive tool TRACE * add code to make new entries in the diary * add code to retrieve entries from the diary * add code to delete entries from the diary * add code to modify entries in the diary * create the Edit Macro to build the Report Skeleton * add the application to the Samples Menu * add the new command to SPF/Pro command tables # 30.1.3 {Selecting Implementation Strategy} As discussed above, we have two main approaches to implementation in SPF/Pro. These can be characterized as the ISPEXEC and the ISREDIT solutions. In this example we are going to implement the solution using REXX and ISPEXEC statements for the diary application and REXX and ISREDIT for the edit macro application. We have chosen to implement the Appointment Diary application in REXX with embedded ISPEXEC statements because the complexity is low and because it gives us a good deal of control within SPF/Pro over the testing and debugging of the application. The application can be developed incrementally with each component separately tested. If the application is written in REXX, no special interface is required. Variables known to the REXX pool are also known to SPF/Pro and do not have to be defined. The Report Skeleton part of the application needs to be implemented as an Edit Macro because it interfaces directly with Edit. This means that REXX and ISREDIT calls do the majority of the work though some ISPEXEC calls are required in order to get the report heading details. # 30.1.4 {Understanding Directory Structure} When an application is to be attached to the SPF/Pro menu structure it is desirable to keep it separate and discreet from other user written and Command Technology supplied utilities. This is why SPF/Pro has sub-directories for user designed code and user developed panels. * REXX Procedures - can be stored in directory REXX\USER directory which is found under the directory where SPF/Pro is installed. Additionally you can place your REXX procedures in any directory that appears on the path referred to by variable ZMACPATH. The value for this variable is set via option 0.8. * Panels - when you develop panels you have the same storage options as you do for your REXX procedures. You can place your Panels in directory called PAN\USER which is also found where SPF/Pro is installed. The profile variable ZPANPATH specifies where alternate directories exist for panels and this too can be altered via panel 0.8. Additionally, you may store panels in a PDS, a Partitioned Data Set. PDS's allow you to store similar file types inside another file. This is primarily beneficial in saving disk space as PDS members take considerably less space than they would as individual files. Keeping the number of control files to a minimum also increases the speed at which the operating system can find files. There are nearly 500 panels in SPF/Pro so we keep our own panels in PDS's. See the section on PDS's for a more detailed description. * Data - REXX macros usually record data in SPF/Pro tables. Tables are stored in directory PROFILES also found under the SPF/Pro directory. (there is no USER sub directory in this case). This directory is determined by the value of the ZPRFPATH profile variable which, like the ones for REXX and Panels, can be set via Option 0.8. # 30.1.5 {Sample Application, Preparation} First we need to tell SPF/Pro the location of our application procedures, panels and data. Press F4(RETURN) to go to the Primary Options Panel. Select Option 0. Option 0 offers a number of parameter categories which can be altered. The one we want is Option 8 - Paths. Type 8 and press [SPF-Enter] or just click the button labeled 8. Option 0.8 shows you the current path settings for Profiles, Procedures, Panels and Programs. We need to insert our test directory in front of the normal search paths. Get into INSERT mode to preserve the existing values. Modify the first three paths as follows: GENERAL PROFILE, TABLE, SKELETON AND KEYBOARD SEARCH PATH CUSTOM ===> C:\SPFPRO\SAMPLES;...existing values moved over... MACRO AND COMMAND PROCEDURE SEARCH PATH CUSTOM ===> C:\SPFPRO\SAMPLES;...existing values moved over... PANEL AND MESSAGE SEARCH PATH CUSTOM ===> C:\SPFPRO\SAMPLES;...existing values moved over... Note: When we finish the exercise we need to reset these paths to their original values. Press F4(RETURN) again to return to the Primary Option Panel, we are ready to start. # 30.1.6 {Sample Application, the Panel} Our sample application is an appointment diary so first of all we should plan the look of the panel we are going to use. It needs to have two parts. One part to control the application and one to display the appointments in some specified order. Below is a suggested layout, which is found in the SAMPLES directory provided with SPF/Pro. You may, of course, modify this to suit your own ideas on design and layout. Indeed one of the best advantages of developing applications in SPF/Pro is the ability to alter the look of the application without altering the underlying code. ------------------------Sample Appointment Diary------------------------------ COMMAND ===># SCROLL===>#CSR Today Date: {26 January 1996} Time: {13:11} Appointment Details Date: #1996-01-29# Time: #14:00# Subject: #Product Release Schedule # Location:#Conference Room A, HQ Building, Alameda # [Add ][Update ][Delete ][Next ][Previous] Appointment List SD[Date ][Time ][Subject ][Location ] # #{1996-01-30}{09:00}{Marketing Review }{Marketing } #S#{1996-01-29}{14:00}{Product Release Schedule }{Conference Room A,} # #{1996-01-26}{14:00}{Manual Read Through }{Conference Room A,} #D#{1996-01-26}{10:00}{Collect Manuals from Printer }{ } # #{1996-01-25}{10:00}{Send media out for reproduction }{Media Center } ---------------------------BOTTOM OF DATA------------------------------------- In the sample above we have shown how the panel may appear. The special characters indicate the type of field we are suggesting: * [...] square brackets represent buttons * #...# pound signs represent input fields * {...} braces represent output fields * Static text is shown "asis" Panel definition using the SPF/Pro Panel Definition Language is achieved by 'painting' fields into a file with the SPF/Pro editor. Panel definitions are comprised of eight sections. These sections in the order they usually appear are: )ATTR )BODY )MODEL )INIT )REINIT )PNTS )PROC )END Each of these has a special purpose which we describe briefly here. A full explanation can be found in the chapter on Panel Definition later in this manual. If you would like to type this panel in as we are describing it, select your working directory in the editor. Edit new file SAMPLE.PAN. Type all the panel definition statements we provide. Alternatively you can obtain the completed sample panel in the SAMPLES directory. # 30.1.6.1 {Attributes} The )ATTR section describes the types of data that can appear on the panel. In our example we have four types of data: buttons input fields output fields fixed text In our sample application, we define these as follows: )ATTR '[' TYPE(PS) '#' TYPE(INPUT) INTENS(LOW) SCROLL(ON) '{' TYPE(OUTPUT) INTENS(LOW) '+' TYPE(TEXT) INTENS(LOW) The character enclosed in single quotes is the attribute which takes up one position on the panel and indicates the field type that follows. The TYPE defines the data type: PS 'Point and Shoot', is used to specify buttons. INPUT Is used to specify a field where data may be entered. OUTPUT Is used to specify a field which displays the content of a variable and is not modifiable. TEXT Is used to specify static text, the boilerplate of your panel. You can also specify INTENS(LOW) for normal intensity, or INTENS(HIGH) to give a field increased visual impact. In this example, the Subject and Location fields are of variable length. SCROLL(ON) allows characters to be entered beyond the field width. If the field width is fixed, specify SCROLL(OFF) instead. For example: '_' TYPE(INPUT) INTENS(LOW) SCROLL(OFF) If we wish to have text in two intensities, we have to have two attributes defined. '+' TYPE(TEXT) INTENS(LOW) '%' TYPE(TEXT) INTENS(HIGH) # 30.1.6.2 {Panel Layout} The )BODY section is where the fixed header portion of the panel is encoded. This is achieved by placing the attribute character at the beginning of each field and typing either fixed text, a button, or the name of and input or output variable. A special feature called expansion allows characters to be repeated without having to type them in individually. This is achieved by placing the character to be repeated between forward slash characters as you can see in line 2 of the example below: )BODY +/-/%Sample Appointment Diary+/-/ %COMMAND ===>#ZCMD/ /%SCROLL ===>#z + +Today Date: {smpdate/ /+ + Time: {smptime/ /+ + +Appointment Details + Date: _smpaptdt + + Time: _z + + Subject: #smpaptsb/ /+ + Location:#smpaptlc/ /+ + +[Add [Update [Delete [Next [Previous+ + +Appointment List +SD[Date [Time [Subject [Location + Lets analyze the )BODY section piece by piece. On the first line we see a '+' attribute which is defined as TYPE(TEXT) INTENS(LOW). This attribute applies to the characters generated by the expansion(/-/). The title itself is preceded by a '%' attribute which is set to TYPE(TEXT) INTENS(HIGH). Finally the line reverts to TYPE(TEXT) INTENS(LOW) for the second expansion to the right of the title. The two expansions, one on either side of the title, have the effect of centering the title in the available display space. Traditionally the second line on a SPF/Pro panel is the Command Line. All SPF/Pro panels follow this convention. This is where you type commands. The line itself shows some interesting features of panel definition. The prompt 'COMMAND ===>', another convention, is high intensity text ('%' attribute). The next part describes an input field. Notice the '#' attribute which we mapped to TYPE(INPUT) INTENS(LOW) SCROLL(ON). Whatever you type here is placed in the variable ZCMD which is the name which follows the '#' attribute. ZCMD is one of several special variables reserved by SPF/Pro. At the end of the command line we find the SCROLL field. Panels which display tables are frequently deeper than the display area and thus need vertical scrolling capability. The scroll field lets you set the mode for scrolling. The SCROLL field takes values from the set PAGE, HALF, CSR, and DATA. Its natural width is four characters corresponding to the longest of the values in the set. This presents a problem. If we use the variable name SCROLL to specify the field, it will be six characters wide. SPF/Pro provides a special set of variables called ZVARs. ZVARs only take one character space so you can use them any time a field's natural width is wider than the name you would normally assign. All ZVARs are specified as the character "Z". We will explain how the different "Z"s in the panel definition get sorted out when we describe the )INIT section. The third and fourth lines show output fields. These fields use the '{' attribute described as TYPE(OUTPUT) INTENS(LOW). A good convention to follow when naming variables is to use the same two or three character prefix followed by some term meaningful to your application. Variable names are limited to eight characters. In our example, fields SMPDATE and SMPTIME use the SMP prefix and the meaningful terms DATE and TIME. These fields are also variables in our REXX program. Warning: Do not start your variable names with the letter "Z"; this letter is reserved for system variables. In the case where a field needs to be wider than its variable name, the end is determined by the position of the next attribute character or, if no attribute character is on the line, the length of the variable name. Here are some examples of input field specification where the lengths of the names and the widths of the fields vary: +SSN: _ssn + field wider than name "ssn" +Month: _Z + field narrower than name "month" +Year: _year+ field same width as name "year" +Name: _name/ /+ field wider than "name" (full panel width) The fifth line is a blank line but it too must have an attribute to define it; a '+' is used to define a line of all blanks, TYPE(TEXT). Input fields are defined on lines seven through ten. We can see that input field is given a fixed text label and is then introduced with a '_' or '{' attribute. These attributes were defined earlier as TYPE(INPUT) INTENS(LOW) SCROLL(ON) and TYPE(INPUT) INTENS(LOW) SCROLL(OFF) respectively. The first two fields, Date and Time, have the SCROLL(OFF) attribute because we know that the date is in 9999-99-99 format and the time is 99:99 format. For this reason we have set a 'stopper' attribute exactly 10 and 5 characters after the input attributes. The Time input field at width 5 will not accomodate the var name SMPAPTTM so we use a ZVAR. The next two fields, Subject and Location, are of indeterminate length. We have therefore given them the '#' SCROLL(ON) attribute and sent, with expansion, the 'stopper' attribute to the righthand edge of the panel. Buttons are defined on lines twelve and fifteen using the '[' attribute which was assigned to the TYPE(PS) or 'point and shoot'. Type PS is a special type which, when the panel is displayed, renders the text as a three dimensional button. This button, when depressed, causes the )PNTS section to be invoked. The )PNTS section contains processing information related to all PS buttons. For example, when the button labeled "Add" is pressed we need to communicate this to the application's REXX procedure. The end of a button is defined by the next attribute. By default the label on buttons is centered even though it is typed flush left in the field definition. # 30.1.6.3 {Table Layout} The )MODEL section is where we define one instance of the line (or lines) which will display the contents of a single row of a specific table. The number of rows displayed depends on the display depth and font. The definition of this part of the panel follows the same rules as those for the )BODY statement. We do not have to specify the 'BOTTOM OF DATA' line as this is generated automatically by SPF/Pro. Vertical scroll bar and elevators to move up and down the table are also provided automatically. Our )MODEL statement looks like this: )MODEL _z+{smplnedt {z {smplnesb {smplnelc + The first and third variables are 'ZVARS'. Their names are really SEL, another SPF/Pro convention, and SMPLNETM. We will see how these names are assigned to ZVARs in the description for the )INIT section. It is possible that the data in a single table row can not be displayed in one screen line with a nominal width of 80 characters. In this case the )MODEL section may have more than one line in its definition. Each model line contains the names of the table fields which are to be displayed in that line. A maximum of eight lines are allowed in the )MODEL section. # 30.1.6.4 {Panel Processing} The )INIT, )REINIT, )PNTS, and )PROC sections of the panel may contain panel program code (primarily control flow and assignment statements). In many cases, panel code can implement the entire behavior of the panel with no support from external REXX procedures or other HLL programs. The )INIT section allows us to set initial values into panel variables when the panel is displayed for the first time. It also is where we define names corresponding to ZVARS. The )INIT for our application simply defines the 'ZVARS'. )INIT .ZVARS = "SCROLL, SMPAPTTM, SEL, SMPLNETM" At last we can see how the "Z" characters in the )BODY section are tied to real variables. Reading the )BODY section from left to right, top to bottom, as each "Z" is processed, it is bound to the next defined ZVAR. Thus on our panel, the first "Z" binds to SCROLL, the second to SMPAPTTM, the third to SEL, and the fourth to SMPLNETM. The )REINIT section is used in a similar way to )INIT in that it re-initializes the variables in the panel after the initial display. For example, you might want to re-initialize any input fields that were modified but not commited on the last display cycle. In our example we do not need to use the )REINIT section. # 30.1.6.5 {Handling Buttons} The )PNTS section is where we define the behavior of the buttons. The buttons on this panel are all TYPE(PS). The reference part of this manual shows how other button definitions can be made. SPF/Pro assigns a system generated name to each button (much like ZVARS). Reading the )BODY section from left to right, top to bottom, as each PS field is processed, it is bound to the next available PS field name. PS field names have the form "ZPSxxnnn" where: * "ZPS" stands for a system generated "Z" variable of the Point and Shoot variety. * "xx" is reserved for future use and is always set to 00. * "nnn" is an integer number corresponding to the ordinal position of the PS field. Thus the first PS field is given the name ZPS00001, the second ZPS00002, the third ZPS00003, etc. In our example, ADD is bound to ZPS00001, UPDATE to ZPS00002, DELETE to ZPS00003, NEXT to ZPS00004, and PREVIOUS to ZPS00005. We want to translate a button press into a command for our program to process. Our example program processes the contents of the system variable called ZCMD which we have defined on the command line. The )PNTS section automatically assigns a value to PS variable when a button is pressed. Our )PNTS section looks like this: )PNTS FIELD(ZPS00001) VAR(ZCMD) VAL(DIARY ADD) FIELD(ZPS00002) VAR(ZCMD) VAL(DIARY UPDATE) FIELD(ZPS00003) VAR(ZCMD) VAL(DIARY DELETE) FIELD(ZPS00004) VAR(ZCMD) VAL(DIARY NEXT) FIELD(ZPS00005) VAR(ZCMD) VAL(DIARY PREVIOUS) FIELD(ZPS00006) VAR(ZCMD) VAL(DIARY SORT DATE) FIELD(ZPS00007) VAR(ZCMD) VAL(DIARY SORT TIME) FIELD(ZPS00008) VAR(ZCMD) VAL(DIARY SORT SUBJECT) FIELD(ZPS00009) VAR(ZCMD) VAL(DIARY SORT LOCATION) When a button is pressed control passes from the panel to the )PNTS section. The ZPS field statement corresponding to the button which was pressed is processed. The value specified in VAL() is placed in the variable specified by VAR(). Thus if ADD were pressed, the value "DIARY ADD" would be set into ZCMD and would subsequently be accessible to our application code. (This is analogous to typing "DIARY ADD" in the command field and pressing [SPF-Enter].) Validating the panel The )PROC section gets control when one of the following events occurs: * [SPF-Enter] is pressed * A program function key is pressed (e.g. F5) * A PS button is clicked on (gets control after )PNTS section) * An attention field is clicked on In our example, we are primarily concerned with validating the contents of various input fields when specific actions are requested via PS field activation. We have to think about the validation process carefully. Do we wish to validate the panel if the user presses 'Next' or 'Previous' buttons, or if the user wishes to terminate the application by pressing END or RETURN? Lets look at the )PROC section to discover how the validation is implemented. )PROC VER(&SEL, LIST, 'S', 'D') IF (&ZCMD = 'DIARY ADD', 'DIARY UPDATE') VER(&SMPAPTDT, NB, PICT, 'NNNN-NN-NN') VER(&SMPAPTTM, NB, PICT, 'NN:NN') VER(&SMPAPTSB, NB) VER(&SMPAPTLC, NB) The 'VER' statement is used to 'Verify' the contents of a variable on the panel. Variables are identified by the ampersand(&) character which is placed ahead of the variable name. 'List' specifies that the variable's contents must be one of the values in the list which follows (or a blank). The first VER specifies that SEL, an input field on the left side of the entries in the appointment list, can be either 'S', 'D' or blank. We use the SEL field contents later to Select or Delete lines from the appointment list. Next we see an 'IF' statement indicating that the condition which follows has to be TRUE for the indented statements to be executed. The statements must all have the same indentation. The comma between the values means logical 'OR'. Therefore this statement says: if ZCMD is 'Diary Add' or 'Diary Update' (which means the 'Add' or 'Update' button was pressed) continue with the validation. The next four 'VER' statements all use the 'NB' option which means "verify that the field is not blank". The 'PICT' option specifies that the data entered into the field must conform "picture" string specification which follows. 'NNNN-NN-NN' says that the input must be comprised of four digits, followed by a hyphen, followed by two digits, followed by a hyphen, followed by two more digits. The 'N' represents any numeric digit. Other picture characters are C (any character), A (any alphabetic character) and X (any hexadecimal digit). Completing the panel The )END section ends the panel. It is the final line of the panel definition. Any lines which follow the )END section are ignored. Many users place information about the author, the application, and the panel design after the )END section. # 30.1.7 {Sample Application, Testing the Panel} SPF/Pro provides two ways of testing our panel without writing any code. These can be found in Option 7 (Dialog Test): * Option 7.1 launches a panel via SELECT service. This sets up a new function pool for variables and also invokes the SELECT service recursively on the ZSEL content after [SPF-Enter] processing on the panel under test. * Option 7.2 launches a panel via DISPLAY service. The function pool is unchanged. The ZSEL var is ignored. Let's now go to option 7.2, as we have a 'Display' panel. Enter the name 'SAMPLE' in the PANEL field, then press [SPF-Enter]. We should see our panel displayed. When the panel is displayed we can test the behavior and functions of the panel by pressing the buttons and seeing if our validation works as intended. # 30.1.8 {Sample Application, the REXX Procedure} We divide the development of the REXX procedure into incremental stages. Each of these self-contained and functional procedures can be found in the SAMPLES directory of SPF/Pro called SAMPLE_1.ISP through SAMPLE_9.ISP. Each one can be tested by entering its name on panel 7.1 in the PROCEDURE field and pressing [SPF-Enter]. Part I - Displaying the panel. This example can be found in SAMPLE_1.ISP In this first part we learn how to write simple REXX and ISPEXEC commands to display the panel repeatedly and to exit when the user issues one of many termination signals, such as END, RETURN or 'Jump' Detection of termination signals is handled by SPF/Pro and communicated to our REXX procedure via special variable RC (return code). A value of zero in RC means that the user pressed [SPF-Enter] and wants us to process the data on the panel. Any other value indicates a termination request. Here is our first REXX procedure: 000100 /* REXX PROCEDURE */ 000200 /* SAMPLE version 1 */ 000300 address ispexec 000400 ZCMD = '' 000500 'display panel(sample)' 000600 do while rc = 0 /* until termination request from user */ 000700 'display panel(sample)' 000800 end /* do while */ 000900 return As you can see it is relatively simple. Lets look at it line by line. We have numbered the lines for ease of reference. All REXX procedures must begin with a comment. Comments in REXX begin with '/*' and end with '*/'. Comments can appear anywhere in the procedure. The initial comment in a REXX procedure on the mainframe must contain the the word 'REXX' as the first word. In SPF/Pro this is not required. For example, /* This is a REXX comment */ Line 300 shows how we tell the REXX command processor to deal with commands it does not recognize. The ADDRESS identifies an environment outside REXX which is to receive any unrecognized commands. On this occasion that environment is ISPEXEC. ISPEXEC is the SPF/Pro execution environment. Now, when REXX finds commands enclosed in single or double quotes it passes them to the ISPEXEC environment for processing. Line 400 shows how we initialize variables that are visible to the panel. This can also be done in the )INIT section of the panel. In the example we are setting ZCMD to a null value. We do this to ensure that only values set in our panel are considered for processing. Line 500 is an example of an external command (so named because the command is external to REXX) to be processed by ISPEXEC. This command displays the panel and then suspends the REXX procedure until the user presses an attention key. We could have written the command as 'ISPEXEC DISPLAY PANEL(SAMPLE)' which is also passed to ISPEXEC. Because most REXX procedures have some interaction with the ISPEXEC command processor the use of the ADDRESS ISPEXEC command (see line 300) saves us having to explicitly write ISPEXEC on each such command. Line 600 is one of the most common constructs in REXX for controlling repeated processes. DO WHILE condition says that the following code, up to a matching END statement (line 800) should be repeatedly as long as the specified condition holds true. In the sample code we are testing RC to determine if the user has pressed END, RETURN or 'Jump'. Line 700 redisplays the panel. On the second through Nth invokation the )REINIT section is given control. This is true as long as the same panel is repeatedly displayed with no intervening change of panel ID. It is also possible to write line 700 as DISPLAY with no PANEL specified. This shorthand technique simply re-displays the current panel. Line 800 is the end of scope for the DO WHILE at line 600. Commands between the DO WHILE and END are indented to aid the programmer's understanding of the behavior of the code. This style of indenting is recommended but not required. In REXX all DO initiated code blocks are terminated with an END instruction. It can be difficult to match an END with its corresponding DO, IF, or SELECT. A good habit to adopt is to add a comment to indicate what is being ended. For example, do while ... - - - end /* while */ Line 900 is the end of the procedure. The RETURN statement in our example is unnecessary. We include it to show how a REXX procedure may be terminated when two or more procedures are coded in a single source module. The other case where it is needed is when an explicit RESULT is set by the called procedure. For example, /* REXX first proc */ - call foo - return /* second proc */ foo: - call foobar - return /* third proc */ foobar: - - - return # 30.2 {Building and Displaying the Appointment List} This example can be found in SAMPLE_2.ISP. To build the appointment list we need to make use of 'Tables'. Tables are a special kind of container comprised of one or more rows of like data. Each row is comprised of fields which correspond to variables in your REXX procedure. When you put a row in the table, your REXX vars corresponding to that row are put into the table. When you get a row from the table, the same REXX vars are loaded from the table row contents. Tables are maintained in memory and may also be recorded on hard disk. Tables are created, modified, and accessed via ISPEXEC commands. The table we are going to create has four fields, each one corresponds to the fields in the )MODEL statement and for ease of use we give them the same names as those in the )MODEL statement. Also we must consider the nature of the data. It is unlikely that you will need two entries in the appointment diary for the same date and time so we can use the default behavior of tables to prohibit this. We must also consider that the very first time the appointment diary is used, no diary exists, so we must create one with a dummy entry to show how it might be used. In the next code fragment we see the initial creation of the table, or if it exists already, the opening of the table. 000100 /* REXX PROCEDURE */ 000200 /* SAMPLE version 2 */ 000300 address ispexec 000305 smpdate = date('s') /* format YYYYMMDD */ 000310 smpdate = substr(smpdate,1,4)||'-'||, 000315 substr(smpdate,5,2)||'-'||, 000320 substr(smpdate,7,2) 000325 smptime = time('n') /* format HH:MM:SS */ 000330 smptime = substr(smptime,1,5) 000400 ZCMD = '' 000405 'tbopen diary share' 000410 if rc <> 0 then /* diary does not exist so create it */ 000415 do 000420 'tbcreate diary keys(smplnedt, smplnetm) names(smplnesb, smplnelc)' 000425 if rc <> 0 then /* it cannot be created */ 000430 do 000435 zedsmsg = 'Diary could not be created' 000440 'ispexec setmsg msg(isrz001)' /* display error message */ 000445 return 99 000450 end 000455 /* end if */ 000460 smplnedt = smpdate 000465 smplnetm = smptime 000470 smplnesb = 'Diary created automatically' 000475 smplnelc = '' 000475 'tbadd diary' /* add starting entry */ 000480 end 000485 /* end if */ 000500 'tbdispl diary panel(sample)' /* display diary in table form */ 000600 do while rc = 0 /* until termination request from user */ 000700 'tbdispl diary panel(sample)' 000800 end /* do while */ 000805 'tbclose diary' 000900 return In this code we have extended the behavior to get today's date and time, to create (or open) the existing diary and to display the diary as a table. Lets look at this in detail. Lines 305 to 330 are involved with getting today's date and time and formatting them according to our date and time notation scheme. On line 305 and 325 we see the use REXX built-in functions DATE() and TIME(). These functions provide the date and time in a variety of formats. DATE('S') generates YYYYMMDD and TIME('N') generates HH:MM:SS. These values are assigned to the variables SMPDATE and SMPTIME respectively. Neither of the returned values is exactly what we want so we use the SUBSTR function to separate the data into the parts we require. We need to break the date into three parts and insert a hyphen in between the parts. The double vertical bar(||) means concatenation of the strings on either side. The hyphen(-) is literal text. Text strings in REXX are enclosed in single or double quotes. SUBSTR(SMPTIME,1,5) extracts characters 1 through 5 (the HH:MM portion). Now that we have resolved the values for SMPDATE and SMPTIME they appear on the panel. Line 405 is where we open the table. All table oriented ISPEXEC commands begin with 'TB', hence 'TBOPEN'. In the example, we try to open the DIARY table (DIARY.TBF file) which is located on the ZPRFPATH. The .TBF extension is the only extension supported by SPF/Pro for tables. If open fails, a non-zero return code is displayed. Notice that the option SHARE has been specified. This allows you to have the diary open in several sessions of SPF/Pro simultaneously. Line 410 shows an example of an IF statement. The condition is testing for the return code, RC, being not equal(<>) to zero. The THEN which follows the conditional expression is required. If the condition is true, control flows to line 415. Line 415 is a DO block which encloses multiple statements to be performed from the True/False branches of the IF statement. The DO is terminated by the END on line 480. If only a single statement is needed for a True or False clause, the DO/END pair is not needed. Line 420 is where we create the table if it does not exist (TBCREATE). The parameter KEYS() specifies the names of the key fields within the table. Key fields may not have duplicate entries in a table. Fields SMPLNEDT and SMPLNETM have been specified as keys to guarantee no appointments of the same time and date are possible. SPF/Pro controls this automatically. The next option NAMES() specifies what other, non-key, fields are to be in the table, these are SMPLNESB (subject), and SMPLNELC (location). Line 425 tests the Return Code again to ensure that the create was successful. If it is not, a serious error has occured. Lines 435 to 445 show how we display error messages on the top right hand corner of the panel. This area is knows as the "short message" field. We achieve this by setting the Short Message variable ZEDSMSG to the error message. We then invoke ISPEXEC SETMSG which queues the message for display on the next panel. The RETURN 99 returns control to the application that invoked our application and sets special return code field RESULT to 99. Lines 460 to 475 are only executed if the table creates successfully. Here we give initial values to the table's fields. Note that SMPLNELC is being given a null value. Line 475 adds the data held in the four table variables to the table. This is the first row in the table. Lines 500 and 700 display the table via the TBDISPL command. TBDISPL displays the fixed portion of the panel body, reads rows from the table, and displays them according to the specifications in the )MODEL section. # 30.2.1 {Adding Appointments} This example can be found in SAMPLE_3.ISP. To add appointments, we have to capture the data entered by the user on the panel and add it to the table as we added the 'Diary created' entry in the example above. In order maintain clarity, only new or modified portions of code are shown (the complete code can be found in SAMPLE_3.ISP in the SAMPLES directory). As we add more functionality to the program the overall design will be easier to understand. Here is the code to enable new appointments to be added. 000100 /* REXX PROCEDURE */ 000200 /* SAMPLE version 3 */ ... 000500 'tbdispl diary panel(sample)' /* display diary in table form */ 000600 do while rc = 0 /* until termination request from user */ 000601 ZCMD = translate(ZCMD) 000602 select /* what does ZCMD contain? */ 000603 when ZCMD = 'DIARY ADD' then /* insert a new entry in the diary */ 000604 do 000605 smplnedt = smpaptdt 000606 smplnetm = smpapttm 000607 smplnesb = smpaptsb 000608 smplnelc = smpaptlc 000609 'tbadd diary' 000610 select /* what was the return code */ 000611 when rc = 0 then /* successful add */ 000612 do 000613 zedsmsg = 'Added' 000614 'ispexec setmsg msg(isrz000)' 000615 end 000616 when rc = 8 then /* duplicate key */ 000617 do 000618 zedsmsg = 'Duplicate' 000619 'ispexec setmsg msg(isrz001)' /* display error message */ 000620 end 000621 otherwise /* other error */ 000622 do 000623 zedsmsg = 'Error '||rc 000624 'ispexec setmsg msg(isrz001)' /* display error message */ 000625 end 000626 end /* select */ 000627 end 000628 otherwise /* some other ZCMD values */ 000629 nop /* no operation for now */ 000630 end /* select ZCMD values */ 000700 'tbdispl diary panel(sample)' ... 000900 return This code fragment acts as a shell for the other options as we enhance our sample application. Line 601 ensures that all incomming commands are uppercase. All the remaining code is related to handling the addition of another row to the table. Lines 605 to 608 move the panel input fields to the table row fields. Line 609 attempts to add the row to the table. There are three possible outcomes. Either the row inserts correctly, RC=0, the row being added has duplicate date and time information, RC=8 or some other event. # 30.2.2 {Updating, Fetching and Deleting Appointments} The complete code can be found in SAMPLE_4.ISP. Using the previous example as a model we can now add the code for Fetching a particular appointment (forward or backward), Updating or Deleting it. Get the next diary entry ... when ZCMD = 'DIARY NEXT' then /* get next appointment */ do /* sort into date order */ 'tbsort diary fields(smplnedt,c,a,smplnetm,c,a)' 'tbtop diary' smplnedt = smpaptdt smplnetm = smpapttm smplnesb = smpaptsb smplnelc = smpaptlc 'tbget diary' /* get the next appointment after the one shown */ 'tbskip diary number(+1)' select /* what was the return code */ when rc = 0 then /* found one */ do smpaptdt = smplnedt smpapttm = smplnetm smpaptsb = smplnesb smpaptlc = smplnelc end when rc = 8 then /* not found */ do zedsmsg = 'None found' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ end end /* select */ end Get the previous entry ... when ZCMD = 'DIARY PREVIOUS' then /* get prev appointment */ do /* sort into date order */ 'tbsort diary fields(smplnedt,c,a,smplnetm,c,a)' 'tbtop diary' smplnedt = smpaptdt smplnetm = smpapttm smplnesb = smpaptsb smplnelc = smpaptlc 'tbget diary' /* get the next appointment before the one shown */ 'tbskip diary number(-1)' select /* what was the return code */ when rc = 0 then /* found one */ do smpaptdt = smplnedt smpapttm = smplnetm smpaptsb = smplnesb smpaptlc = smplnelc end when rc = 8 then /* not found */ do zedsmsg = 'None found' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ end end /* select */ end Update the current diary entry ... when ZCMD = 'DIARY UPDATE' then /* update the current entry */ do smplnedt = smpaptdt smplnetm = smpapttm 'tbget diary' select /* what was the return code */ when rc = 0 then /* got */ do smplnedt = smpaptdt smplnetm = smpapttm smplnesb = smpaptsb smplnelc = smpaptlc 'tbmod diary rowid(crp)' select /* what was the return code */ when rc = 0 then /* updated */ do zedsmsg = 'Updated' 'ispexec setmsg msg(isrz000)' end when rc = 8 then /* not found so added */ do zedsmsg = 'None found - entry added' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ 'tbskip diary row(crp)' end end /* select */ end when rc = 8 then /* not found */ do zedsmsg = 'None found' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ end end /* select */ end Delete the current diary entry ... when ZCMD = 'DIARY DELETE' then /* delete the current entry */ do smplnedt = smpaptdt smplnetm = smpapttm 'tbget diary' select /* what was the return code */ when rc = 0 then /* got */ do smplnedt = smpaptdt smplnetm = smpapttm smplnesb = smpaptsb smplnelc = smpaptlc 'tbdelete diary' select /* what was the return code */ when rc = 0 then /* delete */ do zedsmsg = 'Deleted' 'ispexec setmsg msg(isrz000)' 'tbskip diary row(crp)' end when rc = 8 then /* not found so added */ do zedsmsg = 'None found' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ end end /* select */ end when rc = 8 then /* not found */ do zedsmsg = 'None found' 'ispexec setmsg msg(isrz001)' /* display error message */ end otherwise /* other error */ do zedsmsg = 'Error '||rc 'ispexec setmsg msg(isrz001)' /* display error message */ end end /* select */ end Close analysis of these code fragments shows that they are remarkably similar in organization with just subtle changes to the facilities used varying the behavior. Here is a summary of the features introduced in the code fragments above. * TBDELETE - delete the current row from the table. * TBGET - get the row whose date and time details match those in the key fields. * TBMOD - modify the current row with new values. * TBSKIP - skip the number of rows specified by the NUMBER parameter. * TBSORT - sort the table according to the details in the FIELD parameter. * TBTOP - position the table at the top. # 30.2.3 {Sorting the Appointment List} The complete code can be found in SAMPLE_5.ISP. Sorting the table is easily achieved. We first detect which sort request has been issued and then we sort according to that criterium. We make use of the TBSORT command which takes three options for each sort field, * name of field * type of field * sort direction (Ascending or Descending) Here is one example of the sort code syntax. when ZCMD = 'DIARY SORT DATE' then /* sort date descending */ do 'tbsort diary fields(smplnedt,c,d,smplnetm,c,d)' 'tbtop diary' end Note that sorting for date also sorts for time within date. # 30.2.4 {Allowing the User to Select from the Table} The complete code can be found in SAMPLE_6.ISP. On the panel there is an entry field alongside each of the entries in the appointment list. This field is used to directly select an individual appointment rather than use the 'Next' or 'Previous' buttons which appear on the panel. Processing the list introduces us to two new variables. ZTDSELS contains the number of rows of the table which have been selected. ZMARKED indicates if the row has been marked ('Selected') by the mouse. When control is returned to the application, the position in the table is automatically set to the first row which has been selected (by placing an 'S' in the input field on the left side of the entry) or the first row which has been marked (by clicking on the row with the mouse). Each subsequently selected or marked row is automatically positioned in the table each time the TBDISPL command is issued without the PANEL() option being specified. This action also decrements the value in ZTDSELS until it is zero. It would be a nice feature to add a popup menu which lists the options available in the header and the appointment list. Two special variables, POPUP and POPUPTB, can be set in our program. SPF/Pro uses them to generate popup menus. These variables are set to a string value comprised of pairs of verbs followed by commands separated by vertical bars. The first of the pair is the label to appear on the popup menu. The second, the command to be issued if that option is selected. Lets look at an example: POPUP = 'Add|DIARY ADD|Update|DIARY UPDATE|Delete|DIARY DELETE' POPUPTB = 'Show appointment|:S|Delete appointment|:D' Note how on POPUPTB the commands are prefixed with a colon. This is to specify that they are LINE commands. If the colon is omitted, they become PRIMARY commands (in other words they populate ZCMD). The following code supports line selection and deletion. Our example code is designed to allow the user to type one 'S' or multiple 'D' commands. /* REXX PROCEDURE */ /* SAMPLE version 6 */ ... 'tbdispl diary panel(sample)' /* display diary in table form */ do while rc = 0 /* until termination request from user */ ... when ztdsels = 1 & (translate(sel) = 'S' | zmarked = 'Y') then do smpaptdt = smplnedt smpapttm = smplnetm smpaptsb = smplnesb smpaptlc = smplnelc end when ztdsels > 0 then do while ztdsels > 0 if translate(sel) = 'D' then /* ignore any 'S' after the 'D' */ do 'tbdelete diary' end /* end if */ 'tbdispl diary' /* locate next selected row */ end /* do while */ 'tbdispl diary panel(sample)' ... # 30.2.5 {Sample Application, Adding Application to Samples Menu} We want to be able to invoke our application other than through the Dialog Test Option 7.1. We need to add the application to a place where the user can readily locate it. We are going to add the application to the Samples Menu which is accessed via Option A, Applications, on the Primary Options Panel. Go to the Primary Options Panel and select Option A, then select Option 5. This displays the current settings for the Samples Menu. We are going to add the Diary Application as Option 7 to this list. First we need to know which panel (of many) this is. Enter primary command PANELID. Look at the top left hand corner of the panel. You should see S2DSAMPL. The file name of the panel is S2DSAMPL.PAN and it is stored in one of our PDS files. PDS's, as we discussed earlier, are files with sub-files, or members, within them. S2DSAMPL.PAN is a member of SPFPRO.PDS. Invoke the editor. Specify the directory where SPF/Pro is installed. In sub-directory PAN, find SPFPRO.PDS. Select this file to display the member list. Scroll down this list until you find S2DSAMPL.PAN. S2DSAMPL.PAN conforms to the same rules as the panel we created for our application. We need to add our application to the )BODY section in the form of a select button and to the )PROC section to set the correct ZSEL value when the button is pressed. This is the relevant part of S2DSAMPL.PAN's )BODY section. +^ 5 %HOME RUN +- Patience game demonstrating Animations and Buttons +^ 6 %C PHONES +- Phone program By reading the )ATTR section we can see that the developer of this panel intends the circumflex (hat) to represent buttons. ATTN(ON) is similar to TYPE(PS) but in this case the actual content of the button becomes the string passed into ZCMD. With addition of our code the new )BODY section looks like this: +^ 5 %HOME RUN +- Patience game demonstrating Animations and Buttons +^ 6 %C PHONES +- Phone program +^ 7 %DIARY +- Review, update your appointment diary Next we need to add the appropriate code to the )PROC section. In the current )PROC section we can see that the value of ZCMD is being translated into a command string and placed in the new ZVAR called ZSEL. ZSEL is the command field that is executed on Selection Panels (which are the SPF/Pro menus). 5, "CMD(HOME_RUN)" 6, "PGM(CPHONE)" "Press here", "CTC(S2DBROW) PARM(C:\SPFPRO\README.MAC)" becomes: 5, "CMD(HOME_RUN)" 6, "PGM(CPHONE)" 7, "CMD(SAMPLE)" "Press here", "CTC(S2DBROW) PARM(C:\SPFPRO\README.MAC)" Above are three examples of how applications can be launched from a panel. CMD() invokes the named REXX procedure and CTC() launches internal Command Technology routines. If we save our changes and return to the Primary Option Panel, we should be able to test our application. We could type A, then 5, then 7 to navigate through the menus or we could use the 'Jump' command by typing =A.5.7 to launch the application directly. # 30.2.6 {Sample Application, Making DIARY a Primary Command} We have enabled the user to invoke the appointment diary through the Applications menu. There are occasions when a user would want to invoke DIARY directly without loosing context. To do this we have to add DIARY to the SPF/Pro Primary Command Set. By doing this, it can be invoked directly via DIARY primary command from any panel. SPF/Pro has a feature called Command Tables. These tables allow the user to specify a simple command name which is then mapped to a more complex command string. Go to option 3.J, Command Tables; select SPFCMDS. This table contains the majority of SPF/Pro Primary Commands. To add our own command we press the NEW button. When the EDIT COMMAND BINDING panel appears we have four fields to enter. * VERB is our new command DIARY. * TRUNC is the shortest acceptable form of the command DIARY. For example, we might specify 2 to indicate that DI as a short form. If 0 is specified, no short forms are allowed. * ACTION is the command to be executed. Our action is 'SELECT CMD(SAMPLE)'. Using SELECT starts a separate session which ensures that values changed by SAMPLE do not interfere with the launching application. * DESCRIPTION is any narrative description. Press [SPF-Enter] and then END to save the new command. Now the DIARY primary command can be invoked from any panel. # 30.2.7 {Sample Application, the Edit Macro} We are now ready to design an edit macro which presents a skeleton report with headings pre-completed from the most recent appointment. We do this by obtaining the current date and time and finding the first entry in the table with an earlier date and time. The name of the macro is REPORT.SPF. The .SPF extension indicates that this is an SPF/Pro Edit Macro. The complete REPORT.SPF can be found in the SAMPLES directory. Edit macros use ISREDIT commands. These commands can be found in the section on ISREDIT later in the manual. Here is the macro. Lets analyze it. 000100 /* REXX MACRO */ 000200 /* Version 1 */ 000300 'isredit macro' 000400 'ispexec tbopen diary share' 000500 if rc <> 0 then 000600 do 000700 zedsmsg = 'No diary found' 000800 'ispexec setmsg msg(isrz001)' /* display error message */ 000900 return 001000 end 001100 /* end if */ 001200 today_date = date('s') 001300 today_time = time('n') 001400 today_date = substr(today_date,1,4)||'-'||, 001500 substr(today_date,5,2)||'-'||, 001600 substr(today_date,7,2) 001700 today_time = substr(today_time,1,5) 001800 'ispexec tbsort diary fields(smplnedt,c,a,smplnetm,c,a)' 001900 'ispexec tbtop diary' 002000 smplnedt = today_date 002100 smplnetm = today_time 002200 'ispexec tbscan diary arglist(smplnedt,smplnetm) condlist(ge,ge)' 002300 if rc <> 0 then 002400 do 002500 zedsmsg = 'No diary found' 002600 'ispexec setmsg msg(isrz001)' /* display error message */ 002700 return 002800 end 002900 /* end if */ 003000 'ispexec tbskip diary number(-1)' 003100 if rc <> 0 then 003200 do 003300 zedsmsg = 'No diary found' 003400 'ispexec setmsg msg(isrz001)' /* display error message */ 003500 return 003600 end 003700 /* end if */ 003800 'isredit line_after 0 = "3."' 003900 'isredit line_after 0 = "2."' 004000 'isredit line_after 0 = "1."' 004100 'isredit line_after 0 = "Notes:"' 004200 'isredit line_after 0 = "'||copies('-',80)'"' 004300 'isredit line_after 0 = "Present :"' 004400 'isredit line_after 0 = "Duration :"' 004500 'isredit line_after 0 = "Time :'smplnetm'"' 004600 'isredit line_after 0 = "Date :'smplnedt'"' 004700 'isredit line_after 0 = "Location :'smplnelc'"' 004800 'isredit line_after 0 = "Subject :'smplnesb'"' 004900 'isredit line_after 0 = "Meeting report 'today_date'"' 005000 'ispexec tbclose diary' 005100 return Line 300 is where we tell SPF/Pro that this an Edit Macro. It is essential that this line be present, otherwise all remaining ISREDIT commands will fail. Note how, instead of entering ADDRESS ISREDIT we have chosen to prefix all commands with either ISREDIT or ISPEXEC. This ensures we do not get the two sets of commands confused. Lines 400 to 3700 locate the most recent appointment, that is the one before the current date and time, using commands we have already discussed. The exception to this is the TBSCAN at line 2200. TBSCAN allows you to search the table for a near hit using the condition GE (greater than or equal). So using this we find the appointment just ahead of the current time and then step back one row. Lines 3800 to 4900 insert lines into the REPORT file in reverse order. We have to do this because a newly created file has no line numbers so we insert the lines after line 0. To execute this macro edit a new empty file, type 'REPORT' at the command line. You will get the following report. Meeting report 1996-01-01 Subject :Manual Read Through Location :Conference Room A Date :1996-01-26 Time :14:00 Duration : Present : -------------------------------------------------------------------------------- Notes: 1. 2. 3. # 31. {Panel Definition Language} As in mainframe ISPF, SPF/Pro supports modifiable panels. All SPF panels (mainframe or PC) proceed from the Primary Option Panel. There are two fundamental purposes for modifying panels: 1. The primary use of modifiable panels is to append functions to SPF/Pro which support whole new and distinct application areas. By adding options to the Primary Option Panel a whole tree of panels related to a user developed application become an extension to SPF/Pro. 2. Another use is to alter the default SPF/Pro panels to present things in a way that is more attractive to local use patterns. An example of this might be changing the Edit Entry Panel (2) to eliminate some of the optional fields which you decide are not applicable in your environment. Whenever modifying existing SPF/Pro panels it is important to keep a working copy of the panel in case your modifications do not work as expected. You can always re-install SPF/Pro but it is much easier to simply recall the working copy of the panel. # 31.1 {Panel Elements} SPF/Pro panels are stored in PDS's (see the chapter on Partitioned Data Sets) in SPFPRO\PAN or in files with a name in the following form: name.PAN All references to panels within panel definitions and verbs that apply to panels such as SELECT must be made with their panel ID (the file name without extension). For example, the primary option panel definition file is S2MPRIM.PAN. All references to this panel use panel-id S2MPRIM. SPF/Pro panels display and set variables. Later examples show how variables are specified as part of a panel definition and how the display vs. set issue is handled. When variables are set, they are accessible by the program (or REXX procedure) which displayed the panel. Specific actions may then be taken depending on variable settings to act on the intentions of the end user. # 31.2 {Variable Services} As previously stated all communication between panels, panel programs, and/or panel procedures is through dialog variables. Dialog variables are stored in pools. There are four variable pools: 1. FUNCTION POOL - a new function pool is created when an application is SELECTed. Variables in the function pool are visible to the program (or REXX procedure) which did the SELECT and to no others. 2. SHARED POOL - the shared pool contains variables which are accessible equally by all panels and panel procedures within a single SPF/Pro task. These variables are lost when you terminate the task. For example, each side of a SPLIT is a single task. Shared variables are created and altered by the VPUT variable service. The shared pool is created when a new task is started by a SELECT or by a SPLIT (including FSPLIT, and VSPLIT). 3. GLOBAL POOL - the global pool contains variables which are accessible equally by all panels and panel procedures in all SPF/Pro sessions. These variables are lost when you terminate the last session. Global variables can created and altered by the VPUT variable service. 4. PROFILE POOL - this variable pool contains variables which are accessible equally by all panels, panel procedures, and concurrent tasks. These variables are automatically recorded on disk and are persistent across SPF/Pro sessions even when you have powered off your machine. Profile variables are created and altered by the VPUT variable service. Because each type of variable pool maintains its own name space, it is possible to have like named variables in the different pools at the same time. When looking for a variable the pools are searched in the following order: 1. Function 2. Shared 3. Global 4. Profile If a variable exists, it is found first in the function pool, if not there, in the shared pool, if not there, in the global pool, and finally in the profile pool. Care should be taken when selecting variable names to avoid conflicts. A detailed discussion of individual variable services is presented in a later section. # 31.3 {Panel Display} Panels are displayed in response to one of: * SELECT - displays a panel, creates a new function pool. * DISPLAY - displays a panel without altering the function pool. * TBDISPL - displays a panel containing a table without altering the function pool. Panels may vary in size. Depending on the panel font, whether the panel is maximized or minimized, the screen resolution, and how you have customized your windows. Up to 132 columns, and up to 50 lines may be displayed. If the panel's width exceeds the display width, characters beyond the width are not displayed (are clipped). If the panel's depth exceeds the display depth, lines beyond the depth are not displayed (are clipped). SPF/Pro maintains variables which provide information on screen extents: ZSCRMAXD Contains the depth in lines of the display area. ZSCRMAXW Contains the width in characters of the display area. ZSCREEND Same as ZSCRMAXD. ZSCREENW Same as ZSCRMAXW. ZTSKMAXD Contains the depth in lines of the task display area. When the screen is split horizontally, the depth of the task display area is less than ZSCRMAXD. ZTSKMAXW Contains the width in characters of the task display area. When the screen is split vertically, the width of the task display area is less than ZSCRMAXW. These variables are dynamically updated by SPF/Pro as a result of [SPF-Enter] processing not at the time the panel is resized with a mouse. # 31.4 {Panel Sections} SPF/Pro panels consist of sections. Each section plays a specific role. Some sections are required and some are optional. Following is a description of each section: Attribute Optional - you specify attribute bytes in this section. Attribute bytes define the properties of labels and fields in a panel. Body Required - defines the visible portion of the panel as it will be seen on the display including variables (input or output) and button fields. Model Required for Tables - defines the display prototype for individual table rows. Table rows may contain large numbers of fields. If the number of fields (and their width) can not be displayed in a single display line, the table row may span multiple display lines. Initialization Optional - specifies the processing to be done prior to the panel being displayed for the first time. A typical use of this section is to set initial values in variables which are part of the panel definition. Reinitialization Optional - specifies processing to be done prior to re-displaying the panel. REINIT may be used in a similar manner to INIT to set variable values. Point and Shoot Optional - specifies the processing that is to be done after a named or unnamed button has been selected on the panel. Normally ZSEL or ZCMD is set to effect a SELECT or cause execution of a primary command. Processing Optional - specifies the processing that is to be done after the panel is displayed and the [SPF-Enter] key has been pressed. Typically you verify field content and/or translate field values. End Optional - indicates the end of the panel definition. All statements after the end section are treated as comments. The method of defining the respective sections is as follows: )ATTR ... attribute section statements ... )BODY ... body section statements ... )MODEL ... model section statements ... )INIT ... initialization section statements ... )REINIT ... reinitialization section statements ... )PNTS ... point and shoot section statements ... )PROC ... processing section statements ... )END Section headers must begin in column one. # 31.5 {General Syntax Rules} * In general the text components of panel definitions can be entered in mixed case (i.e. upper and/or lower case). All variable names are automatically translated to uppercase by panel processing. Variable values that are set within panel sections or entered into fields are left "as is" unless CAPS(ON) is specified in the attribute section. * Non-scrollable input fields are limited in length to the display width. * Scrollable input fields are limited to 1024 characters. * Section headers like ")ATTR" must start in column 1. # 31.6 {)ATTR Attribute Section} In most cases there is no need to modify panel attributes. This is because the default settings of the system or locally established defaults are appropriate for 95% of your panels. In any case, we describe how panel attributes are defined and how you can use them to solve special presentation and formatting problems. Attribute character definitions are specified one per line in the following form: attr-char attributes Generally the attribute character is chosen from the punctuation character set and is a character that is not likely to appear in the field labels or variable names in the panel definition. The default attribute character definition for SPF/Pro follows: )ATTR % TYPE(TEXT) INTENS(HIGH) + TYPE(TEXT) INTENS(LOW) _ TYPE(INPUT) INTENS(HIGH) SCROLL(OFF) CAPS(ON) $ TYPE(INPUT) INTENS(HIGH) SCROLL(ON) CAPS(OFF) ~ TYPE(INPUT) INTENS(LOW) SCROLL(OFF) CAPS(ON) You can override the characters chosen for each attribute by specifying the DEFAULT parameter on the attribute section header. The DEFAULT parameter is specified along with the characters you want to represent the various attributes in the order that they were defined. For example, if you want to change "%" to "!", leave "+" alone, and change "_" to "@", you would specify: )ATTR DEFAULT(!+@) In this example, the first character replaces the first attribute, the second character (same as original) replaces the second attribute, and finally, the third character replaces the third attribute. The fourth and fifth attribute are not affected. Attribute character definition options are described in the reference section at the end of this chapter. When specifying a variable with the INPUT attribute, the variable name must immediately follow the attribute character; do not specify the ampersand (&). For example, to specify an input field with the label "FIRST NAME" and input variable "FNAME" with a width of 8 characters: +FIRST NAME%===>_fname + Assuming we are using the default attributes we can break this down starting with the specification "text low" attribute character (+) followed by the label "FIRST NAME". Then we specify the "text high" attribute character (%) followed by the arrow. Finally we specify the "input" attribute character (_) followed by the variable "fname". We end the field eight bytes out with the "text low" attribute character (+). TEXT fields are literal; they display "as is". The static and variable components of a text field use whatever space they need. With scrollable input fields, the variable value may exceed the width of the field. In that case, only the number of characters that fit in the field are displayed. When multiple fields are specified on a single panel line, each label and each variable must be preceded by an attribute character. The following example shows a single panel line with multiple input fields: +NAME: + FIRST%===>_fname + MI%===>_m+ LAST%===>_lname + If the rightmost field on a given line is not terminated by an attribute character, it takes the full display width minus one character. OUTPUT fields display "as is". They are padded with blanks to the full width of the field. They are typically used in situations where you have multiple output fields on a single line with no intervening labels or attributes. The most common case of this occurs in tables. In tables where field values vary in length, they would not display in an orderly manner. By declaring the variables with the output attribute, their length is normalized. You can also apply CAPS and JUST attributes to output fields for further refinement. # 31.7 {)BODY Section} The body section defines how the panel looks to the user. With the exception of tables, all the elements of the definition are entered in exactly the order and position that they will appear on the display. (Tables are defined in the MODEL section.) In addition to the protocols related to the various sections, there are certain panel elements that are commonly specified on all panels. Following are two sets of typical body definitions: Statements commonly defined for non-scrollable menu panels: )BODY %&ZPRODTSK /-/ ... TITLE ... /-/ V &ZSHRTVER %OPTION ===>$ZCMD / /+ Statements commonly defined for non-scrollable text entry panels: )BODY %&ZPRODTSK /-/ ... TITLE ... /-/ V &ZSHRTVER %COMMAND ===>$ZCMD / /+ Statements common to table and edit/browse panel types: %&ZPRODTSK /-/ ... TITLE ... /-/ V &ZSHRTVER %COMMAND ===>$ZCMD / / %SCROLL ===>_Z % )INIT .ZVARS = 'SCROLL' The distinction between the prototype statements is that in the case of menus the primary command field is labeled "OPTION" while text entry panels are labeled "COMMAND". Further, menus and text entry panels have no "SCROLL" field. Now moving left to right through the example prototype let's look at some of the elements: % - 1st line starts with intense TEXT attribute &ZPRODTSK - variable, product name and task ID /-/ - expand statement with hyphen char ... TEXT ... - text identifying panel /-/ - expand statement with hyphen char &ZSHRTVER - variable, product version % - 2nd line starts with intense TEXT attribute COMMAND ===> - primary command field label $ZCMD - scrollable input field / / - expand statement with blank char % - end command field with TEXT attr SCROLL ===> - scroll field label _Z % - ZVAR, 4 byte input field )INIT .ZVARS = 'SCROLL' - map SCROLL field "Z" to var "SCROLL" # 31.8 {)MODEL Section} The MODEL section describes the scrollable portion of a panel where table data is displayed. The most common form of table in SPF/Pro is the select list. Select lists are used throughout SPF/Pro to display lists of files, and also for other collections like printer setup specifications, user commands, profiles, and others. The panel definition for a table also has a BODY section for the static component of the display. Usually this is used to display such things as table column headers and other non-scrollable information. Most tables have one display line per table row. However it is possible and in some cases necessary to define multiple display lines for the contents of a single table row. This occurs when the contents of the table row are wider than the display width. Up to eight lines of model statement may be specified for each row displayed from a table. Below we define for purposes of illustration a simple table which contains a name, address, and phone number in each row. In addition to that we specify an input field on the left side of the table row to allow specification of a line command. )BODY %&ZPRODTSK /-/ PHONE BOOK /-/ V &ZSHRTVER %COMMAND ===>$ZCMD / / %SCROLL ===>_Z % + + NAME ADDRESS PHONE )MODEL _L ~NAME ~ADDR ~PHONE In the example we used the output field attribute tilde (~) to insure that the fields within each table row start at the same display position even when the length of the stored values may be different. Now let's expand on the example to include both home and work addresses and phone numbers in each entry. In this case, the display data is too wide for a single line so we define a multiline model. )BODY %&ZPRODTSK /-/ PHONE BOOK /-/ V &ZSHRTVER %COMMAND ===>$ZCMD / / %SCROLL ===>_Z % + +1) NAME HOME ADDRESS HOME PHONE +2) WORK ADDRESS WORK PHONE )MODEL _L ~NAME ~HADDR ~HPHONE + ~WADDR ~WPHONE +--------------------------------------------- Now for each row in the table there are three display lines with the following content: Line 1 line command field, name, home address, and home phone number Line 2 work address, and work phone number Line 3 a separator line to provide a visual break between table entries. # 31.9 {)INIT Initialize Section} INIT is the first section processed when display service is called. In INIT you would typically initialize any variables which do not have current values. Variable assignment is done with the ASSIGN statement which is discussed in a later section. Common var assignments in INIT section are .ZVARS and .HELP. # 31.10 {)REINIT Reinitialize Section} The REINIT section is processed under the following circumstances: * Display service is called with a blank panel ID. In this case the last panel displayed is re-displayed and the REINIT section is processed in place of the INIT section. * The PROC section processing resulted in a non-blank .MSG control variable and the user did not request END or RETURN processing. This usually indicates an input error of some type. For example, a field validation may have faulted due to incorrect input. The INIT section is not processed when conditions are present which call for REINIT processing. REINIT is used for a variety of tasks including the reset of corrupted variables to valid defaults. Re-init is most typically called when a translate or verify operation performed in the PROC section fails because of bad user input. # 31.11 {)PNTS Point And Shoot Section} The PNTS section, or Point and Shoot section, is invoked every time a button on the panel is pressed which has either TYPE(PS) or PAS(ON) set. Each Point and Shoot button on the panel is given a user defined or system generated name. In the PNTS section the names of the buttons are listed along with the action to be taken if they are depressed. Once the PNTS section has executed control passes to the PROC section. # 31.12 {)PROC Process Section} The PROC section is processed when one of the following events occurs: * [SPF-Enter] is pressed * A field with ATTN(ON), TYPE(PS), or PAS(ON) is clicked on with the mouse * a PF key is pressed which is mapped to a primary command * a PF Show button is pressed * a double click on the left mouse button Prior to giving control to the PROC section, the primary command field is examined. If there is a primary command, it is examined to determine if it is one of the general commands such as END, or RETURN. Also a check is made to determine if direct transfer of control to another panel has been requested via the equal sign (=). If a general command or transfer of control is requested, the PROC section is not given control; instead control is returned to the function which displayed the panel; the return code is set to 8. Otherwise, the )PROC section is given control. In the )PROC section you can access the primary command field contents via variable ZCMD. The most common functions performed by the PROC section are: * setting up .ZSEL for selection panels * field validation for entry panels These functions are performed via translate (TRANS) and verify (VER) statements which are discussed in a later section. When translate and verify operations are completed successfully, the select function which launched the panel gains control and further processing of the field contents is done, usually resulting in some type of application transaction. If translate or verify operations fail because of bad user input, the Dialog Manager gives control to the REINIT section rather than returning to the invoking function. This is normally accompanied by an error message informing the user of the error and presenting the panel once again to obtain corrected input. Alternately in the case where the panel is a menu, the PROC section determines which menu item was selected, and sets the ZSEL variable with appropriate value to cause dispatching of the selected function. This is also accomplished via the TRANS verb. # 31.13 {)END Section} The END section marks the end of the panel definition. Statements after the END statement are ignored. The following table summarizes the Panel Elements which are detailed in the remainder of this chapter. Table 1. Panel Elements # 31.1 {)ATTR} Purpose This is a section header. It introduces the attribute characters which are used to represent the different kinds of data on the panel. This section header is optional. Format )ATTR [DEFAULT(list)] Operands DEFAULT Optional. Specifies the list of alternate characters used to override the default attribute characters which are %+_$~. Example To use the default attributes )ATTR To override the first and third default attribute characters with [ and { respectively and leave the second one as + )ATTR DEFAULT([+{) # 31.2 {)BODY} Purpose This is a section header. It introduces the layout for the fixed, non-scrolling portion of the panel. Each fixed text field, input field, output field and button must be defined by and attribute character and then followed by the text which is to appear in that location or the variable name of the input or output field. This section header is required. Format )BODY [DEFAULT(list)] [EXPAND(character)] [WINDOW(rows,columns)] [SMSG(var-name)] [LMSG(var-name)] Operands DEFAULT Optional. Specifies the list of alternate characters used to override the default attribute characters which are %+_$~. EXPAND Optional. Specifies a start-expand and end-expand character which are used to bracket a character which is used to fill out a display line to full width. The start/end character may be the same character. If not specified, "EXPAND(//)" is assumed. WINDOW Optional. Specifies the depth (in rows) and width (in columns) of a pop-up window, the panel is displayed in, after an ADDPOP command has been issued. SMSG Optional. Specifies the name of a variable to be used for display of the short message. Normally the short message is displayed in the top right hand corner of the panel. LMSG Optional. Specifies the name of a variable to be used for display of the long message. Normally the long message is displayed on the third line of the panel. Example To introduce the )BODY section for a normal display or selection panel )BODY To set the panel as a popup window which is 10 rows by 12 columns )BODY WINDOW(10,12) To set the expansion character to ! for the panel )BODY EXPAND(!!) # 31.3 {)END} Purpose This signifies the end of the panel definition. Any code which follows is ignored. This feature is sometimes used to add documentation to the panel where it cannot be processed. This section is required and must be last. Format )END Example To end the panel. )END # 31.4 {)INIT} Purpose This section contains processing commands which are executed once the first time the panel is displayed. Commands which can appear in the INIT section are IF, ELSE, VER, VPUT, TRUNC, TRANS and assignment. It is customary to define .ZVARS and .HELP in this section. This section is optional. Format )INIT Example To introduce the initialization section. )INIT # 31.5 {)MODEL} Purpose This section header introduces the layout for the scrolling, table display, portion of the panel. Each fixed text field, input field and output field must be defined by an attribute character and then followed by the text which is to appear in that location or the variable name of the input or output field. The model layout can be up to eight lines in depth. At least one input field should be specified. This section header is optional. Format )MODEL Example To introduce the model section. )MODEL # 31.6 {)PNTS} Purpose The "point and shoot" section is where you bind PS fields to specific actions. Each point and shoot field is given a name which is either an output variable, or a system generated name in the form "ZPSxxnnn" where "xx" is reserved and is always "00", and "nnn" is the ordinal position of the PS field on the panel reading left-to-right, top-to-bottom. This section is optional. Format )PNTS Example To introduce the point and shoot section. )PNTS # 31.7 {)PROC} Purpose This is where panel processing commands are specified. The PROC section gets control when [SPF-Enter] is pressed, an attention field is clicked on, a point-and-shoot field is clicked on, or a function key is pressed. Commands which can appear in the PROC section are IF, ELSE, VER, VPUT, TRUNC, TRANS and assignment. This section is optional. Format )PROC Example To introduce the processing section. )PROC # 31.8 {)REINIT} Purpose This is where panel processing commands are specified which are executed when the panel is displayed more than once with no intervening change of panel ID. Commands which can appear in the REINIT section are IF, ELSE, VER, VPUT, TRUNC, TRANS and assignment. This section is optional. Format )REINIT Example To introduce the re-initialization section. )REINIT # 31.9 {TYPE} Purpose The TYPE statement allows you to define characters which are used to represent different attributes in the )BODY and )MODEL sections of the panel definition. Format character [TYPE(INPUT|OUTPUT|TEXT|PS)] [ATTN(ON|OFF)] [CAPS(ON|OFF)] [COLOR(foreground[,background])] [INTENS(HIGH|LOW)] [JUST(LEFT|RIGHT|ASIS)] [PAD(character)] [PAS(ON|OFF)] [SCROLL(ON|OFF)] [SKIP(ON|OFF)] Operands TYPE() Optional. Specifies the field type represented by this attribute character. INPUT Specifies an unprotected input field. If TYPE is not specified, INPUT is assumed. OUTPUT Specifies a protected output field. TEXT Specifies a protected text field (typically a label). PS Specifies an unnamed point and shoot field. The name of the field is derived from its position on the panel. Starting top left and working left-to-right, top-to-bottom each button is named ZPS00001, ZPS00002 and so on. ATTN() Optional. Specifies that the field is to be presented as a button. This button, if pressed, causes the text label which makes up the button to be used as a primary command. The )PNTS section is not processed. ON Specifies that if the field is selected with the mouse, the value in the field is to be processed as a primary command. For example, if the field value were "END" and you selected it with the mouse, it would have the same effect as if you had pressed [F3] or entered the "END" primary command. OFF Specifies that the field is not selectable with the mouse. If the ATTN attribute is not specified, ATTN(OFF) is assumed. CAPS() Optional. The CAPS attribute applies to input and output fields; it does not apply to TEXT fields. ON For input fields, data is translated to uppercase before being stored. For output fields, the variable value is translated to uppercase before being displayed. OFF The input or output field is displayed "as is". If no CAPS attribute is specified, the default for the )MODEL section of tables is CAPS(OFF) and the default for all other input and output fields is CAPS(ON). COLOR() Optional. Specifies the foreground and optionally background color attribute for a field. The color may be one of: BLACK(0), BLUE(1), GREEN(2), CYAN(3), RED(4), VIOLET(5), BROWN(6), WHITE(15). You can also specify the color as a number in the range 0 to 15. Option 0.4 shows how each color appears on your monitor. The numeric form gives you access to eight additional colors which are the highlighted form of the base color. Specifying the COLOR attribute overrides the default color setting associated with the field which is established via Option 0.4. When COLOR is specified, the INTENS attribute is ignored. INTENS() Optional. Specifies how the field should appear on the panel. HIGH Specifies that the field be rendered in high intensity. See Option 0.4 for settings related to high intensity. LOW Specifies that the field be rendered in low intensity. See Option 0.4 for settings related to low intensity. JUST() Optional. Specifies how the data within a field should be justified. The JUST attribute applies to input and output fields; it does not apply to TEXT fields. LEFT Data is displayed flush left within the field. RIGHT Data is displayed flush right within the field. ASIS Data is displayed "as is". If no JUST attribute is specified, the default for the )MODEL section of tables is JUST(ASIS) and the default for all other input and output fields is JUST(LEFT) PAD() Optional. If a field is defined containing blanks, or the variable which resides in that field is blank, the field can be automatically filled with the pad character before display. If the field contains a value which does not fill the field, the remaining empty positions are automatically filled with the pad character. If the desired pad character corresponds to any of the defined attributes, or other special characters, it must be enclosed in single or double quotes. For left justified fields, pad characters are added on the right. For right justified fields, pad characters are added on the left. For "asis" justified fields, pad characters are added on the right. In all cases, pad characters are "display only"; they do not become part of the field content. PAS() Optional. The "point and shoot" attribute applies to output fields. It makes the field a button and an output field. The action taken on the button is determined by the FIELD statement in the )PNTS section. ON The field is to be rendered as a button. OFF The field is an ordinary output field. If not specified, OFF is assumed. SCROLL() Optional. The SCROLL attribute specifies whether more data can be put into the field than its width. ON Specifies that the input field can scroll to accomodate data wider than the defined field width. OFF Data typed into the input field can be no wider than the defined field width. If not specified, OFF is assumed. SKIP() Optional. Specifies whether a TAB in the preceding field will result in the focus being placed in this field. ON If TAB in previous field, set focus in this field. OFF If TAB in previous field, skip this field (do not set focus here). Example Some example attribute character definitions. )ATTR # /* the next five are the default settings */ # % TYPE(TEXT) INTENS(HIGH) # + TYPE(TEXT) INTENS(LOW) # _ TYPE(INPUT) INTENS(HIGH) SCROLL(OFF) CAPS(ON) # $ TYPE(INPUT) INTENS(HIGH) SCROLL(ON) CAPS(OFF) # ~ TYPE(INPUT) INTENS(LOW) SCROLL(OFF) CAPS(ON) # /* example additional attribute settings */ # [ TYPE(TEXT) COLOR(YELLOW,RED) # ] TYPE(PS) # < TYPE(OUTPUT) INTENS(HIGH) SCROLL(OFF) CAPS(OFF) # > TYPE(OUTPUT) INTENS(LOW) SCROLL(ON) CAPS(OFF) # { TYPE(OUTPUT) PAS(ON) # } TYPE(OUTPUT) JUST(RIGHT) PAD(0) # 31.10 {IF} Purpose The IF statement is used to test the value of a variable. This is particularly valuable in the INIT and REINIT sections to test or set a variable. The IF statement may only be used in the )PROC, )INIT and )REINIT sections. Format IF (condition) statement(s) to execute if TRUE [ELSE] [statement(s) to execute if FALSE] Operands condition Required. Condition is testing for equality or non-equality of a variable to a particular value. The expression may take one of the following forms: IF (&A = 5) is var 'A' = to 5 IF (&A != 5) is var 'A' not = to 5 IF (&A = '') is var 'A' empty IF (&A != '') is var 'A' not empty IF (&A = &B) is var 'A' = to var 'B' IF (&A != &B) is var 'A' not = to var 'B' IF (&A = 1,3,5) is var 'A' = to 1 or 3 or 5 IF (&A != 1,3,5) is var 'A' not = to 1 & 3 & 5 Processing the IF expression results in one of the following: * When the expression evaluates TRUE, statements following the IF that have an indent greater than the IF are executed. When a statement is encountered which is at the same indent (or to the left of) the IF, normal processing resumes. * When the expression evaluates FALSE, statements following the IF that have an indent greater than the IF are skipped. When a statement is encountered which is at the same indent (or to the left of) the IF, normal processing resumes. The flow of control based on the TRUE or FALSE evaluation of the IF statement and the indent level of lines following the IF is demonstrated below: IF (&A = 5) ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... ... if FALSE, processing resumes here ... In some cases you may want to check for a second condition after determining the state of a predicate. In this case a nested IF statement is used: IF (&A = 5) ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... IF (&B = YES) ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... ... if FALSE, processing resumes here ... In practical terms you might want to initialize a variable to a default value if it is empty (or blank). )INIT IF (&TIMES = '') &TIMES = 1 ELSE Optional. The ELSE statement is used in conjunction with the IF statement. Statements following the ELSE at a greater indent level are executed when the conditional expression specified in the preceding IF evaluates to FALSE. IF (&A = 5) ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... ... if TRUE, this statement is processed ... ELSE ... if FALSE, this statement is processed ... ... if FALSE, this statement is processed ... ... if FALSE, this statement is processed ... ... if TRUE or FALSE, processing resumes here ... ... if TRUE or FALSE, processing resumes here ... ... if TRUE or FALSE, processing resumes here ... Example )PROC IF (&ZCMD = 'CANCEL') &ZCMD = 'END' IF (&COLOR = 'SWITCH') &TEMP = &FOREGRND &FOREGRND = &BACKGRND &BACKGRND = &TEMP IF (&SHADOW = 'OFF') &SHADOW = 'ON' ELSE &SHADOW = 'OFF' ELSE &DEFAULT = 'NONE' # 31.11 {assignment} Purpose To set a panel variable to a new value. Assignment statements can be used in the )INIT, )REINIT and )PROC sections. Format variable = value Operands variable Required. Specifies a variable into which the value is assigned. The variable is preceded by either and ampersand (&) or a period (.). Variables preceded by an ampersand are system or user variables. Those preceded by a period are special SPF/Pro control variables such as .ZVARS and .HELP. value Required. Specifies a numeric constant, string constant, or variable. A numeric constant is any valid numeric string. A string constant must be enclosed in single or double quotes. If a variable is specified, it must be preceded by an ampersand or a period. Example Following are some examples of the simple forms that a variable assignment might take: &TIMES = 1 /* set var TIMES to 1 */ &CHECK = "YES" /* set var CHECK to YES */ &NAME = &AA /* set var NAME to the value of var AA */ &XPOS = .CURSORX /* remember current X position */ # 31.12 {TRUNC} Purpose The TRUNC verb copies "source-var" to "target-var" then truncates "target-var" based on the setting of "trunc-spec". Characters to the right of the truncation point are stored in control variable .TRAIL. TRUNC is a special extension to the assignment syntax. Format target-var = TRUNC(source-var,trunc-spec) Operands target-var Required. The variable into which the resulting truncated string is to be placed. source-var Required. The variable from which the truncated string will be taken. trunc-spec Required. A number specifying the maximum length for the resulting value or a specific character which acts as the end of the variable. Example Some examples of the use of TRUNC follow. For the first example assume var "B" is "SOMELONGTEXT": &A = TRUNC(&B,4) The example above does the following: * copies var "B" to var "A" * truncates var "A" after the fourth character * sets .TRAIL to the truncated characters After the ASSIGN: &A = "SOME" &B = "SOMELONGTEXT" .TRAIL = "LONGTEXT" For the next example assume var "B" is "2.5.4": &A = TRUNC(&B,'.') The example above does the following: * copies var "B" to var "A" * truncates var "A" at the period (.) * sets .TRAIL to the characters to the right of the period After the ASSIGN: &A = "2" &B = "2.5.4" .TRAIL = "5.4" When a character delimiter is specified in "trunc-spec", it is not stored in .TRAIL. Do not specify the .TRAIL variable within the TRUNC statement. You can also nest the TRUNC and TRANS statements: &ZSEL = TRANS( TRUNC(&ZCMD,'.') 1,first-action 2,second-action 3,third-action 4,... ' ',MSG=SPFP103 MSG=SPFP102) The above example is common in the PROC section of menus. This single statement results in the following actions: * truncate variable ZCMD at the first dot * translate the resulting value to the appropriate menu choice * if no choice is specified, issue message SPFP103 * if an unrecognized choice is specified, issue message SPFP102 If the TRANS variable does not match any of the specified values, an error message is issued and the REINIT section is processed. # 31.13 {TRANS} Purpose The TRANS verb translates "source-var" based on the setting of one or more value pairs. Value pairs specify an initial value which is checked for equality and a second value which is assigned to "target-var" if equality is found. If no equality is found, the optional message specified in "MSG=" is issued. TRANS is a special extension to the assignment syntax. Format target-var = TRANS( source-var svalue,tvalue [svalue,tvalue] ... [MSG=msg-id] ) Operands target-var Required. The variable into which the resulting translated string is to be placed. source-var Required. The variable to be translated. svalue Required. A string to compare to source-var. tvalue Required. A string to set into target-var if source-var matches svalue. Svalues and tvalues must always be in matched pairs. msg-id Optional. The number of the message to be displayed if none of the svalues match source-var. Messages are found in files SPFPRO.MSG and SPFUSER.MSG in the \PAN sub-directory of SPF/Pro. Example Some examples of the use of TRANS follow: &A = TRANS(&B T,TRUE F,FALSE MSG=SPFP102) In the example above, * if variable B is equal to T, variable A is set to TRUE * if variable B is equal to F, variable A is set to FALSE * if variable B has any other value, variable A is set blank and message SPFP102 is issued You can specify an "any other value" translation using the asterisk character as follows: &A = TRANS(&B T,TRUE F,FALSE *,'?') In the example above, * if variable B is equal to T, variable A is set to TRUE * if variable B is equal to F, variable A is set to FALSE * if variable B has any other value, variable A is set to '?' Finally, you can specify that "any other value" be left "as is" by specifying a second asterisk as follows: &A = TRANS(&B T,TRUE F,FALSE *,*) In the example above, * if variable B is equal to T, variable A is set to TRUE * if variable B is equal to F, variable A is set to FALSE * if variable B has any other value, variable A is set to the "as is" value of variable B. You can specify the same variable name on the left and right side when using TRUNC and TRANS. For example, &A = TRUNC(&A,5) &A = TRANS(&A Y,YES N,NO MSG=SPFP102) You can also nest the TRUNC and TRANS statements: &ZSEL = TRANS( TRUNC(&ZCMD,'.') 1,"DISPLAY PANEL(SIZEHELP)" 2,"CMD(SIZECALC)" 3,"PGM(SIZEPRNT) PARM(SYNCH)" 4,"BACKPGM(SIZEPRNT) PARM(ASYNC)" ' ',MSG=SPFP103 MSG=SPFP102) The above example is common in the PROC section of menus. This single statement results in the following actions: * truncate variable ZCMD at the first dot * translate the resulting value to the appropriate menu choice * if no choice is specified, issue message SPFP103 * if an unrecognized choice is specified, issue message SPFP102 If the TRANS variable does not match any of the specified values, an error message is issued and the REINIT section is processed. # 31.14 {VER} Purpose The VER statement is used to verify the contents of a variable against a specific set of values, ranges, or forms. You would typically use VER in the PROC section to validate input variables. If the contents of the variable do not meet the verify criteria, an error message is issued and the REINIT section is processed. Format VER(variable,content-spec,...[,list-of-values,...][,MSG=msg-id]) Operands variable Required. The variable which is to be verified. It must be preceded by an ampersand(&). content-spec Required. The content specification conforms to one of eight rules. They may be used individually or in combination to achieved the desired level of validation. The eight rules are: ALPHA The data can only be comprised of alphabetic characters. BOOL The data can have one of the following values and no others: Y, N, YES or NO. HEX The data can only be comprised of pairs of hexadecimal digits. LIST The data can have one of the values in the list and no others. The list of values follows "LIST" separated by commas. NB The data must not be blank. NUM The data must be an integer number. PICT The data must conform to the PICTURE specification. The specification is a quoted string which follows PICT. The picture string is comprised of picture characters, each of which specifies a test criteria for its character position: -- C, position may contain any character -- A, position may contain any alpha character -- N, position may contain any numeric character -- X, position may contain any hex character -- punctuation, literal, must match exactly -- lowercase alpha, literal, must match exactly RANGE The data must be in the numeric range of the two values which follow. list-of-values Optional. A list of literal values separated by commas. msg-id Optional. The number of the message to be displayed if source-var does not match match any of the svalues. Messages are found in files SPFPRO.MSG and SPFUSER.MSG in the \PAN sub-directory of SPF/Pro. Example VER (&A,ALPHA) var A must be alpha VER (&A,NUM) var A must be a number VER (&A,NB) var A must be non-blank VER (&A,BOOL) var A must be one of: Y, N, YES, or NO VER (&A,HEX) var A must be one or more hex pairs VER (&A,RANGE,n1,n2) var A must be a number between "n1" and "n2" VER (&A,LIST,v1,v2,v...) var A must be one of the values in the list VER (&A,PICT,"string") var A must conform to the picture string VER (&A,...,MSG=msg-id) if var A does not meet criteria, issue msg # 31.15 {VPUT} Purpose Values entered into input variables are automatically stored in the function pool. It is sometimes desirable to make those variables visible to the SHARED, GLOBAL, or PROFILE pools. To do this use the VPUT statement. Format VPUT(variable,...) [SHARED|GLOBAL|PROFILE] Operands variable Required. The variable, or list of variables which are to be put into one of the pools. pool Optional. The name of the pool. If not specified, the FUNCTION pool is assumed. Other values are SHARED, GLOBAL and PROFILE. Example In the following example, the VPUT statements cause function pool variables A, B, and C to be published to the PROFILE pool, variables D, E, and F to be published to the SHARED pool, and variables G and H to be published to the GLOBAL pool. )PROC VPUT (A B C) PROFILE VPUT (D E F) SHARED VPUT (G H) GLOBAL # 31.14 {Special Variables} # 31.14.1 {SCROLL} This var establishes the scroll amount for all scrollable panels. There are four independent vars which are set when this var is changed: * ZSCBR, SCROLL for BROWSE * ZSCED, SCROLL for EDIT * ZSCFL, SCROLL for directory lists * ZSCML, SCROLL for all other tables The default SPF/Pro panels are all specified with a "Z" var in the scroll field which is assigned to var "SCROLL". The independent values are automatically maintained across sessions. # 31.14.2 {ZCMD} On entry to the PROC section ZCMD holds the contents of the primary command field. See page 458 for an explanation of the use of ZCMD. # 31.14.3 {ZSEL} In selection panels, the ZSEL var holds the selection specification to be performed following processing of the PROC section. ZSEL is only processed if the panel was invoked by a SELECT PANEL() statement. # 31.14.4 {ZTDSELS} Contains the number of rows selected in the current table display. See the ISPEXEC TBDISPL command for further details on table display. # 31.14.5 {ZPFnn} PF key variable names are in the family: ZPFnn (01-48). Use a leading 0 for PF key numbers with only one digit. # 31.15 {Control Variables} # 31.15.1 {.ALARM} Use the .ALARM control variable to cause the alarm to be sounded when a particular panel is displayed. This variable would normally be set in the INIT or REINIT section. The variable can be set to YES or NO. .ALARM = YES # 31.15.2 {.AUTOSEL} Use the .AUTOSEL control variable to cause the top row of a table to be auto-selected when [SPF-Enter] is pressed. This variable would normally be set in the INIT or REINIT section. The variable can be set to YES or NO. .AUTOSEL = YES # 31.15.3 {.CURSOR/.CSRPOS} The .CURSOR and .CSRPOS control variables work together and are used in two ways: * For queries, .CURSOR contains the name of the current field. .CSRPOS contains cursor position within current field. * For altering the cursor position, Set .CURSOR to change the current field. Set .CSRPOS to change cursor position within current field. &CURFNAME = .CURSOR get cur field name &CURCPOS = .CSRPOS get cur cursor pos in fld .CURSOR = NAME set cur field to field NAME .CSRPOS = 4 position to col 4 in field The .CURSOR variable is automatically set by TRANS and VER statements when they set the .MSG var in response to a translate or verify fault. # 31.15.4 {.CURSORX/.CURSORY} These control vars contain the current column(X), and row(Y), at the time that the )PROC section gains control. If you are using POPUP menu or DBLCLK to apply a particular action, the current X/Y can be used as your field selector. In )PROC section: &XPOS = .CURSORX &YPOS = .CURSORY # 31.15.5 {.CSRROW} Use the .CSRROW control variable to set the current table to a specific row. If .AUTOSEL = YES was specified, the new row is also auto-selected. .CSRROW = 5 set the current table row to 5 # 31.15.6 {.DBLCLK} In SPF/Pro the effect of pressing the [SPF-Enter] key can be simulated by a double click on the left mouse button. If this occurs, the control variable .DBLCLK is set to 'Y'. Use in the )PROC section to set one of your own variables. )PROC &CLICKED = .DBLCLK # 31.15.7 {.POPUP} SPF/Pro's support of GUI controls enables you to control all aspects of the product's operation with the mouse. The right mouse button provides context sensitive menus to eliminate the need for typing common commands. You can control this menu from within your panels by using the .POPUP, .POPUPELC, .POPUPETX and .POPUPTB control vars. .POPUP is assigned pairs of values. The first of the pair is the text which is to appear in the popup menu; the second of the pair is the primary command to be set into ZCMD (user defined or native). Each value in the assignment string (except the last) must be delimited by a trailing vertical bar (|). Any number of pairs can be specified to make up the menu. When a large number of entries appear in the popup menu it is a good idea to organize them into groups and to separate them with a horizontal separator. To get the horizontal separator into the popup, specify a pair of underscore characters (_) followed by vertical bar (|). When a menu gets so large as to be unwieldy, it can be broken into sub-menus. A sub-menu is indicated by a small arrow on the right of the menu item. To specify a sub-menu, put the sub-menu item/command pairs in brackets([]) in the command part of the primary menu pair. An example is provided below. It is also possible to prefix each item which is being displayed with a plus (+) or a minus (-). The plus, which is the default, means show the item in the list and make it selectable. The minus means show the item in the list but in a grayed out mode thus making it unselectable. )INIT .POPUP = 'Save|SAVE|Print|PRINT ALL|_|_|Exit|END|Help|HELP' or .POPUP = 'item1|cmd1|item2|cmd2|item3|[sub1|cmd1|sub2|cmd2]' # 31.15.8 {.POPUPELC} POPUPELC is a special variant of the .POPUP control variable. It is used to control the behavior of the EDIT Popup menu in the Line Command portion of the edit window. See .POPUP for details of use and syntax rules. # 31.15.9 {.POPUPETX} POPUPETX is a special variant of the .POPUP control variable. It is used to control the behavior of the EDIT Popup menu in the Text portion of the edit window. See .POPUP for details of use and syntax rules. # 31.15.10 {.POPUPTB} .POPUPTB achieves the same effect as .POPUP except that the popup menu created is for use in Table Displays. .POPUP and .POPUPTB can be specified on the panel giving context sensitive control of the popup menus depending on where the mouse pointer was when the right button was pressed. As with .POPUP, .POPUPTB should be assigned to pairs of values. To differentiate between a line command to be applied to an entry in the table and a primary command applied to the whole panel; line commands should be prefixed by a colon (:). )INIT .POPUP = 'Save|SAVE|Print|PRINT ALL|_|_|Exit|END|Help|HELP' .POPUPTB = 'Edit|:E|Delete|:D|Print|:P|_|_|Clear List|CLEAR' # 31.15.11 {.HELP} Use the .HELP control variable to set the help panel ID for a given panel. This variable would normally be set in the INIT section. .HELP = ISPE040 # 31.15.12 {.MSG} Use the .MSG control variable to set the message ID for a message to be displayed after the PROC section has been processed. This var is explicitly set in the PROC section or implicitly set by TRANS and VER statements when a translate or verify fault occurs. # 31.15.13 {.TRAIL} The .TRAIL variable contains the remainder of a variable that has been truncated by the TRUNC statement. # 31.15.14 {.ZPRIM} To make your panel the "top" panel, to which the RETURN command passes control and the one which jump commands use as the starting point, set .ZPRIM='YES' in the panel definition. Panel S2MPRIM.PAN has this value set by default. # 31.15.15 {.ZVARS} Use the .ZVARS control variable to assign full variable names to "Z" var placeholders. The letter "Z" has special significance in the panel definition language. At any point in the panel definition you may specify input or output fields with the letter "Z" in place of the full variable name. An input field is specified as "_Z", an output field as "~Z". Actual field names are assigned via the .ZVAR control var as follows: .ZVARS = '(name1 name2 name3 name...)' "Z" vars are positional. The first "Z" var in the panel definition (reading left to right, top to bottom) is assigned the "name1" value, the second the "name2" value, and so on. This assignment is done in the INIT section. Subsequent references to the "Z" var fields are made using their full names. # 31.16 {Message Files} A byproduct of defining panels is the creation or modification of messages. You can modify or add messages to: SPFPRO.MSG This is the definition file for standard SPF/Pro messages. SPFUSER.MSG This is the definition file for user messages. # 31.17 {Message Definition} SHORT MESSAGE Required. On the first line of two you specify the short message text. The short message should be no longer than 32 characters. It begins with a seven character message ID in the form: ccccnnn Where "cccc" is the four character component ID like "USER" and "nnn" is the unique message number in the range "001" to "999". ALARM Optional. On the same line as the short message you can specify the .ALARM control var to a value of YES or NO. If not specified, NO is assumed. HELP Optional. On the same line as the short message you can specify the .HELP control var to the panel-id of the help panel for this message. The help panel is displayed when [F1] is pressed immediately after the long message is posted. If not specified, no help panel is available. LONG MESSAGE Required. On the second line of two you specify the text of the long message. The long message is displayed when [F1] is pressed immediately after the short message is posted. variables Optional. Within the text of the short or long message, you can insert variables at any point. For example, USERnnn ... text ... &MYVAR ... text ... See file SPFPRO\PAN\SPFPRO.MSG for examples of message definition. # 32. {REXX Programming} "REstructured eXtended eXecutor" # 32.1 {Introduction} REXX is a programming language designed to be portable across a wide range of IBM computers. SPF/Pro's implementation runs on desktop workstations and is faithful to the original definition of the language while, at the same time, fully exploiting the SPF/Pro ISPEXEC and ISREDIT interfaces. REXX is an excellent language for novice or experienced programmers. Novices find the immediacy of interaction aids their programming development. Experienced programmers find they can write effective, production quality applications, in minimal time. REXX has many similarities to other procedural programming languages such as COBOL, Fortran, PL1 and C. One major difference from these languages is that it is an interpreted language. Instead of compiling, linking, and then executing, the source program is "executed" directly. REXX converts each line of source code to an executable form as it is encountered. This means that the run-time environment for REXX has to be loaded when a REXX program is run. In practice the overhead of loading the run time environment is only charged to the first REXX procedure run in a new SPF/Pro session. REXX has many built-in functions to simplify the task of programming. It is also user extensible. Functions to support common tasks can be added to the language for use by other REXX procedure developers at the department, division, or company wide level. # 32.1.1 {Scope of this Document} There are many texts which describe the REXX language and programming techniques that are specific to REXX. In this chapter, we provide a working knowledge of REXX as it is used in conjunction with SPF/Pro. For outside publications we recommend The REXX Language, M. F. Cowlishaw, Prentice Hall, 1989, ISBN 0-13-780651-5. Mr. Cowlishaw designed and implemented the first REXX interpreters and is a guiding force in the evolution of the language. # 32.1.2 {REXX Language Statements} REXX programs are text files comprised of records commonly called program source. We recommend that each source record map to one REXX language statement. At the highest level of abstraction there are three classes of REXX program statements. Comments The most basic language component is the comment. Comments are necessary to explain program operation when the code is not self explanatory. In REXX a comment may start and end anywhere on a line, or span multiple lines. Comments start with "/*" and end with "*/". Comments may be nested. ...... /* comment on same line as other statement */ /* comment on a line by itself */ /* ... ... comment spanning multiple lines ... */ /* ... /* comment inside comment */ ... */ /* ... ... /* comment inside multiline comment */ ... */ Instructions REXX as implemented in SPF/Pro has approximately 20 intrinsic instructions to manipulate variables and control program flow. It also has approximately 60 built-in functions to perform various high level programming tasks. Commands Commands are text strings that are sent to an external command processor. The default external command processor is the operating system. In SPF/Pro you can also send commands to the ISREDIT macro command processor or the ISPEXEC dialog services command processor. Unary statements comprised of quoted strings are commands. ... REXX intrinsic statement ... '... command for external command processor ...' ... REXX intrinsic statement ... # 32.1.3 {Data Elements} All REXX data elements fall into one of four categories: * TEXT - single or double quoted string of any characters * NUMBER - signed or unsigned integer, decimal number, or exponential number * HEXADECIMAL - a string of paired hex digits in the form 'dd'x or 'dd'X where 'd' is in the set '0123456789abcdefABCDEF'. * BINARY - a string of mod eight binary digits in the form 'dddddddd'b or 'dddddddd'B where 'd' is in the set '01'. # 32.1.4 {Variables} REXX variables are typeless. Their contents are processed according to context. For example, if you have a variable named COUNTER, you might inititialize it to 0 and then increment it by 1 each time some event occurs. counter = 0 ... counter = counter + 1 ... You might also want to display it on the system console. say counter In the first case COUNTER's context is as a number, in the second it is a text string. No special conversion is necessary. REXX takes care of that automatically. In functional terms you may assign text strings, numbers, hexadecimal strings, and binary strings to variables. name = 'John Doe' /* text (single quoted) */ name = "John Doe" /* text (double quoted) */ counter = 0 /* integer number */ fraction = 3.14 /* decimal number */ negnum = -4.77 /* negative number */ bignum = 5.3E8 /* big exponential number */ littlenum = 0.23E-7 /* little exponential num */ hexstring = '0C4A2F'X /* hexadecimal string */ hexstring = '0c4a2f'x /* same hex string */ hexstring = '0c 4a 2f'x /* same hex string */ binstring = '11000111'b /* binary string ('C7'x) */ binstring = '1100 0111'b /* same bin string */ Note: If an odd number of hex digits is specified, a '0' is prepended to the specification. Thus '72c'x is prepadded to '072c'x. Similarly, if fewer than 8 bits are specified in a binary string, '0' bits are prepended to fill the missing positions. Thus '101'b is prepadded to '00000101'b. You can get run time errors if you try to apply an operation to a var which contains a value that does not conform to the operand requirements. For example: alpha = 'some text' numeric = 757 sum = alpha + numeric The value in var "alpha" is not in the correct form for the addition operation. # 32.1.5 {Variables Names} Variable names can be up to 250 characters in length. They may be comprised of characters: a-z A-Z (same as a-z) 0-9 at(@) pound(#) underscore(_) exclamation(!) question(?) period(.) Variables may not begin with "0-9" or period(.). Names are NOT case sensitive. For example, COUNT = Count = count. # 32.1.6 {Multi-statement Line} You may have more than one REXX statement on a line separated by semicolons. We do not recommend this practice. ...statement1...; ...statement2...; ...statement3... # 32.1.7 {Continuation Line} Occasionaly a statement becomes so complex that it will not fit on a single line, or it may be more clearly expressed on multiple lines. In this case line continuation should be used. A line is considered continued when it end in a comma(,). IF A = B & C = D & E = F THEN ... can be coded like this: IF A = B &, C = D &, E = F THEN # 32.1.8 {Blanks and Blank Lines} For clarity it is recommended that you use blanks and blank lines freely to improve the readability of your REXX procedures. In general blanks and blank lines are ignored. a=5 b=6 c=a+b could be more clear if coded like this: a = 5 b = 6 c = a + b # 32.1.9 {Labels} It is sometimes desirable to put more than one function in a single source module. In this case, labels are used to define the start of separate functions. All functions so declared, must be concluded with a RETURN statement. SELECT WHEN LEVEL = 'OSVS' THEN CALL OSVS_COMPILE WHEN LEVEL = 'VSC2' THEN CALL VSC2_COMPILE END /* SELECT */ ... OSVS_COMPILE: ... RETURN VSC2_COMPILE: ... RETURN # 32.1.10 {Stem Variables} Stem variables are used to store related data using a common root (or stem) name. A multipart stem variable can produce the effect of a multidimensional array. MONTH.1 = 'January' MONTH.2 = 'February' ... MONTH.12 = 'December' month.jan = 1 month.feb = 2 ... month.dec = 12 /* a two dimensional array */ board.1.2 = 'pawn' /* set piece at row 1 col 2 board.5.3 = 'knight' /* set piece at row 5 col 3 board.7.8 = 'rook' /* set piece at row 7 col 8 /* addressing array using vars to index and a var for piece */ row = 5 col = 3 piece = 'knight' ... board.row.col = piece /* assign piece */ # 32.1.11 {Special Variables} Most of the time your REXX procedure will run error free (after debugging). However, it is possible to have run-time errors and they must be detected and handled. REXX provides a number of special variables for this purpose. RC When you execute an external command, the command processor will set the RC variable automatically to propagate the return code for that command. Most external commands set RC = 0 to indicate successful completion and RC <> 0 to indicate an error. It is up to you to check RC and take appropriate action. target = '... user specified text ...' ..... 'ISREDIT FIND' target /* edit primary command FIND */ if rc = 0 then do /* string found */ ... do something ... end else do /* string not found, or error */ ... take appropriate action ... end RESULT Any routine that is explicitly called (via CALL) may return a value to the caller. The called routine is concluded with "RETURN value". The calling routine will find the returned value in special variable RESULT. Many functions which return values are invoked on the right hand side of an assign statement. In that case, the returned value becomes the current value of the right hand side and is set into the left hand side variable and RESULT is not set. fred = 'some text' call length(fred) /* RESULT is set to length of "fred" var */ result = '' x = length(fred) /* X is set to length of "fred" var, RESULT is not set */ SIGL Whenever a control flow jump is made via CALL or SIGNAL, the source procedure name and line number of the calling function are set in special variable SIGL. This variable is typically used in error trapping conditions which will be discussed at length in a later section. (see SIGNAL instruction) # 32.1.12 {Recommended Standards} Each REXX procedure MUST begin with a comment. A typical REXX prolog follows: /* REXX PROCEDURE */ /*=========================================*/ /* AUTHOR: Command Technology Corporation */ /* DATE: 01-JAN-1996 */ /* PURPOSE: EXAMPLE COMMENT */ /* VERSION: 1.0 */ Indentation is recommended for all conditional statements. IF condition THEN DO ... indented TRUE block ... ... indented TRUE block ... ... indented TRUE block ... END ELSE DO ... indented FALSE block ... ... indented FALSE block ... ... indented FALSE block ... END /* ENDIF */ We recommend that an /* ENDIF */ be placed on IF statements. Also we recommend that DO loops and SELECTs be given a comment on their mandatory END statements to indicate their end. # 32.1.13 {Running a REXX Procedure} REXX procedures are usually kept in a sub-directory which is in the macro and command path (specified on panel 0.8). They have the extension .ISP for ISPEXEC REXX Procedures and .SPF for ISREDIT REXX Macros. To run your procedure from within SPF/Pro: * If it is a file of type .ISP in the current directory or the command path (see 0.8), you can type it directly in the command field: COMMAND ===> CMD MYREXX * or you can invoke it via option 7.1 Dialog Test * or you can add the command name to the SPFCMDS command table via option 3.J: VERB ===> MYREXX TRUNC ===> 0 ACTION ===> SELECT CMD(MYREXX) DESCRIPTION ===> Sample REXX procedure * If you are in edit, and it is a file of type .SPF in the current directory or the macro path (see 0.8), you can type it directly in the command field: COMMAND ===> MYREXX * or set it into the XMACRO/IMACRO option on the edit entry panel. # 32.2 {REXX Instructions} REXX instructions fall into two categories, intrinsic and built-in functions. REXX intrinsics are common program functions that appear in most programming languages. The built-in functions are a rich set of extensions to the basic language which perform many complex tasks. # 32.2.1 {Instrinsic Instruction Summary} ADDRESS set the destination for external commands ARG retrieve parameters passed to function CALL invoke a function DO execute a block of instructions DROP restore a variable to an uninitialized state EXIT end program immediately IF modify control flow based on condition INTERPRET execute instructions stored in a variable ITERATE jump to the top of a DO loop from middle LEAVE exit a DO loop immediately NOP does nothing (use as placeholder) NUMERIC modify how arithmetic processing is performed OPTIONS (not supported) PARSE parse a string under control of a template PROCEDURE control scope of variables PULL read a line from the TTY keyboard PUSH (not supported) QUEUE (not supported) RETURN end a function, optionally return a value SAY write a line to the TTY screen SELECT multiple condition list (aka CASE) SIGNAL set error trapping conditions TRACE trace REXX interpreter actions # 32.2.2 {Built-in Function Summary} ABBREV return TRUE/FALSE, is short string part of long string? ABS return the absolute value of a number without a sign ADDRESS return the name of the external command processor ARG return the parameters passed to a function BITAND return result of logically ANDed bit strings BITOR return result of logically ORed bit strings BITXOR return result of logically XORed bit strings B2X return hex char string, input binary char string CENTER return base string padded on left and right to center CENTRE same as CENTER CHARIN read a string from an external file CHAROUT write a string to an external file CHARS return number of chars remaining unread in external file COMPARE return TRUE/FALSE, do strings compare? CONDITION return current error condition (see CALL and SIGNAL) COPIES returns string catenated to self N times C2D returns decimal value, input char string C2X returns hex char string, input char string DATATYPE returns data type, or TRUE/FALSE on data type test DATE returns the date DELSTR returns substring after deleting at Nth char for N chars DELWORD returns substring after deleting at Nth word for N words DIGITS returns the current setting of the NUMERIC digits value D2C returns char value, input decimal value D2X returns hex string, input decimal value ERRORTEXT returns the text associated with a particular error number FORM returns the current setting of NUMERIC form value FORMAT formats a number (rounds if necessary) FUZZ returns the current setting of the NUMERIC fuzz value INSERT returns superstring comprised of base plus insert strings LASTPOS returns position of last little string in big string LEFT returns substring starting at 1 for N LENGTH returns the length of string LINEIN reads one record from an external file LINEOUT writes one record to an external file LINES returns TRUE/FALSE, any unread lines in external file? MAX returns largest number of a set of numbers MIN returns smallest number of a set of numbers OVERLAY overlays one string with another POS returns position of first little string in big string QUEUED (not supported) RANDOM returns a random number from a range REVERSE returns string with chars reordered right to left RIGHT returns N chars from right end of string SIGN returns the sign of a number SOURCELINE returns number of lines or a specific line of a REXX proc SPACE set specific number of blanks (or other char) between words STREAM return state info on a file, also open/close/seek STRIP strip leading and/or trailing blanks (or other char) from string SUBSTR returns substring at N for N chars SUBWORD returns subword at N for N words SYMBOL returns the state of a var, undefined, defined, or literal TIME returns the time TRACE returns or current setting sets TRACE TRANSLATE returns translated string, char for char by table TRUNC returns a specified decimal precision derivitive of a number VALUE returns or set the value of an environment variable VERIFY verify presence or absence of chars within a string WORD returns the Nth word in a string WORDINDEX returns the char position of the Nth word in a string WORDLENGTH returns the length of the Nth word in a string WORDPOS returns the word number after search for a word in a string WORDS returns the number of words in a string XRANGE returns full range of codes between start and end char/num X2B returns binary char string, input hex char string X2C returns ASCII (or EBCDIC) char string, input hex char string X2D returns decimal value, input hex char string # 32.2.3 {By String Operations} Instructions: PARSE parse a string under control of a template Built-ins: ABBREV return TRUE/FALSE, is short string part of long string B2X return hex char string, input binary char string CENTER return base string padded on left and right to center CENTRE same as CENTER COMPARE return TRUE/FALSE, do strings compare COPIES returns string catenated to self N times C2D returns decimal value, input char string C2X returns hex char string, input char string DELSTR returns substring after deleting at Nth char for N chars DELWORD returns substring after deleting at Nth word for N words D2C returns char value, input decimal value D2X returns hex string, input decimal value INSERT returns superstring comprised of base plus insert strings LASTPOS returns position of last little string in big string LEFT returns substring starting at 1 for N LENGTH returns the length of string OVERLAY overlays one string with another POS returns position of first little string in big string REVERSE returns string with chars reordered right to left RIGHT returns N chars from right end of string SPACE set specific number of blanks (or other char) between words STRIP strip leading and/or trailing blanks (or other char) from string SUBSTR returns substring at N for N chars SUBWORD returns subword at N for N words TRANSLATE returns translated string, char for char by table VERIFY verify presence or absence of chars within a string WORD returns the Nth word in a string WORDINDEX returns the char position of the Nth word in a string WORDLENGTH returns the length of the Nth word in a string WORDPOS returns the word number after search for a word in a string WORDS returns the number of words in a string XRANGE returns full range of codes between start and end char/num X2B returns binary char string, input hex char string X2C returns ASCII (or EBCDIC) char string, input hex char string X2D returns decimal value, input hex char string # 32.2.4 {By Numeric Operations} Instructions: NUMERIC modify how arithmetic processing is performed Built-ins: ABS return the absolute value of a number without a sign C2D returns decimal value, input char string DIGITS returns the current setting of the NUMERIC digits value D2C returns char value, input decimal value D2X returns hex string, input decimal value FORM returns the current setting of NUMERIC form value FORMAT formats a number (rounds if necessary) FUZZ returns the current setting of the NUMERIC fuzz value MAX returns largest number of a set of numbers MIN returns smallest number of a set of numbers RANDOM returns a random number from a range SIGN returns the sign of a number XRANGE returns full range of codes between start and end char/num X2D returns decimal value, input hex char string # 32.2.5 {By I/O Operations} Instructions: PULL read a line from the TTY keyboard PUSH (not supported) QUEUE (not supported) SAY write a line to the TTY screen Built-ins: CHARIN read a string from an external file CHAROUT write a string to an external file CHARS return number of chars remaining unread in external file LINEIN reads one record from an external file LINEOUT writes one record to an external file LINES returns TRUE/FALSE, any unread lines in external file? QUEUED (not supported) STREAM return state info on a file, also open/close/seek # 32.2.6 {By Exception Handling} Instructions: SIGNAL set error trapping conditions TRACE trace REXX interpreter actions Built-ins: ADDRESS return the name of the external command processor CONDITION return current error condition (see CALL and SIGNAL) ERRORTEXT returns the text associated with a particular error number TRACE returns or current setting sets TRACE # 32.3 {Assignment Instruction} Assignment of variables in REXX is done in the conventional manner with an equal sign(=). Assign has three parts: * Left-hand-side, a variable * equal sign(=), the assign operator * Right-hand-side, a literal, a variable, an expression, or a function call. The variable on the left-hand side of the assignment derives its type and content from the variable, literal or expression on the right-hand side. pos = 1 /* literal */ name = parm1 /* variable */ sum = a + b /* expression */ len = length(name) /* function */ Assignment can also include algebraic expressions such as the ones listed below. A = A + 1 /* addition */ B = B - 2 /* subtraction */ C = C * 3 /* multiplication */ D = D / 4 /* division */ E = E % 5 /* integer division */ F = F // 6 /* remainder of F/6 */ G = G ** 7 /* exponentiation */ H = -H /* negate H */ I = +I /* same as I */ Parentheses may be used to order the evaluation of an expression and should be used even when the default order is acceptable to improve clarity. The default order of evaluation is: + - unary operator () parentheses (around functions first, then innermost, then left to right) ** exponentiation (warning a**b**c is illogical but is evaluated as (a**b)**c). Must be an integer. * / % // multiplication and division are of equal priority (left to right) + - addition and subtraction are of equal priority (left to right) Lets look at an example. The following code: total = (2.9 + (a - 3.4 * b))**(c + d), / (23 - u*u) evaluates in the following order: temp1 = 3.4 * b /* innermost () first, * before + */ temp2 = a - temp1 temp3 = 2.9 + temp2 /* () of equal precedence left to right */ temp4 = c + d /* next () in left to right order */ temp5 = u * u /* * before - */ temp6 = 23 - temp5 temp7 = temp3 ** temp4 /* ** before / */ temp8 = temp7 / temp6 # 32.4 {Communication with the User} The commands PULL and SAY allow the REXX procedure to communicate with its user in simple line I/O. Lets look at a simple program: /* REXX PROCEDURE */ /*======================================*/ /* PROCEDURE TO DEMONSTRATE SAY & PULL */ SAY 'Welcome' /* A string */ SAY 'It is ' DATE() TIME() /* Date & Time */ SAY 'What is your name?' /* A string */ PULL TITLE FIRST LAST . /* read three items and ignore every */ /* thing after the third item - the */ /* period causes all else to be lost */ SAY 'Hello' TITLE, /* continuation */ LAST 'or can I call you' FIRST '?' produces output as follows: prog: Welcome prog: It is 1 Jan 1996 00:00:01 prog: What is your name? user: MR TOM WATSON prog: Hello MR WATSON or can I call you TOM ? # 32.5 {Conditional Processing} Conditional processing in REXX is achieved with: IF-THEN-ELSE SELECT-WHEN-THEN-END DO-WHILE/UNTIL-END # 32.5.1 {Syntax for IF} /*--------------------------------------*/ IF condition THEN ... single statement ... /* ENDIF (RECOMMENDED BUT NOT REQUIRED) */ /*--------------------------------------*/ IF condition THEN DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END /* ENDIF (RECOMMENDED BUT NOT REQUIRED) */ /*--------------------------------------*/ IF condition THEN ... single statement ... ELSE ... single statement ... /* ENDIF (RECOMMENDED BUT NOT REQUIRED) */ /*--------------------------------------*/ IF condition THEN DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END ELSE DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END /* ENDIF (RECOMMENDED BUT NOT REQUIRED) */ /*--------------------------------------*/ IF condition THEN DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END ELSE DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END /* IF */ /*--------------------------------------*/ Note the use of the optional "/* ENDIF */" comment to define the scope of the IF. Also note the indentation and use of DO when multiple statements are specified. Conditional operators follow: Note: The characters ? and \ have identical meanings and can be used interchangeably. They are both included because some keyboards and national character sets include one or the other. The choice for the programmer is purely a personal one and in keeping with local standards. As you have seen from the preceding table, the conditional operators have two forms: * EXACT/STRICT - the familiar form used by many other programming languages is referred to as "exact" or "strict". That is, the values are compared byte by byte for equality, non-equality or magnitude relation and the result determined. Length differences are considered in the comparison. if "home" == "home" /* tests TRUE */ if "home" == " home " /* tests FALSE */ if 127 == "127.0" /* tests TRUE */ if 127 == " +127.0 " /* tests FALSE */ * FUZZY - in REXX either side of the comparison may have leading and/or trailing blanks. These blanks are removed (logically) prior to performing the operation. Thus values that are not strictly equal may compare equal. if "home" = "home" /* tests TRUE */ if "home" = " home " /* tests TRUE */ if 127 = "127.0" /* tests TRUE */ if 127 = " +127.0 " /* tests TRUE */ Logical operators can also be used in expressions to form compound conditions: * AND, use ampersand(&) * OR, use vertical bar(|) * XOR, use double ampersand(&&) Care should be taken when mixing "AND" and "OR" because "AND" has precedence. In order to resolve conflicts with precedence parentheses can be used to override the default order of evaluation. It is a good practice when there is any doubt, to use parentheses to make the order of evaluation explicit. IF (LINES < 10 | LINES > 20 ) &, (PAGES = 1 | PAGES = 100) THEN SAY 'Title or trailer' ELSE SAY 'Detail' /* ENDIF */ # 32.5.2 {Syntax for SELECT} SELECT WHEN condition THEN ... single statement ... WHEN condition THEN DO ... multiple statements ... ... multiple statements ... ... multiple statements ... END /* DO */ WHEN ... THEN ... single statement ... OTHERWISE ... single statement ... END /* SELECT */ Only the first TRUE condition is executed even if multiple conditions specified are TRUE. # 32.5.3 {Do Loops} Do loops control iterative processes in REXX procedures. The Do loop syntax comes in a variety of formats suitable to a wide variety of situations. DO /* do once */ ... ... ... END /* DO */ Here the code "..." is executed once. This construct is most commonly found in IF and SELECT structures to allow multiple statements to be executed in a single TRUE or FALSE clause. DO FOREVER /* do forever */ ... ... ... END /* DO */ Here the code "..." is executed "forever". That is it loops continuously unless a LEAVE statement is issued. The LEAVE statement transfers control to the statement after END. DO count /* do number of times in "count" var */ ... ... ... END /* DO */ Here the code "..." is executed the number of times contained in the variable "count". DO 10 /* do 10 times (literal) */ ... ... ... END /* DO 10 */ Here the code "..." is explicitly executed 10 times. DO UNTIL A > B /* do until a condition is met */ ... ... ... END /* DO */ Here the code "..." is executed UNTIL "A" becomes greater than "B". If the condition is true at the outset of the Do loop, the code is executed once. The test of the condition is performed at the end of the loop. DO WHILE A < B ... ... ... END /* DO */ Here the code "..." is executed WHILE "A" is less than "B". If the condition is false at the outset of the Do loop, the code is executed zero times. The test of the condition is performed at the beginning of the loop. DO I = 1 TO 10 /* do with auto-increment */ ... ... ... END /* DO */ Here the code "..." is executed 10 times and on each iteration "I" is incremented by 1. DO I = 1 TO 365 BY 7 /* do with auto-increment */ ... ... ... END /* DO */ Here the code "..." is executed 53 times and on each iteration "I" is incremented by 7. Two additional statements which are closely linked to Do loops are LEAVE and ITERATE. These are used to modify the execution order of a REXX Do loop. LEAVE terminates from anywhere within the loop. ITERATE resumes execution from the top from anywhere within the loop. DO I = 1 TO 365 BY 7 ... ... IF X = Y THEN ... ... ITERATE /* JUMP TO TOP OF LOOP */ /* ENDIF */ ... ... IF X = Z THEN LEAVE /* QUIT LOOP IMMEDIATELY */ /* ENDIF */ ... ... END /* DO */ # 32.5.4 {More on Stem Variables (Arrays)} Stem Variables (Arrays) are useful ways of storing repetitive instances of data. No special declaration of the Stem Variable (Array) is needed; definition is implied from the use of Stem Variable syntax. ADDRESS.1 = 'Command Technology Corporation' ADDRESS.2 = '1040 Marina Village Parkway' ADDRESS.3 = 'Alameda' ADDRESS.4 = 'CA' ADDRESS.5 = '94501' ADDRESS.6 = '1-510-521-5900' The period which separates the stem from its variable occurrence describes the array. Array occurrences can be stated as variables. DO I = 1 TO 6 SAY ADDRESS.I END /* DO */ A convention, not a mandatory feature, is to record the number of occurences in the Stem Variable (Array) in element 0. Thus, ADDRESS.0 = 6 Stem Variables can also be defined in terms of string component names and can have multiple components: ADDRESS.COMPANY = 'CTC' ADDRESS.STREET = '1040 Marina Village Parkway' ADDRESS.MAILSTOP = '' ADDRESS.CITY = 'Alameda' ADDRESS.STATE = 'CA' ADDRESS.ZIP = '94501' ADDRESS.PHONE.VOICE = '1-510-521-5900' ADDRESS.PHONE.FAX = '1-510-521-0369' # 32.5.5 {Exit} The EXIT statement is used to used to terminate a REXX procedure and return control to the operating system. The EXIT statement is not required at the end of a single source file containing a single REXX procedure. It is required at the end of the main procedure in a multi- procedure source file (RETURN may also be used). ... /* SINGLE SOURCE, SINGLE PROCEDURE */ ... ... /* EXIT NOT REQUIRED */ ... /* SINGLE SOURCE, MULTIPLE PROCEDURES */ ... CALL AAA ... CALL BBB ... EXIT /* REQUIRED (OR RETURN) */ AAA: ... RETURN BBB: ... RETURN # 32.5.6 {Prime Numbers Example} Asks the user for an upper limit and then displays prime numbers up to that limit. /* REXX PROCEDURE */ /* =================================== */ /* Author: CTC */ /* Date: 02-January-1996 */ /* Purpose:List prime numbers */ /* =================================== */ SAY /* clear the screen */ SAY 'What is the upper prime number?' PULL upper . DO WHILE (upper < 3) /* must be >= 3 */ SAY 'That is not appropriate try again' PULL upper . END /* DO WHILE */ SAY 'The number 1 is prime' SAY 'The number 2 is prime' DO candidate = 3 to upper by 2 /* check each number */ prime = 'YES' DO number = 3 to (candidate*0.5) by 2 IF (candidate % number) * number, == candidate THEN DO prime = 'NO' LEAVE END /* DO */ /* ENDIF */ END /* DO */ IF prime == 'YES' THEN SAY 'The number' candidate 'is prime' /* ENDIF */ END /* DO candidate */ # 32.5.7 {Coin Analysis Example} Asks the user for an amount in dollars and cents and then displays the number of each denomination of notes and coins required to make the amount. /* REXX PROCEDURE */ /* =================================== */ /* Author: CTC */ /* Date: 02-January-1996 */ /* Purpose:Coin & Note analysis */ /* =================================== */ /* Set up array of denominations */ denom.0 = 10 denom.1 = 100 /* $100 bill */ denom.2 = 50 /* $50 bill */ denom.3 = 20 /* $20 bill */ denom.4 = 10 /* $10 bill */ denom.5 = 5 /* $5 bill */ denom.6 = 1 /* $1 bill */ denom.7 = 0.25 /* Quarter */ denom.8 = 0.10 /* Dime */ denom.9 = 0.05 /* Nickle */ denom.10 = 0.01 /* Penny */ SAY /* clear the screen */ SAY 'What is the amount of cash?' PULL money . DO WHILE (money < 0.01) /* positive? */ SAY 'That is not appropriate try again' PULL money . END /* DO WHILE */ DO n = 1 to 10 while (money > 0.00) number = money % denom.n /* divide by each denomination */ IF number > 0 THEN SAY number 'lots of' denom.n /* ENDIF */ money = money - (number * denom.n) END /* DO n=1-10 */ # 32.6 {Other REXX commands} # 32.6.1 {Parameter Passing} Normally a REXX procedure is passed parameters at the same time it is invoked. For example via primary command, COMMAND ===> CMD MYREXX PARM(01/01/1996 USER01) The procedure needs to retrieve and validate the parameters. This is done using the ARG command. # 32.6.2 {Arguments} At the beginning of a REXX procedure which takes parameters the following code is commonly found: [PARSE] [UPPER] ARG title surname first extras The PARSE and UPPER statements we shall deal with later. The ARG statement puts parameter 1 into variable TITLE, parameter 2 into variable SURNAME, parameter 3 into variable FIRST, and any remaining parameters into variable EXTRAS. In practice any parameters to the right of those expected can be ignored by placing a period "." after the last variable. [PARSE] [UPPER] ARG title surname first . If no parameter was passed for a particular variable (and those to its right), it will have a null value. This can be detected using the LENGTH function on the var name. If the var is empty, "length" returns the value 0. # 32.6.3 {Modular Design} Complex REXX procedures benefit from being subdivided into separate units which perform discrete tasks. These tasks can be invoked by use of the CALL statement. ... CALL validate ... EXIT validate: /* validate a number to be numeric */ ... RETURN The name called refers to a label somewhere in the REXX procedure which contains the code you wish to be executed. The label is identified as such by the use of a colon after the name. The RETURN statement returns control to the line after the call. All the variables available to the REXX procedure are available to the called module. In the example above we could pass a parameter to the routine when the call takes place: CALL validate prime_candidate ... EXIT validate: /* validate a number to be numeric */ ARG number ... RETURN In this example, the data contained in variable "prime_candidate" is set into variable "number" by the ARG statement. The module can communicate back to its calling routine using special variable RESULT. For example: CALL validate prime_candidate IF RESULT == 'Valid' THEN ... ELSE ... /* ENDIF */ ... EXIT validate: /* validate a number to be numeric */ ARG number ... RETURN answer /* set to Valid or Invalid */ The CALL statement can also be used to invoke a REXX built-in function or another REXX procedure. The order in which calls are evaluated follows: First, is it a Label in this procedure? Second, is it a REXX built-in function? Third, is it an external REXX function? # 32.6.4 {Sum the Values Example} This REXX procedure takes three separate values, validates them to be numeric, and in the range 0 to 100. If any is invalid, an error message is issued. Otherwise their total value is computed and displayed. /* REXX PROCEDURE */ /* ====================================== */ /* Author: CTC */ /* Date: 01-January-1996 */ /* Purpose:Validate and sum three values */ /* ====================================== */ TRACE ?A ARG val1 val2 val3 . FAILED = 'FALSE' CALL validate(val1 '1') IF RESULT == 'Error' THEN FAILED = 'TRUE' /* ENDIF */ CALL validate(val2 '2') IF RESULT == 'Error' THEN FAILED = 'TRUE' /* ENDIF */ CALL validate(val3 '3') IF RESULT == 'Error' THEN FAILED = 'TRUE' /* ENDIF */ IF FAILED == 'TRUE' THEN SAY 'Errors found' ELSE SAY 'Total =' val1+val2+val3 /* ENDIF */ EXIT /* Validate */ validate: ARG number position IF (LENGTH(number) == 0) THEN DO SAY 'Variable' position 'is not supplied' answer = 'Error' RETURN answer END /* DO */ /* ENDIF */ IF (DATATYPE(number,'N')) == 0 THEN DO SAY 'Variable' position 'is not numeric ...' number answer = 'Error' RETURN answer END /* DO */ /* ENDIF */ RETURN 'OK' # 32.7 {Parsing Parameters and Variables} # 32.7.1 {PARSE ARG} The PARSE command lets you control the way data is presented to the REXX procedure. We have already seen ARG. Now lets look at another way to retrieve parameters. When we say ARG, we are really saying PARSE UPPER ARG. SPF primary command: COMMAND ===> CMD NAME PARM(Mr Jones Llewellyn) REXX procedure: ... ARG title surname first . gives var values: title MR surname JONES first LLEWELLYN ... PARSE ARG title surname first . gives var values: title Mr surname Jones first Llewellyn # 32.7.2 {PARSE PULL} Similar to ARG, PULL is the same as saying PARSE UPPER PULL. Data retrieved by a plain PULL statement is converted to uppercase. Using PARSE in front of pull retrieves the parameters "as is": PARSE PULL title surname first # 32.7.3 {PARSE VAR} Is a powerful way of manipulating data. For example, if we wish to find the parts of a filename, we could say: filename = 'C:\SPFPRO\SPFPROW.EXE' PARSE VAR filename drive '\' directory '\' name '.' extension This statement parses var "filename" as follows: * 'C:' is put into variable 'drive' * 'SPFPRO' is put into variable 'directory' * 'SPFPROW' is put into variable 'name' * 'EXE' is put into variable 'extension' # 32.8 {Reading and Writing Files} You can read and write files record by record with LINEIN and LINEOUT functions. You can read and write files byte by byte with CHARIN and CHAROUT functions. These functions have fairly complex behavior so we will not attempt to explain them here. Please see the reference section for a detailed discussion of the I/O functions. Simplified examples of typical use follow: filename = 'hamlet.txt' ... record = LINEIN(filename) /* read next record */ ... char = CHARIN(filename) /* read next char */ ... call LINEOUT(filename,record) /* write next record */ ... call CHAROUT(filename,char) /* write next character */ The CHARIN and CHAROUT functions can read or write more than a single character on per call: rec = CHARIN(filename,80) /* read eighty characters */ ... call CHAROUT(filename,rec) /* write string "rec" */ # 32.8.1 {I/O Examples} /* REXX PROCEDURE */ /* ===================================== */ /* This procedure reads a file and */ /* writes records with a date of */ /* 01-01-1996 in positions 71 - 80 to */ /* another file. It then updates the */ /* date to 31-12-1996 on the original */ /* file. */ /* ===================================== */ trace ?a SAY 'Please enter the input file name' PULL input_file_name . DO WHILE ( LINES(input_file_name) = 0 ) SAY 'File name' input_file_name SAY 'not found - enter another one' PULL input_file_name . END /* DO WHILE */ CALL LINEOUT input_file_name /* close input file */ SAY 'Please enter the output file name' PULL output_file_name . DO WHILE ( LINES(output_file_name) = 0 ) SAY 'File name' output_file_name SAY 'not found - enter another one' PULL output_file_name . END /* DO WHILE */ CALL LINEOUT output_file_name /* close output file */ in_count = 0 out_count = 0 input_record = LINEIN(input_file_name) DO WHILE ( LINES(input_file_name) > 0 ) in_count = in_count + 1 IF (substr(input_record,71,10) = '01-01-1996') THEN DO out_count = out_count + 1 output_record = input_record input_record = substr(input_record,1,70), ||'31-12-1996' call LINEOUT output_file_name,output_record,out_count call LINEOUT input_file_name,input_record,IN_count END /* ENDIF */ input_record = LINEIN(input_file_name) END /* DO WHILE */ CALL LINEOUT output_file_name /* close output file */ CALL LINEOUT input_file_name /* close input file */ say 'Input records found = ' in_count say 'Input records processed = ' out_count # 32.9 {Debugging REXX Procedures} The trace utility provides an excellent debugging and diagnostic tool when developing REXX procedures. It enables the execution path to be followed, variables to be examined and modified, and ad hoc insertion of extra lines of code to aid in testing your application. # 32.9.1 {Tracing REXX Processing} The Trace function has a number of options which can be specified. These are: TRACE A /* TRACE ALL CLAUSES */ TRACE C /* TRACE COMMANDS */ TRACE E /* TRACE ERRORS */ TRACE F /* TRACE FAILURE */ TRACE I /* TRACE INTERMEDIATES */ TRACE L /* TRACE LABELS */ TRACE N /* TRACE NORMAL */ TRACE O /* TRACE OFF */ TRACE R /* TRACE RESULTS */ TRACE S /* TRACE SCAN */ The trace option can be preceded by a "?" which enables interactive tracing (see below). # 32.9.2 {Trace Output} The output from a trace session looks like this: nn ccc DO WHILE (position <= LENGTH(filename)) Where: nn Represents the line number of the REXX statement being executed. ccc The next three characters identify the trace line as one of the following: *-* source code +++ trace message >>> result of an expression >.> value assigned to a placeholder >V> variable contents of a string >L> literal string >F> function call string >P> prefix operation string >O> operation on two terms string >C> compound variable string During interactive tracing, after each line of output the user can enter any valid REXX statement to be executed immediately. This enables, for example, variables to be modified with an assignment, variables to be queried with a SAY statement and execution to be terminated by the use of an explicit EXIT statement if, say, a loop is detected. If during testing of a procedure, a loop occurs and tracing is not active, pressing Control/Break interrupts the procedure, typing exit terminates the procedure. # 32.9.3 {Signalling Errors, Errortext and Sourceline} Making REXX procedures as "production quality" as other software is important. One aspect of this goal is error trapping and recovery. When an error of any type occurs, you can pass control to a module which does cleanup, issues a user friendly diagnostic message, and terminates the procedure. The SIGNAL command is used to trap errors in REXX procedures and pass control to a specified label. The SIGNAL command has several modes: SIGNAL ON ERROR /* goto label ERROR: if positive RC is returned */ SIGNAL ON FAILURE /* goto label FAILURE: if negative RC is returned */ SIGNAL ON HALT /* goto label HALT: if CTRL-BREAK is used */ SIGNAL ON NOVALUE /* goto label NOVALUE: if uninitialized var is used */ SIGNAL ON SYNTAX /* goto label SYNTAX if syntax error occurs */ What action can be taken if and when these errors occur? The REXX language provides a number of special variables which can be displayed in user written diagnostics. SAY RC /* DISPLAY THE RETURN CODE */ SAY ERRORTEXT(RC) /* DISPLAY ERROR MESSAGE RELATED TO RC */ SAY SIGL /* DISPLAY LINE NUMBER IN ERROR */ SAY SOURCELINE(SIGL) /* DISPLAY SOURCE LINE RELATED TO SIGL */ A typical REXX procedure with diagnostics might look like this: SIGNAL ON ERROR SIGNAL ON FAILURE SIGNAL ON SYNTAX ... ERROR: ERR_TYPE = 'error' CALL ALLERR FAILURE: ERR_TYPE = 'failure' CALL ALLERR SYNTAX: ERR_TYPE = 'syntax' CALL ALLERR ALLERR: SAY 'An unexpected' ERR_TYPE 'has occured.' SAY ERRORTEXT(RC) SAY 'RC(' || RC || ') LINE(' || SIGL || ')' SOURCELINE(SIGL) EXIT We did not conclude the ERROR, FAILURE, and SYNTAX functions with EXIT because the common error routine does the EXIT which terminates the entire REXX procedure. # 33. {REXX Intrinsic Instructions} In each instruction description we provide the primary use for the instruction followed by the syntax specification, a description of the parameters, and finally some examples of use. # 33.1 {ADDRESS} Temporarily or permanently changes the command processing environment for external commands issued from a REXX procedure. The environment is an external environment such as ISPEXEC, ISREDIT, or the Operating System. SYNTAX: ADDRESS [VALUE] [ENVIRONMENT] [COMMAND] PARAMETERS: VALUE If the environment parameter is specified as a var, "VALUE" must be specified to gate evaluation of the variable. environment Specifies a symbol or literal string identifying the external environment. Valid values are CMD for operating system commands, ISPEXEC for dialog manager commands, and ISREDIT for edit macro commands. command Specifies a command to be executed in the specified environment. If no parameters are specified, future commands are routed to the previous environment. EXAMPLE: ENV = "CMD" ADDRESS /* RETURN TO PREV ENVIRONMENT */ ADDRESS CMD 'DIR' /* SEN DIR CMD TO OPERATING SYSTEM */ ADDRESS ISPEXEC /* ROUTE CMDS TO DIALOG MANAGER */ ADDRESS ISREDIT /* ROUTE CMDS TO EDIT MACRO PROCESSOR */ ADDRESS VALUE ENV /* ROUTE CMDS TO ENV IN VAR "ENV" */ # 33.2 {ARG} Is short hand notation for PARSE UPPER ARG. SYNTAX: ARG [TEMPLATE] In the normal case, you specify one or more var names to receive tokens from a parameter list. More complex parsing rules may be applied under the control of "template" as described in the PARSE instruction. EXAMPLE: ARG RUN_DATE USER_ID # 33.3 {CALL} Passes control to an internal or external routine or to a built-in function. SYNTAX: CALL NAME [ARG1, ARG2, ..., ARGN] PARAMETERS: name Specifies the name of an internal or external REXX procedure to be invoked. External REXX procedures have a file name in the form "name.ISP". arg Specifies one or more arguments separated by commas. EXAMPLE: CALL PRINT_BODY FILE_NAME,FIRST_PAGE,"CTC" CALL LINEOUT FILE_NAME,DETAIL_LINE,N # 33.4 {DO} Along with END, encloses a block of logically related code. The code can be executed once or a number of times and the number of iterations can be controlled by count or by complex logical expressions. SYNTAX: DO [ITERATION] [CONDITION] ...ACTION... END PARAMETERS: iteration Specifies an iteration control in one of the following forms: number Specifies a literal number, a var containing a number, or an expression that evaluates to a number. FOREVER The loop is performed until a LEAVE instruction is processed. var=num [TO num] [BY num] [FOR num] A var "var" is loaded with "num", and then auto-incremented by the "BY" number. The loop terminates when var reaches or exceeds the "TO" number. The loop also terminates if the number of iterations performed reaches the "FOR" number. In all cases "num" may be a literal number, a var containing a number, or an expression that evaluates to a number. condition Specifies a test to be performed before or after each execution of the loop. The WHILE test is performed BEFORE the loop executes. The UNTIL test is performed AFTER the loop executes. The test to be performed is any expression which evaluates to a TRUE or FALSE state. EXAMPLE: DO /* DO ONCE */ DO 10 /* DO 10 TIMES */ DO V1 /* DO NUMBER OF TIMES IN "V1" VAR */ /* DO 10 TIMES, AUTO-INCREMENT "I" BY 1 */ DO I = 1 TO 10 /* DO 10 TIMES, AUTO-INCREMENT "I" BY 5 */ DO I = 0 TO 50 BY 5 /* DO TIMES FROM "N" TO "M" BY "P", OR "R" ITERATIONS WHICHEVER COMES FIRST */ DO I = N TO M BY P FOR R /* TEST CONDITION BEFORE EACH ITERATION, CONTINUE IF "N" GREATER THAN 50 */ DO WHILE N > 50 /* TEST CONDITION AFTER EACH ITERATION, CONTINUE IF "N" LESS THAN 50 */ DO UNTIL N < 50 # 33.5 {DROP} Restores listed variables to an uninitialized state. SYNTAX: DROP VAR1 [VAR2 ... VARN] PARAMETERS: var Specifies on or more var names to be reset to an uninitialized state. EXAMPLE: DROP RUN_DATE USER_ID # 33.6 {EXIT} Returns to the calling module unconditionally. An optional value can be set into special variable RESULT in the calling program. SYNTAX: EXIT [VALUE] PARAMETERS: value Specifies a literal or variable to be set into special variable RESULT in the calling program. EXAMPLE: EXIT /* EXIT, RESULT IS NOT SET */ EXIT 'OK' /* EXIT, SET RESULT = "OK" */ EXIT ANSWER /* EXIT, SET RESULT = VALUE OF VAR "ANSWER" */ # 33.7 {IF} Controls program flow between one or two alternatives. Control flow is determined by evaluating a conditional expression which is part of the IF command syntax. SYNTAX: IF CONDITION THEN ...TRUE CLAUSE... /* ENDIF */ IF CONDITION THEN ...TRUE CLAUSE... ELSE ...FALSE CLAUSE... /* ENDIF */ PARAMETERS: condition Any valid expression which evaluates to a logical TRUE or FALSE state (1 or 0). EXAMPLE: IF COUNT > 50 THEN CALL LINEOUT PRINTER_FILE,HEADING /* ENDIF */ IF RC = 0 THEN SAY 'FINISHED OK' ELSE DO SAY 'ERROR IN PROCESSING' SAY 'RETURN CODE = ' RC SAY 'RECORD NUMBER =' COUNT END /* ENDIF */ # 33.8 {INTERPRET} Allows a REXX command to be created dynamically as a built up string and then executed. SYNTAX: INTERPRET VALUE PARAMETERS: value Specifies any valid string expression which evaluates to a valid REXX expression, instruction, or external command. EXAMPLE: COMMAND = 'X = X + ' MONTH||'_TOTAL'; INTERPRET COMMAND # 33.9 {ITERATE} Is used to force the restart of a DO loop from the beginning of the loop without executing the remainder of the code in the loop. SYNTAX: ITERATE [VARIABLE] PARAMETERS: variable Specifies the control variable for a specific iterating loop that is to be restarted. If not specified, the loop containing the iterate statement is restarted. EXAMPLE: DO COUNTER ... ... DO WHILE A > B ... ... IF ... THEN ITERATE /* RESTART "A > B" LOOP */ ... ... IF ... THEN ITERATE COUNTER /* RESTART "COUNTER" LOOP */ ... ... END ... ... END # 33.10 {LEAVE} Is used to force termination of a DO loop without executing the remainder of the code in the loop. SYNTAX: LEAVE [VARIABLE] PARAMETERS: variable Specifies the control variable for a specific iterating loop that is to be terminated. If not specified, the loop containing the iterate statement is terminated. EXAMPLE: DO COUNTER ... ... DO WHILE A > B ... ... IF ... THEN LEAVE /* TERMINATE "A > B" LOOP */ ... ... IF ... THEN LEAVE COUNTER /* TERMINATE "COUNTER" LOOP */ ... ... END ... ... END # 33.11 {NOP} Is a REXX instruction which has no effect, in essence a placeholder to improve code readability especially when used in conjunction with SELECT statements. SYNTAX: NOP PARAMETERS: None. EXAMPLE: SELECT WHEN ... THEN ...DO SOMETHING... WHEN ... THEN NOP /* DO NOTHING */ WHEN ... THEN ...DO SOMETHING... WHEN ... THEN ...DO SOMETHING... WHEN ... THEN NOP /* DO NOTHING */ WHEN ... THEN ...DO SOMETHING... OTHERWISE ...DO SOMETHING... END # 33.12 {NUMERIC} Alters the behavior of the operations which involve numeric data items. It has three forms: * DIGITS, alters the behavior of arithmetic precision * FORM, alters the format of exponential notation * FUZZ, alters the precision for comparison operations SYNTAX: NUMERIC DIGITS [EXPRESSION] PARAMETERS: expression Specifies an integer or an expression which evaluates to an integer which is the number of digits of arithmetic precision. If not specified, 9 is assumed. SYNTAX: NUMERIC FORM [ SCIENTIFIC | ENGINEERING | [VALUE] EXPRESSION ] PARAMETERS: SCIENTIFIC Specifies that exponential notation data be presented in the form 0 <= X < 10 * E ** N In other words, it is represented as a number between 0 and 10. This is the default setting. ENGINEERING Specifies that exponential notation data be presented in the form 100 <= X < 1000 * E ** N In other words, it is represented as a number between 100 and 1000. [VALUE] expression An expression which evaluates to either the string SCIENTIFIC or the string ENGINEERING. The optional clause VALUE is only included if the string contains non-character values (for example a parenthesis) in the first character position. SYNTAX: NUMERIC FUZZ [EXPRESSION] PARAMETERS: expression Specifies an integer or an expression which evaluates to an integer which specifies the number of digits of precision that apply to arithmetic comparisons. If not specified, 9 is assumed. The value must be less than or equal to the value of NUMERIC DIGITS. EXAMPLE: NUMERIC DIGITS N+1 NUMERIC FORM SCIENTIFIC NUMERIC FORM ENGINEERING NUMERIC FORM VALUE '(SCIENTIFIC)' NUMERIC FUZZ DIGITS()-1 # 33.13 {OPTIONS} Not supported. # 33.14 {PARSE} Is used to parse data according to a specific template. SYNTAX: PARSE [UPPER] DATA [TEMPLATE] PARAMETERS: UPPER Specifies that the parsed values are to be set in upper case form after retrieval. If not specified, parsed values are retrieved "as is". data Specifies the source data for the parameter string. Specify one of: ARG Specifies that the source data for the parameter string is the input parameters to the REXX procedure. LINEIN Specifies that the source data for the parameter string is the next input line from the keyboard. (We recommend you use PULL instead, see below) PULL Specifies that the source data for the parameter string is the next input line from the keyboard. SOURCE Specifies that the source data for the parameter string is the environment. The values returned are: The operating system type: WINDOWS, OS2, or UNIX, The invokation type: COMMAND, FUNCTION, or SUBROUTINE. The fully qualified file name of the current REXX procedure. VALUE expression Specifies that the source data for the parameter string is the fully evaluated value of "expression". VAR name Specifies that the source data for the parameter string is the value of var "name". VERSION Specifies that the source data for the parameter string is the version information for the REXX interpreter. The version information consists of five values: NAME, LEVEL, DAY, MONTH, and YEAR. template Specifies variables and literals which form a "picture" of the data. The variables receive the tokens parsed out of "data". The literal values in the template are ignored. EXAMPLE: PARSE ARG RUN_DATE USER_ID After parsing input parameters to the REXX proc, var "run_date" contains parameter 1, and var "user_id" contains parameter 2. EXAMPLE: PARSE UPPER LINEIN IN_RECORD The keyboard is read, the resulting line is placed into var "in_record" in uppercase form. EXAMPLE: PARSE PULL USER_NAME The keyboard is read, the resulting line is placed "as is" into var "user_name". EXAMPLE: PARSE SOURCE ENV TYPE NAME After parsing the environment, var "env" contains "WINDOWS", var "type" contains "FUNCTION", and var "name" contains the procedure path an file name. EXAMPLE: PARSE VALUE DATE() WITH DAY ' ' MONTH ' ' YEAR After parsing date (e.g. 1 Jan 1996), var "day" contains "1", var "month" contains "Jan", and var "year" contains "1996". EXAMPLE: PARSE VAR PHONENUM AREA '-' NUM ' X' EXT After parsing var phonenum (e.g. 510-521-5900 x515), var "area" contains "510", var "num" contains "521-5900" and var "ext" contains "515". EXAMPLE: PARSE VERSION NAME LEVEL DD MMM YYYY After parsing the version information, var "name" contains "REXX/2", var "level" contains "1", var "dd" contains "01", var "mmm" contains "Jan", and var "yyyy" contains "1996". # 33.15 {PROCEDURE} Is used by internally called routines to make variables either private or public with respect to internal calling routines. SYNTAX: PROCEDURE [EXPOSE VARIABLE-LIST] In using PROCEDURE, there are three distinct cases: * Case 1: If "PROCEDURE" is NOT specified in an internally called routine, the called routine "sees" the caller's variables as if they were his own but the caller does not see the called routine's vars. The called routine may read or write the caller's vars at will; if altered, the altered value is seen by the caller upon return. Newly created vars in the called routine are NOT visible to the caller. * Case 2: If "PROCEDURE" with no operands is specified at the beginning of a called routine, all called routine vars have local scope. That is, if the called routine reads or writes a var using a name that appears in the calling routine, its initial value is "uninitialized" and on return, the caller's vars are unchanged. * Case 3: If "PROCEDURE EXPOSE ..." with a variable list is specified, the vars in the list are bilaterally visible: - vars created in the calling routine that appear in the list, can be read or written by the called routine - vars created in the called routine that appear in the list, can be read or written by the calling routine after return EXAMPLE: /* REXX */ A = 1000 B = 2000 C = 3000 SAY A B C D E /* FIRST SAY */ CALL ROUTINE1 SAY A B C D E /* THIRD SAY */ RETURN ROUTINE1: PROCEDURE EXPOSE C D E SAY A B C D E /* SECOND SAY */ C = 'CHARLIE' D = 'DELTA' E = 'ECHO' RETURN DISPLAYS: 1ST SAY: 1000 2000 3000 D E 2ND SAY: A B 3000 D E 3RD SAY: 1000 2000 CHARLIE DELTA ECHO # 33.16 {PULL} This is shorthand notation for PARSE UPPER PULL. # 33.17 {PUSH} Not supported. # 33.18 {QUEUE} Not supported. # 33.19 {RETURN} Returns control to the calling module unconditionally. An optional value can be returned to special variable RESULT in the calling program. If the call is implicit by virtue of the function being specified in an expression or on the right hand side of an assign, the returned value takes the place of the implicit call. In this case, RESULT is NOT set. SYNTAX: RETURN [VALUE] PARAMETERS: value Specifies a variable, expression, or literal to be set into special variable RESULT. EXAMPLE: ... CALL TESTER /* CALL FUNCTION EXPLICITLY */ IF RESULT = 'OK' THEN ...DO SOMETHING... ... ... V1 = TESTER /* CALL FUNCTION IMPLICITLY */ IF V1 = 'OK' THEN ...DO SOMETHING... ... EXIT TESTER: ... CODE = 'OK' ... RETURN CODE # 33.20 {SAY} Echoes variables and/or literals to the default output device, usually the TTY screen. SYNTAX: SAY VALUE PARAMETERS: value Specifies a variable, expression, or literal to be displayed on the TTY screen. If no variables/literals are displayed, a NULL string is sent which has the effect of clearing the screen. EXAMPLE: SAY /* CLEAR SCREEN */ SAY 'TOTAL NUMBER OF RECORDS =' COUNT SAY 'N =' K*J**2 # 33.21 {SELECT} Controls logic flow between multiple alternatives. Control is determined by evaluating conditional expressions which are part of the SELECT command syntax. EXAMPLE: SELECT WHEN CONDITION THEN ... SINGLE STATEMENT ... WHEN CONDITION THEN DO ... MULTIPLE STATEMENTS ... ... MULTIPLE STATEMENTS ... ... MULTIPLE STATEMENTS ... END /* DO */ WHEN ... THEN ... SINGLE STATEMENT ... OTHERWISE ... SINGLE STATEMENT ... END /* SELECT */ condition Specifies a conditional expression which evaluates to a logical TRUE or FALSE state (1 or 0). When a condition is TRUE, the statement or statements following THEN are performed. If none of the conditions specified in WHEN clauses are TRUE, the OTHERWISE clause is performed. EXAMPLE: SELECT WHEN COUNT > 50 THEN CALL LINEOUT PRINTER_FILE,HEADING WHEN COUNT > 100 THEN CALL LINEOUT PRINTER_FILE,TITLE END /* SELECT */ SELECT WHEN RC = 0 THEN SAY 'FINISHED OK' WHEN RC < 0 THEN DO SAY 'ERROR IN PROCESSING' SAY 'RETURN CODE = ' RC SAY 'RECORD NUMBER = ' COUNT END OTHERWISE DO SAY 'WARNINGS ISSUED' SAY 'RETURN CODE = ' RC END END /* SELECT */ # 33.22 {SIGNAL} Is used to trap errors occuring during the execution of a REXX procedure. Signal is used in one of three forms: SYNTAX: SIGNAL ON|OFF ERROR-TYPE [FUNCTION] SIGNAL LABEL SIGNAL VALUE EXPRESSION PARAMETERS: ON|OFF Specifies whether error trapping for a particular type is to be set on or off. error-type The types of events which can be signalled are: - ERROR, if an instruction returns a non-zero return code - FAILURE, if an external command returns a non-zero return code - HALT, if the procedure is interrupted by an external process (CTRL- BREAK) - NOVALUE, if a variable is used whose value has not been set prior to use - SYNTAX, if a syntax error is found in the REXX code at run time. function Specifies the name of a function to receive control when the ON condition occurs. If not specified, control passes directly to the routine with the same name as the error type. For example, a syntax error would pass control to routine SYNTAX:. label Specifies a label in the current REXX procedure to which unconditional control is passed. VALUE expression Specifies an expression which evaluates to a label in the current REXX procedure to which unconditional control is passed. EXAMPLE: SIGNAL ON ERROR SIGNAL OFF FAILURE SIGNAL ON HALT SIGNAL OFF NOVALUE SIGNAL ON SYNTAX ... ... ...REST OF PROCEDURE... ... ... RETURN ERROR: ...CLEANUP AS REQUIRED... ...ISSUE DIAGNOSTICS... ...SET ABNORMAL END EXIT CONDITIONS... IF RECOVERABLE THEN RETURN ELSE /* NOT RECOVERABLE */ EXIT HALT: ...SIMILAR TO ERROR ROUTINE... SYNTAX: ...SIMILAR TO ERROR ROUTINE... ANOTHER USE: ... ... VECTOR = 'CMD_FIND' ... ... CALL DISPATCH(VECTOR) ... ... RETURN DISPATCH: ARG VECTOR . SIGNAL VALUE VECTOR RETURN # 33.23 {TRACE} Is used to debug REXX procedures. The options specified control the level of information displayed and the amount of interaction you have with the procedure. SYNTAX: TRACE MODE TRACE [VALUE] EXPRESSION PARAMETERS: mode Specifies one of the following values: A trace all REXX statements C trace all external commands E trace only commands that result in ERROR or FAILURE F trace only commands that result in FAILURE I trace all intermediate states of REXX commands L trace all labels encountered during execution N same as F O trace off, nothing is traced R trace all results before and after evaluated expressions S trace commands in scan mode, trace but don't execute Interactive tracing is controlled by placing a question mark before the mode specification. For example, "?A" says trace all statements interactively. If you re-specify the question mark, it toggles the interactive state. [VALUE] expression Specifies an expression or variable which evaluates to a trace mode. In the default case, tracing is non-interactive. That is, trace information is displayed continuously on the TTY screen without interruption as the REXX procedure executes. In interactive mode, REXX processing is suspended after each clause is traced and you are given the opportunity to directly interact with the procedure under trace. You can enter any valid REXX statement just as if it was part of the original program. EXAMPLE: TRACE A TRACE ?C TRACE VALUE QUERY||TYPE TRACE E TRACE ?F TRACE I TRACE ?L TRACE N TRACE ?O TRACE R TRACE ?S # 34. {REXX Built-in Functions} REXX contains many useful built-in functions. These functions perform various searching, processing, comparison, and conversion operations for both text and numbers. Other built-in functions provide formatting capabilities and arithmetic operations. Some functions return a text value, some return a numerical value and some return a logical value. The logical values returned are 1 and 0 representing TRUE and FALSE respectively. # 34.1 {ABBREV} Tests whether a short string is exactly equal to the first part of a longer string. Returns 0 for FALSE, 1 for TRUE. SYNTAX: ABBREV(LONG-STRING,SHORT-STRING[,MIN-LENGTH]) PARAMETERS: long-string Specifies a string which represents the longest value expected for the comparison. short-string Specifies a string to be compared to the long-string. min-length Specifies the minimum acceptable length for the tested string. If not specified, 1 is assumed. EXAMPLE: IF ABBREV("CHANGE",VERB,2) == 1 THEN /* ACCEPTS (CH, CHA, CHAN, CHANG, CHANGE */ # 34.2 {ABS} Returns the absolute value of a number without a sign. SYNTAX: ABS(EXPRESSION) PARAMETERS: expression Specifies any REXX expression which evaluates to a number. EXAMPLE: ABS('-1.23') /* RETURNS 1.23 */ ABS('+1.23') /* RETURNS 1.23 */ # 34.3 {ADDRESS} Returns the current external command processing environment. SYNTAX: ADDRESS() EXAMPLE: ENV = ADDRESS() /* RETURNS EXT CMD PROCESSOR NAME */ # 34.4 {ARG} Returns information about the parameters passed to a function. In the default context, parameters are delimited by BLANK. SYNTAX: ARG([NUMBER[,EXIST]]) PARAMETERS: number Specifies the number of a specific parameter to be retrieved. If no number is specified, the total number of parameters is returned. exist If "E" is specified, returns 1 if Nth parameter exists, 0 if not. If "O" is specified, returns 1 if Nth parameter does not exist (was ommited), 0 if not. EXAMPLE: EXIST = ARG(5,E) /* RETURNS EXIST STATE OF PARM 5 */ OMMITED = ARG(7,O) /* RETURNS OMITTED STATE OF PARM 7 */ TOTAL_PARMS = ARG() /* RETURNS NUMBER OF PARAMETERS */ DO I = 1 TO TOTAL_PARMS CUR_PARM = ARG(I) /* RETURNS NEXT PARM */ ... ... END # 34.5 {BITAND} Returns a string composed of two input strings logically ANDed together at the bit level. SYNTAX: BITAND(STRING1,STRING2[,PAD]) PARAMETERS: string1 The first of two strings to be ANDed together. string2 The second of two strings to be ANDed together. pad Specifies a character to be used to pad the shorter of the two strings if necessary. The default "pad" character is 'FF'x. The pad character is added to the right of the shorter string. EXAMPLE: BITAND('1C'X,'38'X) /* RETURNS '18'X */ BITAND('1C'X,'38A5'X) /* RETURNS '18A5'X */ BITAND('1C'X,'38A5'X,'00'X) /* RETURNS '1800'X */ # 34.6 {BITOR} Returns a string composed of two input strings inclusive ORed together at the bit level. SYNTAX: BITOR(STRING1,STRING2[,PAD]) PARAMETERS: string1 The first of two strings to be ORed together. string2 The second of two strings to be ORed together. pad Specifies a character to be used to pad the shorter of the two strings if necessary. The default "pad" character is 'FF'x. The pad character is added to the right of the shorter string. EXAMPLE: BITAND('1C'X,'38'X) /* RETURNS '3C'X */ BITAND('1C'X,'38A5'X) /* RETURNS '3CA5'X */ BITAND('1C'X,'38A5'X,'00'X) /* RETURNS '3C00'X */ # 34.7 {BITXOR} Returns a string composed of two input strings exclusive ORed together at the bit level. SYNTAX: BITXOR(STRING1,STRING2[,PAD]) PARAMETERS: string1 The first of two strings to be XORed together. string2 The second of two strings to be XORed together. pad Specifies a character to be used to pad the shorter of the two strings if necessary. The default "pad" character is '00'x. The pad character is added to the right of the shorter string. EXAMPLE: BITAND('1C'X,'38'X) /* RETURNS '24'X */ BITAND('1C'X,'38A5'X) /* RETURNS '24A5'X */ BITAND('1C'X,'38A5'X,'FF'X) /* RETURNS '2400'X */ # 34.8 {B2X} Converts a binary string to a hexadecimal string. SYNTAX: B2X(STRING) PARAMETERS: string Specifies a string of '0' and '1' characters representing a binary value. EXAMPLE: B2X('11000001') /* RETURNS 'C1' */ # 34.9 {CENTER (ALSO CENTRE)} Centers a string within a specified length. SYNTAX: CENTER(STRING,LENGTH[,PAD]) PARAMETERS: string Specifies a string of characters to be centered. length Specifies a length greater than the natural length of "string" within which centering is to be done. pad Specifies the character to use for padding on the left and right of the string. If not specified, BLANK is assumed. EXAMPLE: CENTER('APRIL',9) /* RETURNS ' APRIL ' */ CENTER('MAY', 9) /* RETURNS ' MAY ' */ CENTER('MAY', 9,'-') /* RETURNS '---MAY---' */ # 34.10 {CHARIN} Reads a string of characters from an input file. SYNTAX: CHARIN([FILE][,START_POS][,LENGTH]) PARAMETERS: file Specifies the name of an input file. If not specified, the keyboard is read. start_pos Specifies the position of the first character to be read. If not specified, reading proceeds (or continues) from the current position. length Specifies the number of characters to read. If not specified, 1 is assumed. Also see: LINEIN, LINEOUT, and STREAM. EXAMPLE: /* ASSUME A FILE WITH FIXED LENGTH RECORDS OF 80 BYTES */ RECLEN = 80 /* SET RECORD LENGTH */ FNAME = 'PROG1.COB' /* SET FILE NAME */ CHARIN(FNAME,1,0) /* OPEN FILE */ RECORDS = CHARS(FNAME) / RECLEN /* NUMBER OF WHOLE RECORDS */ DO I = 1 TO RECORDS /* READ TO EOF */ REC = CHARIN(FNAME,,RECLEN) /* GET NEXT RECORD */ ...PROCESS RECORD... /* PROCESS THE RECORD */ END # 34.11 {CHAROUT} Writes a string of characters to an output file. SYNTAX: CHAROUT([FILE,]STRING[,START_POS]) PARAMETERS: file Specifies the name of an output file. If not specified, the string is written to the TTY screen. string Specifies the string to be written. start_pos Specifies the position of the first character to be written. If not specified, the string is written to the current position in the data stream. Also see: LINEIN, LINEOUT, and STREAM. EXAMPLE: /* ASSUME A PHONE BOOK WITH FIXED FIELDS */ NAME_LAST_LEN = 16 NAME_FIRST_LEN = NAME_LAST_LEN NAME_MID_LEN = NAME_LAST_LEN STREETLEN = 32 EXTLEN = 4 FNAME = 'PHONE.TXT' /* OUTPUT FILE NAME */ CHAROUT(FNAME,,1) /* OPEN FILE */ ENTRIES = PHONEBOOK.0 /* GET TOTAL NUMBER OF ENTRIES */ DO I = 1 TO ENTRIES /* PUBLISH PHONE BOOK */ /* RETRIEVE FIELD AND PAD TO FIXED LENGTH */ FIELD = LEFT(PHONE.I.NAME_LAST,NAME_LAST_LEN) CHAROUT(FNAME,FIELD); /* WRITE PADDED FIELD */ FIELD = LEFT(PHONE.I.NAME_FIRST,NAME_FIRST_LEN) /* MAKE FIXED 16 */ CHAROUT(FNAME,FIELD); FIELD = LEFT(PHONE.I.NAME_MID,NAME_MID_LEN) /* MAKE FIXED 16 */ CHAROUT(FNAME,FIELD); FIELD = LEFT(PHONE.I.STREET,STREETLEN) CHAROUT(FNAME,FIELD); CHAROUT(FNAME,PHONE.I.STATE); /* ALWAYS FULL WIDTH AT 2 */ CHAROUT(FNAME,PHONE.I.ZIP); /* ALWAYS FULL WIDTH AT 5 */ CHAROUT(FNAME,PHONE.I.AREA); /* ALWAYS FULL WIDTH AT 3 */ CHAROUT(FNAME,PHONE.I.NUMBER); /* ALWAYS FULL WIDTH AT 7 */ FIELD = LEFT(PHONE.I.EXT,EXTLEN); CHAROUT(FNAME,FIELD); END # 34.12 {CHARS} Returns the number of unread characters remaining in an input file. SYNTAX: CHARS([FILE]) PARAMETERS: file Specifies the name of an input file. The default is the keyboard. EXAMPLE: CHARS() /* RETURNS 0 */ CHARS('C:\HAMLET.TXT') /* RETURNS 60439 */ # 34.13 {COMPARE} Compares two strings. Returns 0 if the strings are the same. If they are not the same, returns the position of the first different character. SYNTAX: COMPARE(STRING1,STRING2[,PAD]) PARAMETERS: string1 The first of two strings to be compared. string2 The second of two strings to be compared. pad Specifies a pad character. If one of the strings is shorter than the other, it is padded on the right before the comparison is made. If not specified, BLANK is assumed. EXAMPLE: COMPARE('TO BE','TO BE') /* RETURNS 0 */ COMPARE('TO BE','TO BE ') /* RETURNS 0 */ COMPARE('TO BEE','TO BE') /* RETURNS 6 */ # 34.14 {CONDITION} Returns information about the current error trap condition. SYNTAX: CONDITION([TYPE]) PARAMETERS: type Specify one of: C - the name of the condition (e.g. SYNTAX) D - description of the condition (e.g. Syntax test) I - the conditioning instruction (CALL or SIGNAL) S - the condition state (ON, OFF, or DELAY) If no type is specified, 'I' is assumed. EXAMPLE: CONDITION() /* RETURNS CONDITION INSTRUCTION */ CONDITION('I') /* RETURNS CONDITION INSTRUCTION */ CONDITION('C') /* RETURNS CONDITION NAME */ # 34.15 {COPIES} Returns a string concatenated to itself to produce a specific number of copies. SYNTAX: COPIES(STRING,NUMBER) PARAMETERS: string Specifies the string to be copied. number Specifies the number of copies. EXAMPLE: COPIES('ABC',3) /* RETURNS 'ABCABCABC' */ # 34.16 {C2D} Returns the decimal value of a string. SYNTAX: C2D(STRING) PARAMETERS: string Specifies the string to be converted. EXAMPLE: C2D('A') /* RETURNS 193 */ C2D('1C'X) /* RETURNS 28 */ C2D('0001 1100'B) /* RETURNS 28 */ # 34.17 {C2X} Returns a char string of hex digits representing the input character string. SYNTAX: C2X(STRING) PARAMETERS: string Specifies the string of characters to be converted. EXAMPLE: C2X('ABC') /* RETURNS STRING 'C1C2C3' */ C2X('1CA2'X) /* RETURNS STRING '1CA2' */ C2X('0001 1100'B) /* RETURNS STRING '1C' */ # 34.18 {DATATYPE} Returns data type, or TRUE/FALSE on data type test. SYNTAX: DATATYPE(VARIABLE[,TYPE]) PARAMETERS: variable Specifies the variable whose contents are to be tested. type Specifies specific data type to be tested. If the test var matches the type, returns 1 (TRUE), otherwise returns 0 (FALSE). Types are: A - alphanumeric (no punc) B - binary (only 0 or 1) L - lower case (only lower) M - mixed case (no numbers or punc) N - number (only numbers) S - symbol (only var chars) U - upper case (only upper) W - whole number (only whole) X - hexadecimal (only hex digits) If type is not specified, returns either 'NUM' or 'CHAR'. EXAMPLE: DATATYPE('TO BE OR NOT') /* RETURNS 'CHAR' */ DATATYPE('123') /* RETURNS 'NUM' */ DATATYPE('ALPHANUM 99','A') /* RETURNS 1 */ DATATYPE('ALPHANUM !!','A') /* RETURNS 0 */ DATATYPE('00011100', 'B') /* RETURNS 1 */ DATATYPE('00115500', 'B') /* RETURNS 0 */ DATATYPE('ABCDEF', 'L') /* RETURNS 0 */ DATATYPE('ABCDEF', 'M') /* RETURNS 1 */ DATATYPE('5BCDEF', 'M') /* RETURNS 0 */ DATATYPE('999', 'N') /* RETURNS 1 */ DATATYPE('A99', 'N') /* RETURNS 0 */ DATATYPE('ABCDEF', 'S') /* RETURNS 1 */ DATATYPE('#BCDEF', 'S') /* RETURNS 0 */ DATATYPE('ABCDEF', 'U') /* RETURNS 1 */ DATATYPE('ABCDEF', 'U') /* RETURNS 0 */ DATATYPE('9999', 'W') /* RETURNS 1 */ DATATYPE('99.0', 'W') /* RETURNS 1 */ DATATYPE('999.', 'W') /* RETURNS 1 */ DATATYPE('99.9', 'W') /* RETURNS 0 */ DATATYPE('1CA2', 'X') /* RETURNS 1 */ DATATYPE('HCA2', 'X') /* RETURNS 0 */ # 34.19 {DATE} Returns the local date in many different formats. SYNTAX: DATE([TYPE]) PARAMETERS: type Specifies the date format desired. One of: B - number of days from 01-01-0001 C - number of days from 01-01-1900 D - number of days from 01-01-current E - European format (dd/mm/yy) J - Julian format (yyddd) L - date by language (d m y) M - month in English (January) N - normal (default) (dd mmm yyyy) O - ordered format (yy/mm/dd) S - standard format (yyyymmdd) U - USA format (mm/dd/yy) W - day in English (Monday) EXAMPLE: DATE() /* RETURNS '01 FEB 1996' */ DATE('B') /* RETURNS 727959, */ DATE('C') /* RETURNS 34365, */ DATE('D') /* RETURNS 32, */ DATE('E') /* RETURNS '01/02/96', */ DATE('J') /* RETURNS 96032, */ DATE('L') /* RETURNS '1 FEBRUARY 1996' */ DATE('M') /* RETURNS 'FEBRUARY', */ DATE('N') /* RETURNS '1 FEB 1996, */ DATE('O') /* RETURNS '96/01/02', */ DATE('S') /* RETURNS 19960201, */ DATE('U') /* RETURNS '02/01/96, */ DATE('W') /* RETURNS 'SATURDAY,' */ # 34.20 {DELSTR} Deletes a sub-string from a string. SYNTAX: DELSTR(STRING,CHAR_POS[,NUMBER]) PARAMETERS: string Specifies the base string. char_pos Specifies the starting character position for the delete. number Specifies the number of characters to be deleted. If not specified, all characters from "char_pos" to end of string are deleted. EXAMPLE: DELSTR('TO BE OR NOT TO BE',6,7) /* RETURNS 'TO BE TO BE' */ DELSTR('TO BE OR NOT TO BE',6) /* RETURNS 'TO BE' */ # 34.21 {DELWORD} Deletes words from a string. SYNTAX: DELWORD(STRING,WORD_POS[,NUMBER]) PARAMETERS: string Specifies the base string. word_pos Specifies the word position of the first word to be deleted. number Specifies the number of words to delete. If not specified, all words from "word_pos" to end of string are deleted. EXAMPLE: DELWORD('TO BE OR NOT TO BE',3,2) /* RETURNS 'TO BE TO BE' */ DELWORD('TO BE OR NOT TO BE',3) /* RETURNS 'TO BE' */ # 34.22 {DIGITS} Returns the current value of NUMERIC DIGITS. SYNTAX: DIGITS() EXAMPLE: DIGITS() /* RETURNS CURRENT PRECISION (DEFAULT=9) */ # 34.23 {D2C} Returns the character value equivalent of a decimal value. SYNTAX: D2C(VALUE) PARAMETERS: value Specifies the decimal value to be converted. EXAMPLE: D2C(15) /* RETURNS '0F'X */ D2C(65) /* RETURNS 'A' */ D2C(126) /* RETURNS '~' */ # 34.24 {D2X} Returns the hex string equivalent of the decimal value. SYNTAX: D2X(VALUE) PARAMETERS: value Specifies the decimal value to be converted. EXAMPLE: D2X(15) /* RETURNS STRING '0F' */ D2X(64) /* RETURNS STRING '40' */ D2X(255) /* RETURNS STRING 'FF' */ # 34.25 {ERRORTEXT} Returns the REXX error message associated with a particular error number. The error number is normally set in special variable RC after a SYNTAX error. (see SIGNAL and CONDITION) SYNTAX: ERRORTEXT(ERR_NUMBER) PARAMETERS: err_number Specifies the error message number. EXAMPLE: ERRORTEXT(RC) /* RETURNS THE ERROR TEXT FOR VALUE IN RC) # 34.26 {FORM} Returns the current value of NUMERIC FORM. SYNTAX: FORM() EXAMPLE: FORM() /* RETURNS SCIENTIFIC OR ENGINEERING */ # 34.27 {FORMAT} Formats a number to a specified number of decimal places. SYNTAX: FORMAT( NUMBER [,DIGITS_BEFORE] [,DIGITS_AFTER] [,DIGITS_EXPONENT] [,WHEN_EXPONENT] ) PARAMETERS: number Specifies the number to be formatted. digits_before Specifies a fixed number of character positions before the decimal point. The default is the natural width of the integer portion of the number. digits_after Specifies a fixed number of character positions after the decimal point. The default is 0. digits_exponent Specifies the number of character positions occupied by the exponent part if exponential notation is used. when_exponent Specifies the point at which exponential notation should be used. EXAMPLE: FORMAT('1', 6,2) /* RETURNS ' 1.00' */ FORMAT('1.23',2,1) /* RETURNS ' 1.2' */ FORMAT('5.67',2,0) /* RETURNS ' 6' */ FORMAT('5.67',0) /* RETURNS 0.567E1 */ # 34.28 {FUZZ} Returns the current value of NUMERIC FUZZ. SYNTAX: FUZZ() EXAMPLE: FUZZ() /* RETURNS CURRENT PRECISION (DEFAULT=0) */ # 34.29 {INSERT} Inserts a string into another string. SYNTAX: INSERT(SOURCE,TARGET[,POSITION][,LENGTH][,PAD]) PARAMETERS: source Specifies the string to be inserted. target Specifies the string to be inserted into. position Specifies the character position at which the insert is to begin. If not specified, the insert string is prepended to the target string. length Specifies the length of the string to be inserted. If not specified, the natural length of the insert string is used. pad Specifies the character to use to pad the inserted string if it less than "length". If not specified, BLANK is assumed. EXAMPLE: INSERT('OR NOT ','TO BE TO BE',7) /* RETURNS 'TO BE OR NOT TO BE' */ INSERT('OR NOT ','TO BE TO BE') /* RETURNS 'OR NOT TO BE TO BE' */ # 34.30 {LASTPOS} Scans a string from right to left looking for a particular substring. If the substring is found, returns its position. Otherwise returns 0. SYNTAX: LASTPOS(LITTLE_STRING,BIG_STRING[,START_POS]) PARAMETERS: little_string Specifies the string to be found. big_string Specifies the string to be searched. start_pos Specifies the character position a which to start the search. The search is from right to left. If not specified, the search begins at the end of "big_string". EXAMPLE: LASTPOS('BE','TO BE OR NOT TO BE') /* RETURNS 17 */ LASTPOS('BE','TO BE OR NOT TO BE',10) /* RETURNS 4 */ # 34.31 {LEFT} Returns a substring of string from position 1 for a specific length. SYNTAX: LEFT(STRING,LENGTH[,PAD]) PARAMETERS: string Specifies the base string. length Specifies the length of the result string. pad Specifies the character to pad the right of base string if it is shorter than length. If not specified, BLANK is assumed. EXAMPLE: LEFT('TO BE OR NOT',8) /* RETURNS 'TO BE OR' */ LEFT('TO BE",8) /* RETURNS 'TO BE ' */ LEFT('TO BE",8,'-') /* RETURNS 'TO BE---' */ # 34.32 {LENGTH} Returns the length of a string. SYNTAX: LENGTH(STRING) PARAMETERS: string Specifies the string whose length is to be returned. EXAMPLE: LENGTH('TO BE OR NOT TO BE') /* RETURNS 18 */ LENGTH('') /* RETURNS 0 */ # 34.33 {LINEIN} Reads one record from an input file. SYNTAX: LINEIN([FILE][,START_REC][,COUNT]) PARAMETERS: file Specifies the name of an input file. If not specified, the keyboard is read. start_rec Specifies the position of the record to be read. The only valid value for this parameter is 1. When 1 is specified, the first record is read. This is a convenient way of insuring that you are starting at the beginning of the file. count Specifies the number of records to read. The only valid values for this parameter are 0 and 1. If 0 is specified, the file is positioned to the beginning and no records are read (equivalent to "open file-name for read" in other languages). If not specified, 1 is assumed. To check for "END OF FILE" condition, use LINES function. Also see: CHARIN, CHAROUT, and STREAM. EXAMPLE: /* OPEN INPUT FILE AT START OF FILE, READ TO EOF */ FNAME = 'HAMLET.TXT' LINEIN(FNAME,1,0) /* OPEN FILE FOR READ */ DO WHILE LINES(FNAME) > 0 REC = LINEIN(FNAME) /* READ NEXT REC */ ...PROCESS RECORD... END /* DO */ # 34.34 {LINEOUT} Writes a record to an output file. Returns 0 if successful, 1 if not successful. SYNTAX: LINEOUT([FILE][,STRING][,REC_NUM]) PARAMETERS: file Specifies the name of an output file. If not specified, the line is written to the TTY screen. string Specifies the string to be written. If not specified, a null line is written. rec_num Specifies the record number of the record to be written. The only valid number for "rec_num" is 1. If "string" and "rec_num" are both omitted, the file is closed. If "string" is omitted, and "rec_num" is 1, the file is positioned at the beginning. If "string" is specified, and "rec_num" is not specified, the record is written at the current file position. If "string" has the value null (e.g. ''), only the "line end" character sequence is written to the file (a null line). Also see: CHARIN, CHAROUT, and STREAM. EXAMPLE: /* OPEN FOR WRITE, WRITE RECS, THEN CLOSE */ REC.1 = ...ONE... REC.2 = ...TWO... REC.3 = ...THREE... RECORDS = 3 FNAME = 'TEST.TXT' LINEOUT(FNAME,,1); /* OPEN FOR WRITE */ LINEOUT(FNAME,"START OF FILE") /* WRITE ONE RECORD */ LINEOUT(FNAME,'') /* WRITE A NULL LINE */ DO I = 1 TO RECORDS WRC = LINEOUT(FNAME,REC.I) /* WRITE ONE RECORD */ IF WRC = 1 THEN DO SAY 'ERROR WRITING RECORD' I /* ERROR ON WRITE */ I = RECORDS /* END LOOP */ END /* IF */ END /* DO */ LINEOUT(FNAME,'') /* WRITE A NULL LINE */ LINEOUT(FNAME,"END OF FILE") /* WRITE ONE RECORD */ LINEOUT(FNAME); /* CLOSE OUTPUT FILE */ AFTER WRITING, FILE TEST.TXT CONTAINS: START OF FILE ...ONE... ...TWO... ...THREE... END OF FILE # 34.35 {LINES} Returns 1 (TRUE) if there are unread lines remaining in the input file. Otherwise, returns 0 (FALSE). Use this function to detect the "END OF FILE" condition when reading external files. SYNTAX: LINES([FILE]) PARAMETERS: file Specifies the name of an input file. If not specified, the keyboard is assumed. EXAMPLE: DO WHILE LINES(FNAME) > 0 /* DO WHILE RECORDS REMAIN */ REC = LINEIN(FNAME) /* READ NEXT REC */ ...PROCESS RECORD... END /* DO */ # 34.36 {MAX} Returns the largest number from a list of numbers. SYNTAX: MAX(NUMBER-LIST) PARAMETERS: number-list Specify two or more numbers separated by commas. EXAMPLE: MAX(2,4,10,12,6,8) /* RETURNS 12 */ # 34.37 {MIN} Returns the smallest number from a list of numbers. SYNTAX: MIN(NUMBER-LIST) PARAMETERS: number-list Specify two or more numbers separated by commas. EXAMPLE: MIN(6,8,2,4,10,12) /* RETURNS 2 */ # 34.38 {OVERLAY} Overlays one string onto another string. SYNTAX: OVERLAY(OVERLAY_STRING,BASE_STRING[,POSITION][,LENGTH][,PAD]) PARAMETERS: overlay_string Specifies the overlaying string. base_string Specifies the string to be overlayed. position Specifies the character position at which the overlay is to begin. If not specified, 1 is assumed. length Specifies the length of the overlay string. If not specified, the natural length of the overlay string is used. pad Specifies the pad character. There are two cases where the pad character comes into play: - If "overlay_string" is shorter than "length", "overlay_string" is padded on the right to "length". - If "position" is greater than the length of "base_string", "base_string" is padded on the right to "position". If the pad character is not specified, BLANK is assumed. EXAMPLE: OVERLAY('BE','TO US OR',4) /* RETURNS 'TO BE OR' */ OVERLAY('LONG','SHORT',10) /* RETURNS 'SHORT LONG' */ OVERLAY('X','SIGN: ',7,11,'_') /* RETURNS 'SIGN: X__________' */ # 34.39 {POS} Scans a string from left to right looking for a particular substring. If the substring is found, returns its position. Otherwise returns 0. SYNTAX: POS(LITTLE_STRING,BIG_STRING[,START_POS]) PARAMETERS: little_string Specifies the string to be found. big_string Specifies the string to be searched. start_pos Specifies the character position at which to start the search. The search is from left to right. If not specified, 1 is assumed. EXAMPLE: POS('BE','TO BE OR NOT TO BE') /* RETURNS 4 */ POS('BE','TO BE OR NOT TO BE',10) /* RETURNS 17 */ # 34.40 {QUEUED} Not supported. # 34.41 {RANDOM} Returns a random number from a range of numbers. (Note: degree of randomness varies depending on seed.) SYNTAX: RANDOM([MIN,]MAX[,SEED]) PARAMETERS: min Specifies the smallest random number to return. If not specified, 0 is assumed. max Specifies the largest random number to return. Max must be greater than min. If not specified, 999 is assumed. seed Specifies a number to seed the random number generator. Specifying the same initial seed causes the random number sequence to repeat. Conversely setting a random seed, in most cases will result in a random sequence. EXAMPLE: /* SET RANDOM TO DEAL CARDS * SEED = TIME('M') /* MINUTES SINCE MIDNIGHT */ RANDOM(1,52,SEED) /* INITIALIZE GENERATOR */ DO FOREVER CARD = RANDOM(1,52) /* PICK A CARD */ ... ...USE CARD SELECTED... ... END /* DO */ /* FOR DICE (SIX SIDES) */ RANDOM(1,6,SEED) /* INITIALIZE GENERATOR */ DIE = RANDOM(1,6) /* THROW A DIE */ # 34.42 {REVERSE} Reverses the order of characters in a string. SYNTAX: REVERSE(STRING) PARAMETERS: string Specifies the string to be reversed. EXAMPLE: REVERSE('ABCDEF') /* RETURNS 'FEDCBA' */ # 34.43 {RIGHT} Returns a substring of string from the right side for a specific length. SYNTAX: RIGHT(STRING,LENGTH[,PAD]) PARAMETERS: string Specifies the base string. length Specifies the desired length of the result string. pad Specifies the character to use to pad the left of result string if it is shorter than "length". If not specified, BLANK is assumed. EXAMPLE: RIGHT('OR NOT TO BE',5) /* RETURNS 'TO BE' */ RIGHT('TO BE',8) /* RETURNS ' TO BE' */ RIGHT('TO BE',8,'-') /* RETURNS '---TO BE' */ # 34.44 {SIGN} Returns the sign of the number. SYNTAX: SIGN(NUMBER) PARAMETERS: number Specifies the number whose sign is to be obtained. If the number is < 0, -1 is returned. If the number is > 0, 1 is returned. If the number is = 0, 0 is returned. EXAMPLE: SIGN(-7) /* RETURNS -1 */ SIGN(+7) /* RETURNS 1 */ SIGN(7) /* RETURNS 1 */ SIGN(0) /* RETURNS 0 */ # 34.45 {SOURCELINE} Returns the number of lines in the program, or a specific line. This function is primarily used for diagnostic purposes. Also see SIGNAL, CONDITION, and SIGL. SYNTAX: SOURCELINE([NUMBER]) PARAMETERS: number Specifies the number of a sourceline in the REXX procedure. If specified, the line data is returned. If not specified, the number of lines in the source file is returned. EXAMPLE: SOURCELINE() /* RETURNS NUMBER OF LINES */ SOURCELINE(237) /* RETURNS LINE 237 */ #34.46 {SPACE} Removes leading and trailing blanks. Replaces embedded blanks with 0 to N characters of "pad". SYNTAX: SPACE(STRING[,NUMBER][,PAD]) PARAMETERS: string Specifies the base string. number Specifies the number of "pad" characters to replace embedded blanks. pad Specifies the pad character. If not specified, BLANK is assumed. EXAMPLE: SPACE('TO BE OR NOT',1,'*') /* RETURNS 'TO*BE*OR*NOT' */ SPACE('TO BE OR NOT',2,'*') /* RETURNS 'TO**BE**OR**NOT' */ SPACE('TO BE OR NOT',2) /* RETURNS 'TO BE OR NOT' */ SPACE(' TO BE ') /* RETURNS 'TO BE' */ SPACE(' TO BE ',1,'*') /* RETURNS 'TO*BE' */ # 34.47 {STREAM} Returns a string that describes the current state of a file, or the result of a specific operation on a file. Supports state retrieval, open, close, seek, and query operations. SYNTAX: STREAM(FILE,OPERATION[,STREAM-COMMAND]) PARAMETERS: file Specifies the name of a file. operation Specify one of: C - specifies that a stream command follows in parm three D - returns extended state information S - returns concise state information If not specified, 'S' is assumed. Possible states are READY, NOTREADY, ERROR, and UNKNOWN. stream-command If 'C' was specified in parameter two, a stream command may be specified in parameter three. Specify one of: CLOSE Specifies that the named file is to be closed. If successful, returns string 'READY', otherwise returns an error message. OPEN [mode] Specifies that the named file is to be opened. Mode may be one of: READ open for read of CR/LF delimited records WRITE open for write of CR/LF delimited records TEXT READ same as READ TEXT WRITE same as WRITE BINARY READ open for read of binary data byte by byte BINARY WRITE open for write of binary data byte by byte BINARY open for read+write of binary data If not specified, TEXT READ+WRITE is assumed. If successful, returns string 'READY', otherwise returns an error message. Note: LINEIN and LINEOUT only operate in TEXT mode. That is, they require record termination characters. In DOS, WINDOWS, and OS2, CR/LF characters terminate each record. In UNIX, the LF character terminates each record. CHARIN and CHAROUT may operate in either TEXT or BINARY mode and will produce the same results as they are not record oriented. SEEK offset Specifies the number of bytes to offset from the beginning of the file. If successful, returns the new file position, otherwise returns an error message. The offset value may be preceded by one of the following modifier characters: = (equal) offset from front of file (the default) < (less-than) offset from end of file + (plus) advance from current position - (minus) back up from current position QUERY info-type Specify one of the following information types: EXISTS if exists, returns file name, else null SIZE if exists, returns byte count, else 0 DATETIME if exists, returns date and time, else null EXAMPLE: FNAM = 'HAMLET.TXT' /* SET FILE NAME */ SRET = STREAM(FNAM) /* RETURNS CONCISE STATE */ SRET = STREAM(FNAM,'S') /* RETURNS CONCISE STATE */ SRET = STREAM(FNAM,'D') /* RETURNS EXTENDED STATE */ SRET = STREAM(FNAM,'C','QUERY EXIST') /* RETURNS EXIST STATE */ SRET = STREAM(FNAM,'C','QUERY SIZE') /* RETURNS SIZE */ SRET = STREAM(FNAM,'C','QUERY DATETIME') /* RETURNS TIMESTAMP */ SRET = STREAM(FNAM,'C','OPEN READ') /* OPEN FOR TEXT READ */ SRET = STREAM(FNAM,'C','OPEN WRITE') /* OPEN FOR TEXT WRITE */ SRET = STREAM(FNAM,'C','OPEN') /* OPEN FOR TEXT READ+WRITE */ SRET = STREAM(FNAM,'C','OPEN BINARY') /* OPEN FOR BIN READ+WRITE */ SRET = STREAM(FNAM,'C','SEEK 80') /* SEEK TO OFFSET 80 */ /* CHECK STREAM RETURN "SRET" AFTER "STREAM" OPERATIONS */ # 34.48 {STRIP} Removes leading or trailing characters from a string. SYNTAX: STRIP(STRING[,DIRECTION][,CHARACTER]) PARAMETERS: string Specifies the string to be stripped. direction Specify one of: L - strip leading characters T - strip trailing characters B - strip leading and trailing characters (both) If not specified, B is assumed. character Specifies the character to be stripped. If not specified, BLANK is assumed. EXAMPLE: STRIP(' TO BE ') /* RETURNS 'TO BE' */ STRIP(' TO BE ','B') /* RETURNS 'TO BE' */ STRIP(' TO BE ','L') /* RETURNS 'TO BE ' */ STRIP(' TO BE ','T') /* RETURNS ' TO BE' */ STRIP('* TO BE *','B','*') /* RETURNS ' TO BE ' */ # 34.49 {SUBSTR} Returns a sub-string of a string at N for N. SYNTAX: SUBSTR(STRING,START_POS[,LENGTH][,PAD]) PARAMETERS: string Specifies the string to be sub stringed. start_pos Specifies the start position for the sub-string. length Specifies the desired length of the sub-string. If not specified, all characters from "start_pos" to end of string are included. pad Specifies the character to be used for pad if "start_pos" plus "length" exceeds the length of the string. If not specified, BLANK is assumed. EXAMPLE: SUBSTR('TO BE OR NOT TO BE',4,5) /* RETURNS 'BE OR' */ SUBSTR('TO BE OR NOT TO BE',10) /* RETURNS 'NOT TO BE' */ SUBSTR('TO BE OR NOT TO BE',14,8,'.') /* RETURNS 'TO BE...' */ # 34.50 {SUBWORD} Returns a sub-string of whole words from a string at N for N. SYNTAX: SUBWORD(STRING,START_WORD[,WORDS]) PARAMETERS: string Specifies the base string. start_word Specifies the position of the first word to be included in the sub-string. words Specifies the number of words to be included. If not specified, all words from "start_word" to end of string are included. EXAMPLE: SUBWORD('TO BE OR NOT TO BE',3,2) /* RETURNS 'OR NOT' */ SUBWORD('TO BE OR NOT TO BE',4) /* RETURNS 'NOT TO BE' */ SUBWORD('TO BE OR NOT TO BE',7) /* RETURNS '' */ # 34.51 {SYMBOL} Tests to see if a name has been used as a variable. Returns "VAR" if the name is an existing variable. Returns "LIT" if the name is a valid variable name but has not been used. Returns "BAD" if the name is not a valid variable name. SYNTAX: SYMBOL(NAME) PARAMETERS: name Specifies the name to be checked. EXAMPLE: SYMBOL(XDATE) /* RETURNS VAR - IN USE AS A VAR */ SYMBOL(BRANDNEW) /* RETURNS LIT - OK NAME BUT NOT USED AS VAR */ SYMBOL(#JUNK) /* RETURNS BAD - INVALID VAR NAME */ # 34.52 {TIME} Returns the local time in many different formats. SYNTAX: TIME([TYPE]) PARAMETERS: type Specifies one of: C - civilian time (hh:mm**) **=am/pm E - seconds.useconds since elapsed time clock started H - hours since midnight L - long format (hh.mm.ss.uu) uu=microseconds M - minutes since midnight N - normal (default) (hh.mm.ss) 24 time R - reset timer, also returns same as 'E' S - seconds since midnight EXAMPLE: TIME() /* RETURNS 24 HOUR TIME */ TIME('C') /* RETURNS 12 HOUR TIME */ TIME('E') /* RETURNS ELAPSED TIME */ TIME('H') /* RETURNS HOURS SINCE 00.00 */ TIME('L') /* RETURNS LONG TIME */ TIME('M') /* RETURNS MINUTES SINCE 00.00 */ TIME('N') /* RETURNS 24 HOUR TIME */ TIME('R') /* RETURNS AND RESETS ELAPSED TIMER */ TIME('S') /* RETURNS SECONDS SINCE 00.00.00 */ # 34.53 {TRACE} Returns or sets the current trace level. SYNTAX: TRACE([SETTING]) PARAMETERS: setting See TRACE instruction. EXAMPLE: TRACE() /* RETURNS CURRENT TRACE SETTING */ TRACE('?A') /* SETS INTERACTIVE + TRACE ALL */ TRACE('C') /* SETS TRACE COMMANDS */ TRACE('E') /* SETS TRACE ERROR */ TRACE('F') /* SETS TRACE FAILURE */ TRACE('I') /* SETS TRACE INTERMEDIATES */ TRACE('L') /* SETS TRACE LABELS */ TRACE('N') /* SETS TRACE NORMAL */ TRACE('O') /* SETS TRACE OFF */ TRACE('R') /* SETS TRACE RESULTS */ # 34.54 {TRANSLATE} Translates characters in a string byte by byte under the control of translate tables. If no translate tables are specified, translates all characters to upper case. SYNTAX: TRANSLATE(STRING[,TO_TABLE][,FROM_TABLE][,PAD_CHAR]) PARAMETERS: string Specifies the string to be translated. to_table Specifies a table of characters (in string form) to replace corresponding characters in "from_table". from_table Specifies a table of characters (in string form) to search for in "string". Each character found is replaced with the corresponding character in "to_table". pad_char Specifies the character to use for padding if "to_table" is shorter than "from_table". If not specified, BLANK is assumed. EXAMPLE: TRANSLATE('TO BE OR NOT') /* RETURNS UPPERCASE 'TO BE OR NOT' */ TRANSLATE('AABBCC','X','B') /* RETURNS 'AAXXCC' */ TRANSLATE('ABCDABCDABCD','12','BD') /* RETURNS 'A1C2A1C2A1C2' */ # 34.55 {TRUNC} Returns the integer part of a number. SYNTAX: TRUNC(NUMBER) PARAMETERS: number Specifies the number whose integer part is to be obtained. EXAMPLE: TRUNC('5.67') /* RETURNS 5 */ # 34.56 {VALUE} Returns or sets the value of an external environment variable. SYNTAX: VALUE(ENV_VAR_NAME[,NEW_VALUE][,ENVIRONMENT]) PARAMETERS: env_var_name Specifies the name of the external environment variable to retrieve or set. new_value Specifies the value to which the external environment variable is to be set. If not specified, the variable is simply retrieved. environment Specifies the external environment. CMD is the current operating system and is the only external environment supported. EXAMPLE: VALUE('PATH',,'CMD') /* RETURNS SETTING OF ENV VAR PATH */ VALUE('SPFPATH','C:\SPFPRO,'CMD') /* SET ENV VAR SPFPATH */ # 34.57 {VERIFY} Verify whether characters within a string belong to a particular subset of characters. SYNTAX: VERIFY(STRING,SUBSET[,OPTION][,START_POS]) PARAMETERS: string Specifies the string to be verified subset Specifies a string containing one instance of each character in the subset. option Specifies one of: N Report non-matching character condition. Returns the position of the first non-matching character. Otherwise returns 0 (all characters match). M Report matching character condition. Returns the position of the first matching character. Otherwise returns 0 (no characters match). If not specified, 'N' is assumed. start_pos Specifies the start position in string at which to commence verification. If not specified, 1 is assumed. EXAMPLE: VERIFY('123TXT','0123456789') /* RETURNS 4, 1ST NO-MATCH */ VERIFY('123456','0123456789') /* RETURNS 0, ALL CHARS MATCH */ VERIFY('TXT456','0123456789','M') /* RETURNS 4, 1ST MATCH */ VERIFY('TXTABC','0123456789','M') /* RETURNS 0, NO CHARS MATCH */ # 34.58 {WORD} Returns the Nth word in a string. SYNTAX: WORD(STRING,WORD_POS) PARAMETERS: string Specifies the base string. word_pos Specifies the ordinal position of the word to be retrieved. EXAMPLE: WORD('TO BE OR NOT TO BE',3) /* RETURNS 'OR' */ WORD('TO BE OR NOT TO BE',7) /* RETURNS '' */ # 34.59 {WORDINDEX} Returns the character position of the Nth word in a string. SYNTAX: WORDINDEX(STRING,WORD_POS) PARAMETERS: string Specifies the base string. word_pos Specifies the ordinal position of the word whose character position is to be retrieved. EXAMPLE: WORDINDEX('TO BE OR NOT TO BE',3) /* RETURNS 7 */ WORDINDEX('TO BE OR NOT TO BE',7) /* RETURNS 0 */ # 34.60 {WORDLENGTH} Returns the length of the Nth word in a string. SYNTAX: WORDLENGTH(STRING,WORD_POS) PARAMETERS: string Specifies the base string. word_pos Specifies the ordinal position of the word whose character length is to be retrieved. EXAMPLE: WORDLENGTH('TO BE OR NOT TO BE',3) /* RETURNS 2 */ WORDLENGTH('TO BE OR NOT TO BE',4) /* RETURNS 3 */ WORDLENGTH('TO BE OR NOT TO BE',7) /* RETURNS 0 */ # 34.61 {WORDPOS} Returns the word number of the first word (or words) matching the search criteria. SYNTAX: WORDPOS(WORDS,STRING[,START_WORD]) PARAMETERS: words Specifies one or more words separated by blanks. Multiple blanks are treated as single blanks for the purpose of the comparison. string Specifies the base string. Multiple blanks are treated as single blanks for the purpose of the comparison. start_word Specifies the ordinal position of the first word to be searched. If not specified, 1 is assumed. EXAMPLE: WORDPOS('NOT', 'TO BE OR NOT TO BE') /* RETURNS 4 */ WORDPOS('BE', 'TO BE OR NOT TO BE',3) /* RETURNS 6 */ WORDPOS('OR NOT', 'TO BE OR NOT TO BE') /* RETURNS 3 */ WORDPOS('OR NOT', 'TO BE OR NOT TO BE') /* RETURNS 3 */ WORDPOS('OR NOT','TO BE OR NOT TO BE') /* RETURNS 3 */ # 34.62 {WORDS} Returns the number of words in a string. SYNTAX: WORDS(STRING) PARAMETERS: string Specifies the base string. EXAMPLE: WORDS('TO BE OR NOT TO BE') /* RETURNS 6 */ WORDS(' ') /* RETURNS 0 */ # 34.63 {XRANGE} Returns a string of characters which includes all character codes from the start to the end of a range. SYNTAX: XRANGE([START_CHAR][,END_CHAR]) PARAMETERS: start_char Specifies the first character in the range. If "start_char" is greater than "end"char", the range wraps around. If not specified, '00'x is assumed. end_char Specifies the last character in the range. If not specified, 'FF'x is assumed. EXAMPLE: XRANGE('A','I') /* RETURNS 'ABCDEFGHI' */ XRANGE('45'X,'4C'X) /* RETURNS '45464748494A4B4C'X */ XRANGE('FC'X,'03'X) /* RETURNS 'FCFDFEFF00010203'X (WRAPS) */ # 34.64 {X2B} Converts a hexadecimal string to a binary string. SYNTAX: X2B(STRING) PARAMETERS: string Specifies the string of hex characters to be converted. EXAMPLE: X2B('3') /* RETURNS '00000011' */ X2B('8C') /* RETURNS '10001100' */ X2B('58C') /* RETURNS '0000010110001100' */ X2B('A58C') /* RETURNS '1010010110001100' */ # 34.65 {X2C} Converts a hexadecimal string to equivalent ASCII characters. SYNTAX: X2C(STRING) PARAMETERS: string Specifies the string of hex characters to be converted. EXAMPLE: X2C('C1C2C3') /* RETURNS 'ABC' */ # 34.66 {X2D} Converts a hexadecimal string to an equivalent decimal value. SYNTAX: X2D(STRING) PARAMETERS: string Specifies the string of hex characters to be converted. Hex character strings having an odd number of digits are extended on the left with '0'. EXAMPLE: X2D('1') /* RETURNS 1 */ X2D('01') /* RETURNS 1 */ X2D('A') /* RETURNS 10 */ X2D('0A') /* RETURNS 10 */ X2D('C1') /* RETURNS 193 */ X2D('FF') /* RETURNS 255 */ X2D('FFF') /* RETURNS 4095 */ X2D('0FFF') /* RETURNS 4095 */ # 35. {Command Tables} # 35.1 {Purpose and Use of Command Tables} Command tables let you "customize" the SPF/Pro primary command set. In this way you can extend SPF/Pro to more closely emulate your mainframe environment. Command tables are stored as SPF/Pro tables, bearing the extension ".TBF", and residing in ZPRFPATH (see option 0.8). Command tables are identified by name: xxxxCMDS.TBF. Where 'xxxx' is the name of the command table which is used in the NEWAPPL command (see later). The table has an initial row that is a description of the command table. This row is ignored when the table is loaded. Each row of the table has a number of fields. The fields are defined as follows: ZCTVERB Holds the name of the new command (2-8 characters). ZCTTRUNC Specifies the minimum number of characters of ZCTVERB necessary for recognition of this command (0-8 characters). ZCTACT The actual command to be executed (up to 60 characters). Valid commands are: SELECT Invokes the SELECT service to display a panel or execute a program (either REXX, CTC or user written). ALIAS Allows one command to substituted for another. For example, TOP is aliased to UP MAX. PASSTHRU Causes the command to be passed through to the current dialog. This allows you to "trap" SPF/Pro's commands and override or augment their behavior. SETVERB Causes the first word of ZCMD to be passed to variable ZVERB and the remainder to be set into ZCMD. NOP Causes the command to be a "no operation", it does nothing. BLANK Causes the command table entry to be skipped. Search for a matching command verb continues with the next entry in the command table. &varname The variable is expanded, providing dynamic command action functionality. Please note that it is illegal for a variable to expand to another variable. For example, var &A can not have the value "&B". ZCTDESC An optional description of the action the command is to perform. (up to 57 characters) Modification of command tables should be performed via Dialog Manager panel 3.J. Do not edit xxxxCMDS.TBF directly, their format may change. If command table SPFCMDS.TBF is not found at startup, it is created with all default values. If you somehow "break" the working version, simply exit &PRODUCT, erase it, then re-enter &PRODUCT. A new table will be created. You will of course loose any changes made up to that point. (Modifiable via panel 3.J.) If command table EDITCMDS.TBF is not found by edit, it is created with all default values. This table contains commands for both EDIT and BROWSE services, and is automatically activated. (Modifiable via panel 3.J.) There is an "intrinsic" command table, which contains specifications for the base general command set of SPF/Pro. This table is not accessible. The intrinsic commands follow: CMD CMDNOCLR CRETRIEV CURSOR DOS EOF FF FSPLIT HELP LPRINT LPRINTER LPRT OS2 PANELID PFSHOW PRINT RETRIEVE SCREEN SPLIT SPLITH SPLITV STACKDIS SWAP VSPLIT Command processing searches through user command tables in LIFO order. Then it searches EDITCMDS, SPFCMDS, and finally the Intrinsic table. If no match is found, the command verb is passed to the current dialog for processing. User command tables are added to the stack of command tables by use of the NEWAPPL option which is part of the SELECT command. Consider the command: SELECT CMD(USERAPP) NEWAPPL(USER) This example invokes user application USERAPP.ISP and adds command table USERCMDS.TBF to the stack of command tables. If USERCMDS.TBF overrides the behavior of some SPF/Pro commands, this new behavior will continue until either a new command table overrides this one or the application terminates in which case USERCMDS.TBS is popped from the stack. For more details, see the SELECT service in the chapter on ISPEXEC. # 36. {ISREDIT Macro Commands} Edit macros are used as an extension to the primary and line command set. In an edit macro you can program the edit session. In effect you can alter the contents of the file in a complex and conditional manner with a macro. This is much more efficient than keying in multiple primary and line commands to effect changes. Edit macros are written in REXX. When an edit macro is invoked via the primary command line or by function key, SPF/Pro passes the macro to REXX for processing. The REXX procedure language provides conditional processing, loop control, symbol assignment, arithmetic functions, access to external files, and a variety of other useful functions. In conjunction with REXX you use ISREDIT commands of SPF/Pro to travel, inspect, and modify the file. You can also interact with the end user. Information regarding the use of REXX within SPF/Pro is documented in the file SPFPRO\REXX.DOC. All of edit's primary and line commands are available through the ISREDIT interface. You also have access to a wide range of system variables and state information which enables you to perform the most complex of tasks. All edit macros are given the file type ".SPF". and must begin with a REXX comment line: /* ... REXX comment line ... */ We recommend: /* SPF EDIT MACRO: macro-name */ All ISREDIT statements must be enclosed in single quotes: 'ISREDIT ...' The first ISREDIT command in any macro must be: 'ISREDIT MACRO' So in the most simple case your edit macro would look like this: /* SPF MACRO: EXAMPLE1 */ 'ISREDIT MACRO' 'ISREDIT ...' REXX and ISREDIT commands may be freely intermixed: IF ... THEN 'ISREDIT ...' ELSE 'ISREDIT ...' Note: In most examples and command descriptions we use uppercase letters for clarity; you may use lower case letters if desired. Print some of the edit macros in SPFPRO\REXX for examination. This gives you some insight into how edit macros can be applied and how to write them: PRINT SPFPRO\REXX\PROLOG.SPF PRINT SPFPRO\REXX\MODIFY.SPF The first example macro "PROLOG" creates a prolog in a "C" source module. The second example macro "MODIFY" adds a modification entry to the prolog of an existing module. # 36.1 {ISREDIT Macro Command Summary} AUTOLIST Set or retrieve the AUTOLIST profile variable. AUTONUM Set or retrieve the AUTONUM profile variable. AUTOSAVE Set or retrieve the AUTOSAVE profile variable. BLKSIZE Retrieves the current block size. BOUNDS Set or retrieve the BOUNDS profile variable. CANCEL Cancels editing of current file without saving changes. CAPS Set or retrieve the CAPS profile variable. CHANGE Searches for a string and replaces it with another string. CHANGE_COUNTS Retrieves the count set by the last issued CHANGE command. CHARSET Set or retrieve the CHARSET profile variable. COLORMAP Set or retrieve the COLORMAP profile variable. COMPARE Compare an external file to the current edit file. COPY Copies another file into the current file. CREATE Specifies a new file is to be created. CURSOR Sets or retrieve line and col number of current cursor pos. CUT Copy/Move block of lines to clipboard. DATA Insert/overtype data at the current cursor position. DATA_CHANGED Retrieves the current data changed status. DATA_WIDTH Returns data width of current file. DATAID Not supported. DATASET Retrieves the name of the current file. DEFINE Enable/disable specific macros by name. DELETE Removes one or more lines from the file you are editing. DISPLAY_COLS Retrieves the first and last display columns. DISPLAY_LINES Retrieves line numbers of first and last displayed lines. DOS Executes an operating system command. DOWN Displays the next frame of lines in the file. EDIT Edit another file without leaving the current file. END Ends the edit session. ERRORFILE Merge compiler error messages with program source. EXCLUDE Allows you to temporarily exclude lines from view EXCLUDE_COUNTS Sets count of strings and lines excluded by last EXCLUDE. FIND Searches a file for a specified string. FIND_COUNTS Sets count of strings and lines found by last FIND or RFIND. FLOW_COUNTS Sets count of original and resulting lines created by last TFLOW. HEX Set or retrieve the HEX profile variable. HOLD_LOCK Hold the lock on the file. IMACRO Set or retrieve the IMACRO profile variable. INSERT Inserts one or more null lines for data entry in current file. LABEL Sets or retrieves the label on a specific line. LCOMMAND Set or retrieve the LCOMMAND profile variable. LEFT Displays currently undisplayed columns to the left. LEVEL Set or retrieve the current modification level. LINE Sets or retrieves data from a specified line. LINE_AFTER Inserts line of text after a specified line in current file. LINE_BEFORE Inserts line of text before a specified line in current file. LINENUM Retrieves the relative line number of a labeled line. LOCATE Makes line matching search criteria the top display line. LRECL Returns the logical record length of the current file. MACRO Identifies a macro, its parameters, and processing conditions. MACRO_LEVEL Retrieves the nesting level of the current macro. MASKLINE Set or retrieve the MASKLINE profile variable. MEMBER Retrieves the name of the current file. MODEL Insert MODEL syntax entry applicable to this file type. MOVE Moves another file into the current file. NOTE Set or retrieve the NOTE profile variable. NUMBER Set or retrieve the NUMBER profile variable. PASTE Insert lines from clipboard at A or B line. PROCESS Controls when pending line commands and data are processed. PROFILE Displays the current edit profile. RANGE_CMD Identifies first line command captured by PROCESS RANGE. RCHANGE Repeats the most recent CHANGE command. READ_ONLY Set the file to read only. RECFM Retrieves the record format of the current file. RECOVERY Allow UNDO. REDO Redo an edit transaction after an undo. RENUM Turns NUMBER mode on and renumbers lines. REPLACE Replaces an existing file with all or part of the current file. RESET Restores the status of data lines and removes special lines. RFIND Repeats the most recent FIND command. RIGHT Displays currently undisplayed columns to the right. SAVE Saves the current file without terminating the edit session. SAVECOUNT Set or retrieve the SAVECOUNT profile variable. SAVE_ENABLED Set the file to allow SAVE. SCAN Sets or retrieves the SCAN mode. SCOPY Copy the current selection to the clipboard. SCREATE Create a new file with the current selection contents. SCUT Copy current selection to clipboard, then delete selection. SDELETE Delete the current selection. SEEK Same as FIND but does not expose excluded lines. SEEK_COUNTS Sets count of strings and lines found by last SEEK. SHIFT ( Moves data left using column shift logic. SHIFT ) Moves data right using column shift logic. SHIFT < Moves data left using data shift logic. SHIFT > Moves data right using data shift logic. SORT Rearranges data or cols of data in a specified order. SPASTE Insert the clipboard contents at the current cursor position. SREPLACE Replace a file with the current selection contents. STATS Sets or retrieves the current STATS mode. STOLOWER Convert all alpha characters in the selection to lower case. STOUPPER Convert all alpha characters in the selection to uppercase. SUBMIT Only supported if MVS access component purchased. SXCLUDE Exclude all lines touched by the current selection. TABS Set or retrieve the TABS profile variable. TABSLINE Set or retrieve the TABSLINE profile variable. TENTER Provides blank screen space for text entry. TFLOW Composes a block of text within designated BOUNDS. TJOIN Joins current line with following line; inverse of TSPLIT. TSPLIT Splits a line so that additional text can be inserted. UNDO Undo the last edit operation. UNNUM Turns NUMBER mode off and removes line numbers. UP Displays the previous frame of lines in the file. USER_STATE Saves or restores user state information. XMACRO Set or retrieve the XMACRO profile variable. XSTATUS Sets or retrieves exclude status of specified data line. # 36.1 {AUTOLIST} Purpose Set or retrieve the AUTOLIST profile variable. If AUTOLIST mode is on when you exit the edit session via [F3] or END, a listing of the modified file is sent to the system printer. Format ISREDIT (varname) = AUTOLIST ISREDIT AUTOLIST = mode ISREDIT AUTOLIST mode Operands varname The name of a variable to contain the AUTOLIST mode, either ON or OFF. mode The setting of AUTOLIST mode. ON Turns on AUTOLIST. OFF Turns off AUTOLIST. Returns 0 Normal completion 20 Severe error Example To put the current AUTOLIST mode into variable V1: 'ISREDIT (V1) = AUTOLIST' To set AUTOLIST mode ON: 'ISREDIT AUTOLIST = ON' To set AUTOLIST mode from variable V1: 'ISREDIT AUTOLIST = (V1)' or 'ISREDIT AUTOLIST = 'V1 # 36.2 {AUTONUM} Purpose Set or retrieve the AUTONUM profile variable. If AUTONUM mode is on when you exit the edit session via [F3] or END, the lines are renumbered. Format ISREDIT (varname) = AUTONUM ISREDIT AUTONUM = mode ISREDIT AUTONUM mode Operands varname The name of a variable to contain the setting of AUTONUM mode, either ON or OFF. mode The setting of AUTONUM mode. ON Turns on automatic renumbering. Lines are renumbered when changes are saved. OFF Turns off automatic renumbering. Lines are not renumbered when changes are saved. Returns 0 Normal completion 20 Severe error Example To put the current AUTONUM mode into variable V1: 'ISREDIT (V1) = AUTONUM' To set AUTONUM mode OFF: 'ISREDIT AUTONUM = OFF' To set AUTONUM mode from variable V1: 'ISREDIT AUTONUM = (V1)' or 'ISREDIT AUTONUM = 'V1 # 36.3 {AUTOSAVE} Purpose Set or retrieve the AUTOSAVE profile variable. If AUTOSAVE mode is on when you exit the edit session via [F3] or END, the modified file is saved. Format ISREDIT (var1,var2) = AUTOSAVE ISREDIT AUTOSAVE = MODE ISREDIT AUTOSAVE mode Operands var1 Name of a variable to contain the setting of autosave mode, either ON or OFF. var2 Name of a variable to contain the prompt value, either PROMPT or NOPROMPT. mode The setting of the autosave mode. ON Turns AUTOSAVE mode on. OFF PROMPT Turns AUTOSAVE mode off with the PROMPT option. If you exit via [F3] or END, you are notified that changes have been made. At this point you can either SAVE or CANCEL the file. OFF NOPROMPT Turns AUTOSAVE mode off with the NOPROMPT option. The file is not saved on exit. Returns 0 Normal completion 4 OFF NOPROMPT specified 20 Severe error Example To put the current AUTOSAVE mode into variables V1 and V2: 'ISREDIT (V1,V2) = AUTOSAVE' To set AUTOSAVE mode ON: 'ISREDIT AUTOSAVE = ON' To set AUTOSAVE mode from variables V1 and V2: 'ISREDIT AUTOSAVE = (V1,V2)' or 'ISREDIT AUTOSAVE = 'V1 V2 # 36.4 {BLKSIZE} Purpose Sets the block size of the current file into a named variable. Format ISREDIT (varname) = BLKSIZE Operands varname The name of a variable to contain the "block size" of the current file. The number is a six digit value left-padded with zeros. SPF/Pro does not support blocked records. For compatibility, the value 1024 is always returned. Returns 0 Normal completion 20 Severe error Example To set the block size of the current file into variable V1: 'ISREDIT (V1) = BLKSIZE' # 36.5 {BOUNDS} Purpose Set or retrieve the BOUNDS profile variable. Format ISREDIT (var1,var2) = BOUNDS ISREDIT BOUNDS = left-col right-col ISREDIT BOUNDS left-col right-col Operands var1 Name of a variable to contain the left bound. var2 Name of a variable to contain the right bound. left-col The setting for the left bound. An asterisk (*) indicates that the current value is to be used. right-col The setting for the right bound. An asterisk (*) indicates that the current value is to be used. Returns 0 Normal completion 4 Right bound greater than default, default right bound used 12 Invalid bounds specified 20 Severe error Example To set the current bounds into variables V1 and V2: 'ISREDIT (V1,V2) = BOUNDS' To set only the left bound into variable V1: 'ISREDIT (V1) = BOUNDS' To set only the right bound into variable V2: 'ISREDIT (,V2) = BOUNDS' To set the left bound but not the right: 'ISREDIT BOUNDS = 5 *' To set the right bound but not the left: 'ISREDIT BOUNDS = * 60' To set the bounds to the system default values: 'ISREDIT BOUNDS' To restore the bounds to the values saved in variables V1 and V2: 'ISREDIT BOUNDS = (V1,V2)' or 'ISREDIT BOUNDS = 'V1 V2 # 36.6 {CANCEL} Purpose Cancels editing of the current file without saving any changes made. Format ISREDIT CANCEL Returns 0 Normal completion 20 Severe error Example To cancel the current edit session: 'ISREDIT CANCEL' # 36.7 {CAPS} Purpose Set or retrieve the CAPS profile variable. If CAPS mode is ON, keyed input data is automatically translated into uppercase. Format ISREDIT (varname) = CAPS ISREDIT CAPS = mode ISREDIT CAPS mode Operands varname The name of a variable to contain the caps mode, either ON or OFF. mode The setting of the caps mode. ON Automatically translates keyed input data to uppercase. OFF Does not translate keyed input data to uppercase. Returns 0 Normal completion 20 Severe error Example To set the current CAPS mode into variable V1: 'ISREDIT (V1) = CAPS' To set CAPS mode OFF: 'ISREDIT CAPS = OFF' To set CAPS mode from variable V1: 'ISREDIT CAPS = (V1)' or 'ISREDIT CAPS = 'V1 # 36.8 {CHANGE} Purpose The CHANGE macro command is identical in syntax and function to the CHANGE primary command. When using CHANGE in a macro it is advisable to save the current bounds and then set them to a known value. On exit restore the bounds to the saved values. See page 630 for details. Format ISREDIT CHANGE ... Returns 0 Normal completion 4 String not found 8 Change error ('to' string longer than 'from' string and substitution was not performed on at least one change) 20 Severe error Example To change all occurrences of "this" to "that": 'ISREDIT CHANGE C"this" C"that" ALL' # 36.9 {CHANGE_COUNTS} Purpose Retrieves counts set by the last CHANGE command and stores the values in variables. Format ISREDIT (var1,var2) = CHANGE_COUNTS Operands var1 Name of a variable to contain the number of strings changed. The number is an eight digit value left-padded with zeros. var2 Name of a variable to contain the number of strings not changed. The number is an eight digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To put the number of changes and non-changes resulting from the most recent CHANGE command into variables V1 and V2: 'ISREDIT (V1,V2) = CHANGE_COUNTS' # 36.10 {CHARSET} Purpose Set or retrieve the CHARSET profile variable. Format ISREDIT (varname) = CHARSET ISREDIT CHARSET = value ISREDIT CHARSET value Operands varname The name of a variable to contain the current setting of CHARSET. value The desired setting for profile variable CHARSET. The value may be: ASCII The characters in the file are all ASCII. EBCDIC The characters in the file are all EBCDIC. Returns 0 Normal completion 20 Severe error Example To retrieve profile variable CHARSET: 'ISREDIT (V1) = CHARSET' To set profile variable CHARSET: 'ISREDIT CHARSET = ASCII' To set profile variable CHARSET from variable V1: 'ISREDIT CHARSET = (V1)' or 'ISREDIT CHARSET = 'V1 # 36.11 {COLORMAP} Purpose Set or retrieve the COLORMAP profile variable. Format ISREDIT (varname) = COLORMAP ISREDIT COLORMAP = value ISREDIT COLORMAP value Operands varname The name of a variable to contain the current setting of COLORMAP. value The desired setting for profile variable COLORMAP. The value is the name part of name.ext for the color map file. Returns 0 Normal completion 20 Severe error Example To retrieve profile variable COLORMAP: 'ISREDIT (V1) = COLORMAP' To set profile variable COLORMAP: 'ISREDIT COLORMAP = COBOL' To set profile variable COLORMAP from variable V1: 'ISREDIT COLORMAP = (V1)' or 'ISREDIT COLORMAP = 'V1 # 36.12 {COMPARE} Purpose Compare an external file to the current edit file. Parameters are identical to the COMPARE primary command. Format ISREDIT COMPARE [ file-name ] Returns 0 Normal completion 20 Severe error # 36.13 {COPY} Purpose Copies another file into the current file. Format ISREDIT COPY filename [AFTER lptr] [line-range] [BEFORE lptr] Operands filename The name of the file to be copied. AFTER The relative position where the new data is to be inserted. BEFORE The relative position where the new data is to be inserted. line-range The start and end line numbers of the block of lines to be copied. If not specified, all lines are copied. Returns 0 Normal completion 8 End of data reached before last record read 12 Invalid line pointer (lptr); file not found 16 End of data reached before first record of specified range was reached 20 Severe error Example To copy all of file XYZ to the end of the current file: 'ISREDIT COPY XYZ AFTER .ZLAST' To copy all of file XYZ to the beginning of the current file: 'ISREDIT COPY XYZ BEFORE .ZFIRST' To copy lines 6 through 10 of file XYZ to the beginning of the current file: 'ISREDIT COPY XYZ BEFORE .ZFIRST 6 10' # 36.14 {CREATE} Purpose Creates a new file in the current directory from lines in the current file. Format ISREDIT CREATE filename range Operands filename The name of the file to create. range The start and end line numbers or labels of the block of lines to be used to create the new file. Returns 0 Normal completion 8 Already exists, file not created 12 Invalid range or file not found 20 Severe error Example To create new file XYZ from lines 6 through 10 of the current file: 'ISREDIT CREATE XYZ 6 10' # 36.15 {CURSOR} Purpose Sets or retrieves the line and column number of the cursor position in the current file. Format ISREDIT (var1,var2) = CURSOR ISREDIT CURSOR = line col Operands var1 Name of a variable to contain the line number. The number is six digit value left-padded with zeros. It is the ordinal number of the line; not the sequence number. If the cursor is in the command area, the line number returned is that of the first displayed data line. If the file is empty, the line number returned is 0. var2 Name of a variable to contain the column number. The number is a three digit value left-padded with zeros. Columns are numbered left to right starting with 1. If the cursor is in the command area, the column number returned is 1. If the cursor is in the line command area, the column number returned is 0. If the file is empty, the column number returned is 0. line The line number where the cursor is to be located. col The column number where the cursor is to be located. If the column number specified is beyond the bounds, the cursor is positioned to the first position in the line command area of the next line. When you invoke a macro, the cursor value is the cursor position on the screen at invocation time. The following statements may change the cursor position: CHANGE EXCLUDE FIND SEEK TSPLIT Returns 0 Normal completion 4 Column number beyond data, line number incremented 12 Invalid line number 20 Severe error Example To put the current cursor position into variables V1 and V2: 'ISREDIT (V1,V2) = CURSOR' To set the cursor position to line 3, column 20: 'ISREDIT CURSOR = 3 20' To set the cursor position to column 1 of the last data line: 'ISREDIT CURSOR = .ZLAST 1' To set the cursor position to line labeled ".A" without changing the column position: 'ISREDIT CURSOR = .A' # 36.16 {CUT} Purpose Copy a block of "CC" lines, or move a block of "MM" lines to the clipboard. Operation is identical to the CUT primary command. Also see page . Format ISREDIT CUT Returns 0 Normal completion 20 Severe error # 36.17 {DATA} Purpose Insert/overtype data at the current cursor position. Parameters are identical to the DATA primary command. Format ISREDIT DATA text Returns 0 Normal completion 20 Severe error # 36.18 {DATA_CHANGED} Purpose Retrieves the current data changed status and stores the value in a variable. Format ISREDIT (varname) = DATA_CHANGED Operands varname The name of a variable to contain the data changed status, either YES or NO. The data changed status is initially set to NO at the beginning of an edit session, and is reset to NO whenever a save is done. When data is changed, the changed status is set to YES. Returns 0 Normal completion 20 Severe error Example To set the change status into variable V1: 'ISREDIT (v1) = DATA_CHANGED' # 36.19 {DATA_WIDTH} Purpose Returns the data width (LRECL minus number field) of the current file in a specified variable. Format ISREDIT (varname) = DATA_WIDTH Operands varname The name of the variable to contain the data width. The number is a three digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error The data width varies depending on the record numbering option: Number Type Data Width None LRECL STD LRECL - 8 COBOL LRECL - 6 STD COBOL LRECL - 14 Example To set the data width in variable V1: 'ISREDIT (V1) = DATA_WIDTH' # 36.20 {DATASET} Purpose Retrieves the name of the current file and stores the value in a variable. Format ISREDIT (varname) = DATASET Operands varname The name of a variable to contain the name of the current file. Returns 0 Normal completion 20 Severe error Example To set the current file name into variable V1: 'ISREDIT (V1) = DATASET' Note the difference between MEMBER and DATASET: 'isredit (name1) = MEMBER' 'isredit (name2) = DATASET' would set the variables as follows: name1 == AUTOEXEC.BAT name2 == C:\AUTOEXEC.BAT # 36.21 {DEFINE} Purpose The DEFINE macro command is identical in syntax and function to the DEFINE primary command. Format ISREDIT DEFINE ... Returns 0 Normal completion 8 RESET name not found or ALIAS name2 is a NOP. 12 ALIAS name2 is not valid. 20 Severe error Example See DEFINE primary command examples. # 36.22 {DELETE} Purpose Removes one or more lines from the current file. Format ISREDIT DELETE [ALL] [X ] [lptr ] [NX] [range] Operands ALL The DELETE command always deletes all qualified lines, thus it is unnecessary to specify ALL unless you want it for clarity. X If X is specified, only excluded lines are deleted. NX If NX is specified, only non-excluded lines are deleted. lptr Specifies the line number or label of the single line to be deleted. range Specifies the start and end line numbers or labels of a block of lines to be deleted. Returns 0 Normal completion 4 No lines deleted 8 No standard records exists 12 Invalid line number 20 Severe error Example To delete all excluded lines: 'ISREDIT DELETE X' To delete all non-excluded lines: 'ISREDIT DELETE NX' To delete the last line of the current file: 'ISREDIT DELETE .ZLAST' To delete lines 6 through 10 of the current file: 'ISREDIT DELETE 6 10' To delete excluded lines between labels .A and .B: 'ISREDIT DELETE X .A .B' # 36.23 {DISPLAY_COLS} Purpose Retrieves the first and last column displayed on the screen and stores these values in variables. Format ISREDIT (var1,var2) = DISPLAY_COLS Operands var1 The name of a variable to contain the number of the first visible data column. The number is a four digit value left-padded with zeros. var2 The name of a variable to contain the number of the last visible data column. The number is a four digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the leftmost and right most visible data column numbers into variables V1 and V2 respectively: 'ISREDIT (V1,V2) = DISPLAY_COLS' # 36.24 {DISPLAY_LINES} Purpose Retrieves the relative line numbers of the first and last data lines that would be displayed at this point if the macro terminated, and stores these values in variables. Format ISREDIT (var1,var2) = DISPLAY_LINES Operands var1 The name of a variable to contain the relative line number of the first visible data line. The number is a six digit value left-padded with zeros. var2 The name of a variable to contain the relative line number of the last visible data line. The number is a six digit value left-padded with zeros. Returns 0 Normal completion 4 No visible data lines 8 No existing data lines 20 Severe error Example To set the topmost and bottom most visible data line numbers into variables V1 and V2 respectively: 'ISREDIT (V1,V2) = DISPLAY_LINES' # 36.25 {DOS} Purpose Executes an operating system command. Format ISREDIT DOS operating-system-command Operands Specify the operating system command. Returns 0 Normal completion 20 Severe error Example To issue the "dir" operating system command: 'ISREDIT DOS dir' # 36.26 {DOWN} Purpose Displays the next frame of lines in the file. Format ISREDIT DOWN amount Operands Specify scroll amount in one of the following forms: nnnn The number of lines to scroll. MAX Scroll to the end of the file. HALF Scroll by one half screen depth. PAGE Scroll by one full screen depth. CURSOR Scroll to make the line on which the cursor is located the first display line. DATA Same as PAGE minus one line. Returns 0 Normal completion 2 No more data 4 No visible lines 8 No data to display 12 Amount value required but missing 20 Severe error Example To make the current line the top display line: 'ISREDIT DOWN CURSOR' # 36.27 {EDIT} Purpose Allows editing of another file without leaving the current file. Format ISREDIT EDIT file-name Operands file-name The name of the file to be edited. Returns 0 Normal completion 12 Invalid file name 14 File in use 20 Severe error Example To recursively edit file XYZ: 'ISREDIT EDIT XYZ' # 36.28 {END} Purpose Ends the edit session. If the editor was invoked through the dialog manager, you are returned to the EDIT panel. Format ISREDIT END Returns 0 Normal completion 4 New data saved 12 END not done, data not saved 20 Severe error Example To end the current edit session: 'ISREDIT END' # 36.29 {ERRORFILE} Purpose Merge compiler error messages with program source in the current edit file. Parameters are identical to the ERRORFILE primary command. Format ISREDIT ERRORFILE err-msg-file-name Returns 0 Normal completion 20 Severe error # 36.30 {EXCLUDE} Purpose The EXCLUDE macro command is identical in syntax and function to the EXCLUDE primary command. When using EXCLUDE in a macro it is advisable to save the current bounds and then set them to a known value. On exit, restore the bounds to the saved values (see page 630 for details). Format ISREDIT EXCLUDE ... Returns 0 Normal completion 4 String not found 8 Line(s) not excluded 20 Severe error Example To exclude all lines and then display only lines containing the string IF: 'ISREDIT EXCLUDE ALL' 'ISREDIT FIND ALL IF' # 36.31 {EXCLUDE_COUNTS} Purpose Sets the count of strings and lines excluded by the last EXCLUDE command into named variables. Format ISREDIT (var1,var2) = EXCLUDE_COUNTS Operands var1 The name of a variable to contain the number of strings excluded. The number is an eight digit value left-padded with zeros. var2 The name of a variable to contain the number of lines excluded. The number is an eight digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the number of strings and lines containing string IF into variables V1 and V2 respectively: 'ISREDIT EXCLUDE ALL IF' 'ISREDIT (V1,V2) = EXCLUDE_COUNTS' # 36.32 {FIND} Purpose The FIND macro command is identical in syntax and function to the FIND primary command When using FIND in a macro it is advisable to save the current bounds and then set them to a known value. On exit, restore the bounds to the saved values (see page 630 for details). Format ISREDIT FIND ... Returns 0 Normal completion 4 String not found 12 Syntax error 20 Severe error Example To exclude all lines and then display only lines containing the string IF: 'ISREDIT EXCLUDE ALL' 'ISREDIT FIND ALL IF' # 36.33 {FIND_COUNTS} Purpose Sets the count of strings and lines found by the last FIND or RFIND command into named variables. Format ISREDIT (var1,var2) = FIND_COUNTS Operands var1 The name of a variable to contain the number of strings found. The number is an eight digit value left-padded with zeros. var2 The name of a variable to contain the number of lines found. The number is an eight digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the number of strings and lines containing string IF into variables V1 and V2 respectively: 'ISREDIT FIND ALL IF' 'ISREDIT (V1,V2) = FIND_COUNTS' # 36.34 {FLOW_COUNTS} Purpose Sets the count of original lines and resulting lines created by the last TFLOW command into named variables. Format ISREDIT (var1,var2) = FLOW_COUNTS Operands var1 The name of a variable to contain the number of original lines. The number is an eight digit value left-padded with zeros. var2 The name of a variable to contain the number of resulting lines. The number is an eight digit value left-padded with zeros. The number of lines added or deleted from the file as a result of the last TFLOW operation can be determined by comparing the values returned. Returns 0 Normal completion 20 Severe error Example To set the number of lines before and after the TFLOW into variables V1 and V2 respectively: 'ISREDIT TFLOW' 'ISREDIT (V1,V2) = FLOW_COUNTS' IF V1 = V2 THEN DO /* number of lines unchanged */ ... END ELSE DO IF V1 > V2 THEN DO /* (V1 - V2) lines deleted */ ... END ELSE DO /* (V2 - V1) lines added */ ... END END # 36.35 {HEX} Purpose Set or retrieve the HEX profile variable. Format ISREDIT (var1,var2) = HEX ISREDIT HEX = mode ISREDIT HEX mode Operands var1 The name of a variable to contain the hexadecimal mode, either ON or OFF. var2 The name of a variable to contain the hexadecimal display method. In SPF/Pro display method is always VERT. mode Specify either ON or OFF. SPF/Pro always displays hexadecimal data in VERT format. Returns 0 Normal completion 20 Severe error Example To set hex mode and display method in variables V1 and V2 respectively: 'ISREDIT (V1,V2) = HEX' To set hex mode OFF: 'ISREDIT HEX OFF' # 36.36 {HOLD_LOCK} Purpose HOLD_LOCK controls whether the editor currently holds a lock on the file that you are editing. By default, when in the editor, SPF/Pro maintains a lock on the file you are editing to ensure that no one else can write to it or delete it concurrently. However, this lock restricts whether other programs, including friendly ones like Source Control systems, from making changes to the file from within edit macros. Format 'ISREDIT (variable) = HOLD_LOCK' 'ISREDIT HOLD_LOCK = ON' 'ISREDIT HOLD_LOCK = OFF' Operands variable The name of a variable to receive the result of the inquiry. A value of 'LOCKED' is returned if the file is locked. It may also be used to control lock status. The value of ON or OFF should be specified to change the lock status. Note: When you unlock the file that you are editing, you are leaving it available for other programs to manipulate. You may end up having the file changed underneath your edit session, or even locked while you are editing it, causing a write error or some other unexpected side effect while using it. We recommend that if you need to unlock the file for another utility, then immediately relock it after the utility is complete. Other editor commands, such as SAVE, influence lock status. So, if you unlock your file, it may become locked again by some other SPF/Pro command. Also, if you have VLOAD enabled, HOLD_LOCK = OFF forces the entire file to be loaded into memory before the file is closed. Returns 0 Normal completion 20 Severe error Example HOLD_LOCK may be used as a query as follows: 'isredit (LOCKED) = HOLD_LOCK' if (LOCKED<>'YES') then say This file is not locked /* end if */ To unlock a file and the relock it after some action: 'isredit HOLD_LOCK = OFF' address cmd ... 'isredit HOLD_LOCK = ON' # 36.37 {IMACRO} Purpose Set or retrieve the IMACRO profile variable. Format ISREDIT (varname) = IMACRO ISREDIT IMACRO = name ISREDIT IMACRO name Operands varname The name of a variable to contain the name of the initial macro. name The name of the initial macro. If NONE is specified, no initial macro is executed. NONE is returned when NONE or no initial macro was specified. Returns 0 Normal completion 4 IMACRO set not accepted 12 Invalid name specified 20 Severe error Example To set the name of the initial macro in variable V1: 'ISREDIT (V1) = IMACRO' To set the initial macro name to MYIMAC: 'ISREDIT IMACRO MYIMAC' To reset the initial macro: 'ISREDIT IMACRO NONE' # 36.38 {INSERT} Purpose Inserts one or more null lines for data entry in the current file. Format ISREDIT INSERT lptr [lines] Operands lptr The line number or label of the line after which the null lines are to be inserted. To insure that the inserted lines are visible, the line specified should be positioned to the top of the display with the LOCATE command (see example). lines The number of null lines to insert. If not specified, one line is inserted. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To position a labeled line at the top of the display and insert 5 null lines after the labeled line: 'ISREDIT LOCATE .A' 'ISREDIT INSERT .A 5' # 36.39 {LABEL} Purpose Sets or retrieves a symbolic name on a specific line. Format ISREDIT (var1,var2) = LABEL lptr ISREDIT LABEL lptr = name [level] Operands var1 The name of a variable to contain the label. var2 The name of a variable to contain the nesting level of the label. The number is a three character value left-padded with zeros. lptr The line number or label of the line which is to be labeled or queried. name The name of the label. The name must begin with a period and be followed by one to eight alphabetic characters. Visible labels are limited to five alphabetic characters. The initial letter "Z" is reserved for special editor labels. To delete a label set it to empty string (""). level Specifies the label nesting level. Level 0 is visible to the end user and all macros. Level 1 or greater is not visible to the end user. The maximum level that can be specified is the lesser of the current nesting level or 255. Returns 0 Normal completion 4 Label name not returned, specified line has no label 8 Label set, but an existing label at the same level was deleted 12 Line number specified is beyond the end of data 20 Severe error Example To set the label and nesting level of the current line into variables V1 and V2 respectively: 'ISREDIT (V1,V2) = LABEL .ZCSR' To label the current line with label .A: 'ISREDIT LABEL .ZCSR = .A' # 36.40 {LCOMMAND} Purpose Set or retrieve the LCOMMAND profile variable. Format ISREDIT (varname) = LCOMMAND ISREDIT LCOMMAND = value ISREDIT LCOMMAND value Operands varname The name of a variable to contain the current setting of LCOMMAND. value The desired setting for profile variable LCOMMAND. The value may be: ON Specifies that the line command field is to be visible. OFF Specifies that the line command field is to be invisible. See Options 0.3 and 0.K for details on mapping keys to perform specific line commands. Returns 0 Normal completion 20 Severe error Example To retrieve profile variable LCOMMAND: 'ISREDIT (V1) = LCOMMAND' To set profile variable LCOMMAND: 'ISREDIT LCOMMAND = ON' To set profile variable LCOMMAND from variable V1: 'ISREDIT LCOMMAND = (V1)' or 'ISREDIT LCOMMAND = 'V1 # 36.41 {LEFT} Purpose Displays currently undisplayed columns to the left. Format ISREDIT LEFT amount Operands Specify scroll amount in one of the following forms: nnnn Scroll a specific number of columns. MAX Scrolls to the leftmost data column. HALF Scroll half the width of the display area. PAGE Scroll the full width of the display area. CURSOR Scrolls to place the cursor is data display column 1. DATA Same as PAGE minus one column. Returns 0 Normal completion 4 No visible lines 8 No data to display 12 Amount value required but missing 20 Severe error Example To scroll the display left by 5 columns: 'ISREDIT LEFT 5' # 36.42 {LEVEL} Purpose Sets or retrieves the current modification level. Format ISREDIT (varname) = LEVEL ISREDIT LEVEL = number ISREDIT LEVEL number Operands varname The name of a variable to contain the modification level. The number is a two digit value left-padded with zeros. number The modification level, a number in the range 0 to 99. Returns 0 Normal completion 4 STATS off, command ignored 12 Invalid value specified 20 Severe error Example To set the modification level into variable V1: 'ISREDIT (V1) = LEVEL' To set the modification level to 1: 'ISREDIT LEVEL = 1' # 36.43 {LINE} Purpose Sets or retrieves data from a specified line. Format ISREDIT (varname) = LINE lptr ISREDIT LINE lptr = data Operands varname The name of a variable to contain the contents of the specified line. lptr The line number or label of the line to be set or retrieved. data Data may be in one of the following forms: - Simple string - Delimited string - Variable - Template () - Merge format (string-1 + string-2, keyword + string-2, string-1 + keyword) - Keyword: LINE Data from the current line. LINE lptr Data from the identified line. MASKLINE Data from the mask line. TABSLINE Data from the tabs line. Returns 0 Normal completion 4 Data truncated 8 Variable not found 12 Invalid line number 16 Variable data truncated 20 Severe error Example To create a comment starting in column 1 and ending in column 72: 'ISREDIT LINE 1 = < 1 "/*" 71 "*/" >' To overlay the first two columns of line 2 with '/*': 'ISREDIT LINE 2 = LINE + "/*"' Example To merge mask line data with data from variable V1: 'ISREDIT LINE 3 = MASKLINE + "'V1'"' or 'ISREDIT LINE 3 = MASKLINE + 'V1 # 36.44 {LINE_AFTER} Purpose Inserts a line of text after a specified line in the current file. Format ISREDIT LINE_AFTER lptr = [DATALINE] data [NOTELINE] [MSGLINE ] Operands lptr The line number or label of the line that the new data will be inserted after. DATALINE The line inserted is a data line. NOTELINE The line inserted is a NOTE line. Note lines are not data lines and do not become part of the file. Note lines are identified with the string =NOTE= in the line command field. MSGLINE The line inserted is a MSG line. Message lines are not data lines and do not become part of the file. Message lines are identified with the string ==MSG> in the line command field. data Data may be in one of the following forms: - Simple string - Delimited string - Variable - Template () - Merge format (string-1 + string-2, keyword + string-2, string-1 + keyword) - Keyword: LINE Data from the previous line. LINE lptr Data from the identified line. MASKLINE Data from the mask line. TABSLINE Data from the tabs line. Returns 0 Normal completion 4 Data truncated 12 Invalid line number 20 Severe error Example To put a comment line containing text from variable V1 at the end of the file: 'ISREDIT LINE_AFTER .ZL = < 1 "/*" 4 "'V1'" 71 "*/" >' # 36.45 {LINE_BEFORE} Purpose Inserts a line of text before a specified line in the current file. Format ISREDIT LINE_BEFORE lptr = [DATALINE] data [NOTELINE] [MSGLINE ] Operands lptr The line number or label of the line that the new data will be inserted before. DATALINE The line inserted is a data line. NOTELINE The line inserted is a NOTE line. Note lines are not data lines and do not become part of the file. Note lines are identified with the string =NOTE= in the line command field. MSGLINE The line inserted is a MSG line. Message lines are not data lines and do not become part of the file. Message lines are identified with the string ==MSG> in the line command field. data Data may be in one of the following forms: - Simple string - Delimited string - Variable - Template () - Merge format (string-1 + string-2, keyword + string-2, string-1 + keyword) - Keyword: LINE Data from the following line. LINE lptr Data from the identified line. MASKLINE Data from the mask line. TABSLINE Data from the tabs line. Returns 0 Normal completion 4 Data truncated 12 Invalid line number 20 Severe error Example To put a comment line containing text from variable V1 at the start of the file: 'ISREDIT LINE_BEFORE .ZF = < 1 "/*" 4 "'V1'" 71 "*/" >' # 36.46 {LINENUM} Purpose Retrieves the relative line number of a labeled line. Format ISREDIT (varname) = LINENUM label Operands varname The name of the variable to contain the line number of the line with the specified label. The number is a six digit value left-padded with zeros. label The label for the line whose line number is requested. Returns 0 Normal completion 4 Line 0 specified 8 Label not found 12 Invalid line number 20 Severe error Example To set the number of the last line in the file into variable V1: 'ISREDIT (V1) = LINENUM .ZLAST' # 36.47 {LOCATE} Purpose Makes a line matching a specific search criteria the top display line. Format ISREDIT LOCATE [lptr] [direction] type [range] Operands lptr Specifies the line number or label of the line to locate. direction Specifies the direction of search, one of: NEXT Search from the cursor line forward. PREV Search from the cursor line backward. FIRST Search from the first line forward. LAST Search from the last line backward. type Specifies a generic line type to locate: LABEL(LAB) Locate line with a label. CHANGE(CHG) Locate change line (==CHG>). ERROR(ERR) Locate error line (==ERR>). SPECIAL(SPE) Locate special line, one of: - Profile lines (=PROF>) - Mask lines (=MASK>) - Bounds lines (=BNDS>) - Tabs lines (=TABS>) - Message lines (==MSG>) - Note lines (=NOTE=) EXCLUDED(X) Locate excluded line. COMMAND(COM) Locate line with pending line command. range Specifies the start and end line numbers or labels of a block of lines to which the locate search is to be limited. Returns 0 Normal completion 4 Line not located 8 Empty file 20 Severe error Example To locate the next line with a label: 'ISREDIT LOCATE NEXT LABEL' To locate the first special line in the file: 'ISREDIT LOCATE FIRST SPECIAL' To locate the last excluded line: 'ISREDIT LOCATE LAST X' To locate the previous line with an unexecuted line command: 'ISREDIT LOCATE PREV COM' # 36.48 {LRECL} Purpose Set the logical record length of the current file in a named variable. Format ISREDIT (varname) = LRECL Operands varname The name of a variable to contain the logical record length of the current file. The number is a three digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the logical record length into variable V1: 'ISREDIT (V1) = LRECL' # 36.49 {MACRO} Purpose Identifies an SPF/Pro macro, its parameters, and processing conditions to be applied. Format ISREDIT MACRO [var1 [,var2,...]] [PROCESS ] [NOPROCESS] Operands var1, ... The names of variables to contain parameter values passed to the macro. Parameters are tokenized on the blank character. Variables are filled from left to right. If there are more parameters than variables, the remaining parameters are all placed in the last (right most) variable. If there are fewer parameters than variables, the unused variables are set to a null string. Single or double quotes may be used to prevent tokenization of strings containing blanks. PROCESS Specifies that pending data changes and line commands be processed immediately. NOPROCESS Specifies that pending data changes and line commands not be processed. If this macro expects to process its own line commands, NOPROCESS must be used to prevent processing of line commands before the macro gets control. Processing of pending input is done when a PROCESS command is encountered or at the end of the macro. See page for details on synchronization of processing. Returns 0 Normal completion 20 Severe error Example To begin a macro that accepts no parameters and processes pending input prior to the macro proper getting control: 'ISREDIT MACRO' To begin a macro that accepts one parameter and processes pending input prior to the macro proper getting control: 'ISREDIT MACRO (P1)' To begin a macro that accepts two parameters and does not process pending input prior to the macro proper getting control: 'ISREDIT MACRO (P1,P2) NOPROCESS' ... macro body ... 'ISREDIT PROCESS' /* process pending input now */ ... more macro body ... # 36.50 {MACRO_LEVEL} Purpose Retrieves the nesting level of the current macro. Format ISREDIT (varname) = MACRO_LEVEL Operands varname The name of a variable to contain the macro nesting level. The number is a three digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the current macro nesting level into variable V1: 'ISREDIT (V1) = MACRO_LEVEL' # 36.51 {MASKLINE} Purpose Set or retrieve the MASKLINE profile variable. Format ISREDIT (varname) = MASKLINE ISREDIT MASKLINE = data Operands varname The name of a variable to contain the MASK line data. data Data may be in one of the following forms: - Simple string - Delimited string - Variable - Template () - Merge format (string-1 = string-2, keyword + string-2, string-1 + keyword) - Keyword: LINE lptr Data from the specified line. MASKLINE Data from the mask line. TABSLINE Data from the tabs line. Returns 0 Normal completion 4 Data truncated 16 Variable data truncated 20 Severe error Example To set a comment mask from column 36 to 72: 'ISREDIT MASKLINE = < 36 "/*" 71 "*/" >' # 36.52 {MEMBER} Purpose Retrieves the name of the current file. Format ISREDIT (varname) = MEMBER Operands varname The name of a variable to contain the name of the current file. Returns 0 Normal completion 20 Severe error Example To set the current file name into variable V1: 'ISREDIT (V1) = MEMBER' Note the difference between MEMBER and DATASET: 'isredit (name1) = MEMBER' 'isredit (name2) = DATASET' would set the variables as follows: name1 == AUTOEXEC.BAT name2 == C:\AUTOEXEC.BAT # 36.53 {MOVE} Purpose Moves another file into the current file. Format ISREDIT MOVE file-name [AFTER ] lptr [BEFORE] Operands filename The name of the file to be moved. AFTER The relative position where the new data is to be inserted. BEFORE The relative position where the new data is to be inserted. lptr The line number or label of the destination line within the current file. Returns 0 Normal completion 8 End of data before last record read 12 Invalid line pointer (lptr); file not found 16 End of data before first record read 20 Severe error Example To move the contents of file XYZ to the start of the current file: 'ISREDIT MOVE XYZ AFTER 0' To move the contents of file XYZ preceding the current line position: 'ISREDIT MOVE XYZ BEFORE .ZCSR' # 36.54 {NOTE} Purpose Set or retrieves the NOTE profile variable. Format ISREDIT (varname) = NOTE ISREDIT NOTE = mode ISREDIT NOTE mode Operands varname The name of a variable to contain the note mode, either ON or OFF. mode The note mode, one of: ON Note lines will be displayed. OFF Note lines will not be displayed. Returns 0 Normal completion 20 Severe error Example To set the value of note mode in variable V1: 'ISREDIT (V1) = NOTE' To set note mode OFF: 'ISREDIT NOTE = OFF' # 36.55 {NUMBER} Purpose Set or retrieves the NUMBER profile variable. Format ISREDIT (var1,var2) = NUMBER ISREDIT NUMBER = mode ISREDIT NUMBER mode Operands var1 The name of a variable to contain the number mode, either ON or OFF. var2 The name of a variable to contain the number type a combination of STD, COBOL, and DISPLAY. mode The number mode and type, a combination of: ON Turns number mode on. Also verifies that lines are in ascending order and if not, renumbers them. OFF Turns number mode off. STD If number mode is ON, numbers sequentially in the standard sequence field (columns 73 through 80). COBOL If number mode is ON, numbers sequentially in the COBOL sequence field (columns 1 through 6). DISPLAY Specifies that lines are to be presented so that the number field is displayed. For COBOL numbered lines, the number field (columns 1 through 6) is presented to the right of the line command field in display columns 8 through 13. For STD numbered lines, the number field (columns 73 through 80) is presented on the far right in display columns 73 through 80, data columns 1 through 7 are obscured by the line command field and boundary. Returns 0 Normal completion 20 Severe error Example To set the number mode and type into variables V1 and V2 respectively: 'ISREDIT (v1,v2) = NUMBER' To set the number mode ON and number type COBOL: 'ISREDIT NUMBER = ON COBOL' # 36.56 {PASTE} Purpose Insert a block of lines from the clipboard at the A or B line. Operation is identical to the PASTE primary command. Format ISREDIT PASTE Returns 0 Normal completion 20 Severe error # 36.57 {PROCESS} Purpose Specifies that pending line commands and data are to be processed. Format ISREDIT PROCESS [DEST] [RANGE cmd1 [cmd2]] Operands DEST Specifies that the editor label .ZDEST be set to one of: - The line following a .A line command. - The line containing a .B line command. - If neither .A or .B line commands are present, the last line in the file. RANGE cmd1 [cmd2] specifies that editor label .ZFRANGE be set to the line number of the line containing a "cmd1" line command and that label .ZLRANGE be set to the line number of the line containing a "cmd2" line command. If "cmd2" is not specified .ZLRANGE is set to the same line as .ZFRANGE. If "cmd1" is not found, .ZFRANGE is set to the first line in the file and .ZLRANGE is set to the last line in the file. The line command name specified in "cmd1" or "cmd2" may not exceed six characters. It may contain any alphabetic or special character except blank, hyphen(-), apostrophe('), or numbers. Returns 0 Normal completion 4 Range expected but not present; defaults set 8 Destination expected but not present; defaults set 12 Both range and destination expected but not present; defaults set 16 Incomplete or conflicting line commands 20 Severe error Example To set .ZDEST to the line associated with the .A or .B line command: 'ISREDIT MACRO NOPROCESS' ... body of macro ... 'ISREDIT PROCESS DEST' IF RC = 0 THEN DO /* A or B found, insert new data */ END ELSE DO /* A or B not found */ END To set .ZFRANGE and .ZLRANGE to the lines with line commands BEGIN and END respectively: 'ISREDIT MACRO NOPROCESS' ... body of macro ... 'ISREDIT PROCESS RANGE BEGIN END' IF RC = 0 THEN DO /* BEGIN/END block of lines found */ END ELSE DO /* BEGIN/END block of lines not found */ END # 36.58 {PROFILE} Purpose Displays the current edit profile. It can also be used to choose an edit profile for a different extension or lock the current profile. Format ISREDIT PROFILE name [number] number LOCK UNLOCK Operands name Specifies the profile name that you would like to change to. If the specified name does not exist, a new profile is created using the parameters that are in effect when the ISREDIT PROFILE command is processed. number The number of profile lines to display. You can specify any number from 1 to 8. The default is 4, the maximum is 8. If you don't want to see the profile lines, enter RESET or PROFILE 0. LOCK Save and lock the profile. All current modes and options are saved and marked so that they can not be overwritten. Each time that an edit session is begun, the locked profile is re-called exactly as it was when it was locked. Changes made during a new edit session affect only the current edit session, and not subsequent sessions. UNLOCK Unlock the current edit profile so that it can be changed. Returns 0 Normal completion 20 Severe error Example To display profile variables: 'ISREDIT PROFILE' # 36.59 {RANGE_CMD} Purpose Identifies the first line command captured by the PROCESS RANGE command. Format ISREDIT (varname) = RANGE_CMD Operands varname The name of a variable to contain the line command captured by PROCESS RANGE. Returns 0 Normal completion 4 Line command not set 8 Line command setting not acceptable 20 Severe error Example To capture a range of possible line commands and then selectively process them: 'ISREDIT MACRO NOPROCESS' ... body of macro ... 'ISREDIT PROCESS RANGE X Y' IF RC = 0 THEN DO /* line command found */ 'ISREDIT (V1) = RANGE_CMD' IF V1 = "X" THEN DO /* process X line command */ END ELSE DO /* process Y line command */ END END ELSE DO /* line command not found */ END # 36.60 {RCHANGE} Purpose Repeats the most recent CHANGE command. Format ISREDIT RCHANGE Returns 0 Normal completion 4 String not found 8 Change error ('to' string longer than 'from' string and substitution was not performed on at least one change) 12 Syntax error 20 Severe error Example To repeat the last CHANGE command: 'ISREDIT RCHANGE' # 36.61 {READ_ONLY} Purpose READ_ONLY returns YES or NO based upon whether the editor originally opened the file a Read Only (the RO attribute was on) or Write Protected (could not get exclusive access to the file). For example: Format 'isredit (variable) = READ_ONLY' Operands varname The name of a variable to contain the current setting of the READ_ONLY status. Returns 0 Normal completion 20 Severe error Example 'isredit (RO) = READ_ONLY' if (RO='YES') then say The file is either read only or write protected. /* end if */ # 36.62 {RECFM} Purpose Retrieves the record format of the current file and stores the value in a variable. Format ISREDIT (varname) = RECFM Operands varname The name of a variable to contain the record format. Returns one of the following values. L (length-delimited), D (data-delimited), M (Micro Focus Header Variable), or V (Micro Focus VRECGEN). Returns 0 Normal completion 20 Severe error Example To set the record format into variable V1: 'ISREDIT (V1) = RECFM' # 36.63 {REDO} Purpose Following an UNDO, redo the last undo. Parameters are identical to the REDO primary command. Format ISREDIT REDO [ nnn | ALL ] Returns 0 Normal completion 20 Severe error # 36.64 {RENUM} Purpose Turns number mode on and renumbers all lines. Parameters are identical to the NUMBER command. Format ISREDIT RENUM [ COBOL ] [ STD ] [ DISPLAY ] Returns 0 Normal completion 20 Severe error Example To renumber all program source lines in columns 1 through 6: 'ISREDIT RENUM COBOL' # 36.65 {REPLACE} Purpose Replaces an existing file with all or part of the current file. Format ISREDIT REPLACE filename range Operands filename The name of the file to be replaced. range The start and end line numbers or labels of a block of lines to replace the named file. Returns 0 Normal completion 12 Invalid line pointer; file not found 20 Severe error Example To replace file XYZ with the first 10 lines of the current file: 'ISREDIT REPLACE XYZ 1 10' # 36.66 {RESET} Purpose Restores the status of data lines and removes special lines. Format ISREDIT RESET [type] [range] Operands type Specifies the line type to be reset, one of: LABEL Reset labels on labeled lines. (short form: LAB) CHANGE Reset (==CHG>) flags on changed lines. (short form: CHG) ERROR Reset (==ERR>) flags on error lines. (short form: ERR) SPECIAL Reset special lines. (short form: SPEC) -- Profile lines (=PROF>) -- Mask lines (=MASK>) -- Bounds line (=BNDS>) -- Tabs line (=TABS>) -- Message lines (==MSG>) -- Note lines (=NOTE=) EXCLUDED Makes excluded lines visible. (short form: EXC) COMMAND(COM) Reset pending line commands. (short form: COM) range The start and end line numbers or labels of a block of lines to which the reset is to apply. Returns 0 Normal completion 20 Severe error Example To reset all special lines: 'ISREDIT RESET SPECIAL' # 36.67 {RFIND} Purpose Repeats the most recent FIND command. Format ISREDIT RFIND Returns 0 Normal completion 4 String not found 12 Syntax error 20 Severe error Example To repeat the most recent FIND command: 'ISREDIT RFIND' # 36.68 {RIGHT} Purpose Displays currently undisplayed columns to the right. Format ISREDIT RIGHT amount Operands Specify scroll amount in one of the following forms: nnnn Scroll a specific number of columns. MAX Scrolls to the right most data column. HALF Scroll half the width of the display area. PAGE Scroll the full width of the display area. CURSOR Scrolls to place the cursor in the right most display column. DATA Same as PAGE minus one column. Returns 0 Normal completion 4 No visible lines 8 No data to display 12 Amount value required but missing 20 Severe error Example To scroll the display right by 5 columns: 'ISREDIT RIGHT 5' # 36.69 {SAVE} Purpose Saves the current file without terminating the edit session. Format ISREDIT SAVE Returns 0 Normal completion 4 New file saved 12 Data not saved 20 Severe error Example To save the current file: 'ISREDIT SAVE' # 36.70 {SAVECOUNT} Purpose Set or retrieve the SAVECOUNT profile variable. Format ISREDIT (varname) = SAVECOUNT ISREDIT SAVECOUNT = value ISREDIT SAVECOUNT value Operands varname The name of a variable to contain the current setting of SAVECOUNT. value The desired setting for profile variable SAVECOUNT. The value is the number of [SPF-Enter] keys pressed before an automatic save is performed. Returns 0 Normal completion 20 Severe error Example To retrieve profile variable SAVECOUNT: 'ISREDIT (V1) = SAVECOUNT' To set profile variable SAVECOUNT: 'ISREDIT SAVECOUNT = 10' To set profile variable SAVECOUNT from variable V1: 'ISREDIT SAVECOUNT = (V1)' or 'ISREDIT SAVECOUNT = 'V1 # 36.71 {SAVE_ENABLED} Purpose SAVE_ENABLED returns YES or NO based upon whether the SAVE command is enabled in the current edit session. The editor disables the save command when it encounters a severe error during load, encounters an out of memory error during processing of a command, or if you are editing a read-only file or a write-protected file. Format 'ISREDIT (varname) = SAVE_ENABLED' Operands varname The name of a variable to contain the current setting of SAVE_ENABLED. The value will be YES or NO. Returns 0 Normal completion 20 Severe error Example 'isredit (SAVEON) = SAVE_ENABLED' if (SAVEON\='YES') then say Save is disabled! /* end if */ # 36.72 {SCAN} Purpose Sets or retrieves the scan mode. Format ISREDIT (varname) = SCAN ISREDIT SCAN = mode ISREDIT SCAN mode Operands varname The name of a variable to contain the scan mode, either ON or OFF. mode The scan mode: ON Resolve variable values in command lines. OFF Do not resolve variable values in command lines. Returns 0 Normal completion 20 Severe error Example To set the scan mode in variable V1: 'ISREDIT (V1) = SCAN' To set scan mode ON: 'ISREDIT SCAN = ON' # 36.73 {SCOPY} Purpose Copy the current selection to the clipboard. Format ISREDIT SCOPY Returns 0 Normal completion 20 Severe error # 36.74 {SCREATE} Purpose Create a new file with the current selection contents. Parameters are identical to the SCREATE primary command. Format ISREDIT SCREATE [ file-name ] Returns 0 Normal completion 20 Severe error # 36.75 {SCUT} Purpose Copy the current selection to the clipboard, then delete the selection. Format ISREDIT SCUT Returns 0 Normal completion 20 Severe error # 36.76 {SDELETE} Purpose Delete the current selection. Format ISREDIT SDELETE Returns 0 Normal completion 20 Severe error # 36.77 {SEEK} Purpose The SEEK macro command is identical in syntax and function to the FIND primary command except that it does not expose excluded lines or update the display. When using SEEK in a macro it is advisable to save the current bounds and then set them to a known value. On exit restore the bounds to the saved values. See page 630 for details. Format ISREDIT SEEK ... Returns 0 Normal completion 4 String not found 12 Syntax error 20 Severe error Example To seek the next line containing an IF statement: 'ISREDIT SEEK IF' # 36.78 {SEEK_COUNTS} Purpose Sets the count of strings and lines found by the last SEEK command into named variables. Format ISREDIT (var1,var2) = SEEK_COUNTS Operands var1 The name of a variable to contain the number of strings found. The number is an eight digit value left-padded with zeros. var2 The name of a variable to contain the number of lines found. The number is an eight digit value left-padded with zeros. Returns 0 Normal completion 20 Severe error Example To set the number of strings and lines containing string IF into variables V1 and V2 respectively: 'ISREDIT SEEK ALL IF' 'ISREDIT (V1,V2) = SEEK_COUNTS' # 36.79 {SHIFT (} Purpose Moves data left using column shift logic. Format ISREDIT SHIFT ( lptr [n] Operands lptr The line number or label of the line to shift. n The number of columns to shift. If not specified, 2 is assumed. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To column shift the current line left 2 columns: 'ISREDIT SHIFT ( .ZCSR' # 36.80 {SHIFT )} Purpose Moves data right using column shift logic. Format ISREDIT SHIFT ) lptr [n] Operands lptr The line number or label of the line to shift. n The number of columns to shift. If not specified, 2 is assumed. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To column shift line 5 right 10 columns: 'ISREDIT SHIFT ) 5 10' # 36.81 {SHIFT <} Purpose Moves data left using data shift logic. Format ISREDIT SHIFT < lptr [n] Operands lptr The line number or label of the line to shift. n The number of columns to shift. If not specified, 2 is assumed. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To data shift the current line left 2 columns: 'ISREDIT SHIFT < .ZCSR' # 36.83 {SORT} Purpose The SORT macro command is identical in syntax and function to the SORT primary command. Format ISREDIT SORT ... Returns 0 Normal completion 4 Lines already in sort order 20 Severe error Example To sort all the lines in the file in ascending order: 'ISREDIT SORT' # 36.84 {SPASTE} Purpose Insert the contents of the clipboard at the current cursor position. Parameters are identical to the SPASTE primary command. Format ISREDIT SPASTE [ INSERT | OVERLAY ] [ LINE | STREAM | BLOCK ] Returns 0 Normal completion 20 Severe error # 36.85 {SREPLACE} Purpose Replace an existing file with the current selection contents. Parameters are identical to the SREPLACE primary command. Format ISREDIT SREPLACE [ file-name ] Returns 0 Normal completion 20 Severe error # 36.86 {STATS} Purpose Sets or retrieves the current STATS mode. Format ISREDIT (varname) = STATS ISREDIT STATS = mode ISREDIT STATS mode Operands varname The name of a variable to contain the current STATS mode, either ON or OFF. mode The stats mode: ON Statistics will be created and saved. OFF Statistics will not be created or saved. Returns 0 Normal completion 20 Severe error Example To put the current STATS mode in variable V1: 'ISREDIT (V1) = STATS' To set STATS mode ON: 'ISREDIT STATS = ON' # 36.87 {STOLOWER} Purpose Convert all the alpha characters in the current selection to lower case. Format ISREDIT STOLOWER Returns 0 Normal completion 20 Severe error # 36.88 {STOUPPER} Purpose Convert all the alpha characters in the current selection to uppercase. Format ISREDIT STOUPPER Returns 0 Normal completion 20 Severe error # 36.89 {SXCLUDE} Purpose Exclude all lines touched by the current selection. Format ISREDIT SXCLUDE Returns 0 Normal completion 20 Severe error # 36.90 {TABS} Purpose Set or retrieve the TABS profile variable. Format ISREDIT (var1,var2) = TABS ISREDIT TABS = mode [tab-char] [ALL|STD] ISREDIT TABS mode [tab-char] [ALL|STD] Operands var1 The name of a variable to contain the TABS mode, either ON or OFF. var2 The name of a variable to contain the logical tab character and the tabs type, either ALL, STD, or blanks. mode The tabs mode: ON Logical tabs are processed. OFF Logical tabs are not processed. tab-char Specifies the logical tab character. ALL Sets all standard hardware tabs. On the mainframe using a 3270 the hardware attribute byte overlays data characters in hardware tab columns; on the PC these characters are preserved. STD Same as ALL. Returns 0 Normal completion 20 Severe error Example To set the TABS mode and type into variables V1 and V2 respectively: 'ISREDIT (V1,V2) = TABS' To set the tab character to "\" and set the tabs mode ON: 'ISREDIT TABS ON \' # 36.91 {TABSLINE} Purpose Set or retrieve the TABSLINE profile variable. Format ISREDIT (varname) = TABSLINE ISREDIT TABSLINE = data Operands varname The name of a variable to contain the contents of the current tabs line. data The data for the TABS line. Valid characters for the TABS line are: asterisk(*), hyphen(-), and underscore(_). The following forms can be used: - Simple string - Delimited string - Variable - Template () - Merge format (string-1 + string-2, keyword + string-2, string-1 + keyword) - Keyword: LINE lptr Data from the specified line. MASKLINE Data from the mask line. TABSLINE Data from the tabs line. Returns 0 Normal completion 4 Data truncated 8 Invalid data detected and ignored 20 Severe error Example To set the value of the tabs line in variable V1: 'ISREDIT (V1) = TABSLINE' To clear the tabs line: 'ISREDIT TABSLINE = " "' To set tabs in columns 5 and 20: 'ISREDIT TABSLINE = <5,*,20,*>' To add a tab in column 30: 'ISREDIT TABSLINE = TABSLINE + <30,*>' To remove a tab from column 30: 'ISREDIT TABSLINE = TABSLINE + <30," ">' # 36.92 {TENTER} Purpose Provides blank screen space for text entry (same as TE line command). Format ISREDIT TENTER lptr [n] Operands lptr The line number or label of the line where the text entry space is to be provided. To insure that the entry space is visible on the screen, do a locate on the target line. n The number of lines of text entry space to be provided. If not specified, the remainder of the screen is used. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To provide 5 lines of text entry space at line 10: 'ISREDIT LOCATE 10' 'ISREDIT TENTER 10 5' # 36.93 {TFLOW} Purpose Composes a block of text within current BOUNDS. Lines are flowed to a maximum width as is common in word processors. Text flow ends when a blank line, an indented line, or the character period(.), colon (:), ampersand (&), or less-than (<) is encountered in column one of an original line. Format ISREDIT TFLOW lptr [col] Operands lptr The line number or label of the line where TFLOW is to begin. col The right most column for the flowed text. If the column number is not specified, the text is flowed within the current BOUNDS. This command differs from the TF line command in that it is not sensitive to display width. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To flow text into columns 1 through 72: 'ISREDIT BOUNDS' 'ISREDIT TFLOW 1 72' # 36.94 {TJOIN} Purpose Joins the current line with the following line; the inverse of TSPLIT. Format ISREDIT TJOIN [lptr] Operands lptr The line number or label of the line to be joined. Returns 0 Normal completion 20 Severe error Example To join the current line with the following line: 'ISREDIT TJOIN .ZCSR' # 36.95 {TSPLIT} Purpose Splits a line so that additional text can be inserted. Format ISREDIT TSPLIT [lptr col] Operands lptr The line number or label of the line to be split. col The column where the text is to be split. If not specified, the line is split at the current cursor position. Returns 0 Normal completion 12 Invalid line number 20 Severe error Example To split the current line at column 10: 'ISREDIT TSPLIT .ZCSR 10' # 36.96 {UNDO} Purpose Undo the last edit transaction. Parameters are identical to the UNDO primary command. Format ISREDIT UNDO [ nnn | ALL ] Returns 0 Normal completion 20 Severe error # 36.97 {UNNUM} Purpose Turns NUMBER mode off and removes line numbers. Format ISREDIT UNNUM Returns 0 Normal completion 12 Number mode not on 20 Severe error Example To turn number mode off and unnumber the lines: 'ISREDIT UNNUM' # 36.98 {UP} Purpose Displays the previous frame of lines in the file. Format ISREDIT UP amt Operands Specify scroll amount in one of the following forms: nnnn The number of lines to scroll. MAX Scroll to the top of the file. HALF Scroll by one half screen depth. PAGE Scroll by one full screen depth. CURSOR Scroll to make the line on which the cursor is located the first display line. DATA Same as PAGE minus one line. Returns 0 Normal completion 2 No more data 4 No visible lines 8 No data to display 12 Amount value required but missing 20 Severe error Example To scroll one full frame up: 'ISREDIT UP PAGE' # 36.99 {USER_STATE} Purpose Saves or restores user state information. This includes edit profile values, FIND and CHANGE values, and screen and cursor values. Format ISREDIT (varname) = USER_STATE ISREDIT USER_STATE = (varname) Operands varname The name of a variable to contain the user state information. State information is saved in a proprietary format. The following state information is saved and restored: AUTOLIST CURSOR PROFILE FIND AUTONUM HEX STATS CHANGE AUTOSAVE IMACRO TABS EXCLUDE BOUNDS MASKLINE TABSLINE SEEK CAPS NUMBER Returns 0 Normal completion 20 Severe error Example To set the user state in variable V1: 'ISREDIT (V1) = USER_STATE' To restore the user state from variable V1: 'ISREDIT USER_STATE = (V1)' # 36.100 {XMACRO} Purpose Set or retrieve the XMACRO profile variable. Format ISREDIT (varname) = XMACRO ISREDIT XMACRO = value ISREDIT XMACRO value Operands varname The name of a variable to contain the current setting of XMACRO. value The desired setting for profile variable XMACRO. The value is a macro name. Returns 0 Normal completion 20 Severe error Example To retrieve profile variable XMACRO: 'ISREDIT (V1) = XMACRO' To set profile variable XMACRO: 'ISREDIT XMACRO = POSTMOD' To set profile variable XMACRO from variable V1: 'ISREDIT XMACRO = (V1)' or 'ISREDIT XMACRO = 'V1 # 36.101 {XSTATUS} Purpose Sets or retrieves the exclude status of a specified line and stores the value in a variable. Format ISREDIT (varname) = XSTATUS lptr ISREDIT XSTATUS lptr = [X ] [NX] Operands varname The name of a variable to contain the exclude status, either X or NX. lptr The line number or label of the line to set or query. X Set the line status to excluded. NX Set the line status to non-excluded. Returns 0 Normal completion 8 Line status not set 12 Line number not an existing line 20 Severe error Example To set the exclude status of line 5 into variable V1: 'ISREDIT (V1) = XSTATUS 5' To set line 10 to excluded: 'ISREDIT XSTATUS 10 = X' # 37. {ISPEXEC Dialog Services} You can use REXX procedures to develop panels and extend SPF/Pro. In all cases, your programs will request SPF/Pro services with some combination of ISPEXEC and/or ISREDIT. # 37.1 {REXX and ISPEXEC} If your are using REXX, to display a panel you might code 'ISPEXEC DISPLAY PANEL(...panel-ID...)' In REXX you use ISPEXEC commands to set and examine variables and call external functions. The REXX procedure language provides conditional processing, loop control, symbol assignment, arithmetic functions, access to external files, and a variety of other useful features. Within REXX, you have access to SPF/Pro variables and state information which enables you to perform many complex tasks. REXX procedures which use ISPEXEC calls are given the file type ".ISP". REXX and ISPEXEC commands may be freely intermixed. For example, to conditionally call the DISPLAY dialog service: IF ... THEN 'ISPEXEC DISPLAY ...' To eliminate the need for explicitly specifying "ISPEXEC ..." in each dialog service call you can insert the following statement at the start of your REXX procedure: ADDRESS ISPEXEC Now your call to DISPLAY service would look like this: ADDRESS ISPEXEC ... intervening REXX statements ... IF ... THEN 'DISPLAY ...' Look at files SPFPRO\REXX\*.ISP. Late breaking news about REXX is documented in SPFPRO\README.MAC. These sources will give you insight into how REXX procedures might be applied and how to write them. Detailed information on REXX is provided in a preceding chapter. # 37.2 {Table Services} A large proportion of the Dialog Services are devoted to the creation, modification, and display of tables. Collectively these services are referred to as "Table Services". For ease of identification and clarity in documentation, all table services have a prefix of "TB...". If your panel application has no need for tables, you can safely ignore all the "TB..." services. The following table summarizes the ISPEXEC commands which are detailed in the remainder of this chapter. Command Function ADDPOP Display a panel as a sub-window on the current panel. BROWSE Browse a file (or files). CONTROL Set dialog processing options. DISPLAY Display a panel or table. EDIT Edit a file (or files). GETMSG Get elements of a message. PDSCREATE Create a PDS file format file. PDSDELETE Delete a member from a PDS. PDSEXPORT Export a member from a PDS to a file. PDSIMPORT Import a file to a PDS into a member. POPUPMENU Display a GUI popup menu on the panel. PRNCLOSE Close the default printer., PRNOPEN Open the default printer and set the headings. PRNRECORD Print a record on the default printer. REMPOP Remove the sub window displayed with ADDPOP. SELECT Invoke a function or display a menu panel. SETMSG Set message to be displayed on next panel. TBADD Add a row to a table. TBBOTTOM Position to the bottom of a table. TBCLOSE Close a table; write to disk if applicable. TBCREATE Create a new table. TBDELETE Delete a row from a table. TBDIRCREATE Create a special table to contain directory entries. TBDIRDISPL Display a table of directory entries using SPF/Pro defaults. TBDIRPOPULATE Populate a table of directory entries from a supplied file mask. TBDISPL Display a table. TBEND Close a table; don't write to disk. TBERASE Delete a disk based table. TBEXIST Determine if keyed table row exists. TBGET Load dialog vars from a table row. TBMOD Update a keyed table row. TBOPEN Open a disk based table for access. TBPUT Update a non-keyed table row. TBQUERY Get information about a particular table. TBSARG Set search args for TBSCAN or TBDISPL. TBSAVE Write a disk based table without closing. TBSCAN Search a table for a particular row. TBSKIP Position in a table and retrieve the row. TBSORT Sort a table by field(s). TBSTATS Obtain statistical information about a table. TBTOP Position to the top of a table. TBVCLEAR Clear variables in the current row. VGET Copy non-function pool var to function pool. VPUT Copy function pool var to non-function pool. # 37.1 {ADDPOP} Purpose Use this command to notify Dialog Manager that any future panels displayed are to be in a pop-up window. Nothing is actually displayed until a DISPLAY or TBDISPL is issued. This pop-up has to be removed before you can return to the panel below it. Use the REMPOP command to remove it. Pop-up windows can be moved by clicking on a border with the mouse and dragging. The window size is defined by the WINDOW(x,y) command in the )BODY section of a panel definition. ISPEXEC Syntax ISPEXEC ADDPOP [ POPLOC(field-name) ] [ ROW(row) ] [ COLUMN(column) ] Operands POPLOC Optional. Specifies the field on the current panel where the upper left of corner of the pop-up window is to render. ROW Optional. Specifies the row offset where the upper left corner of the pop-up window is to render. COLUMN Optional. Specifies the column offset where the upper left corner of the pop-up window is to render. Returns 0 Normal completion 4 A second ADDPOP call was issued before a panel was displayed. 20 Severe error Example Display an addpop window. 'ISPEXEC ADDPOP POPLOC(ZCMD) ROW(5) COL(5)' 'ISPEXEC DISPLAY TESTPAN' 'ISPEXEC REMPOP' # 37.2 {BROWSE} Purpose Use this command to browse a file or files. ISPEXEC Syntax ISPEXEC BROWSE FILE(file-name) [ PANEL(panel-ID) ] [ PROFILE(profile-name) ] [ LRECL(max-lrecl) ] [ EDITMAC(YES|NO) ] [ IMACRO(macro-name) ] Operands FILE Required. Specifies the name of the file to BROWSE. If the file name is a directory, or is ambiguous (contains * or ?), or is not specified, a select list of the corresponding files is presented. You can subsequently select the desired files from the list. PANEL Optional. Specifies the panel ID for the panel to be used in place of the standard BROWSE panel. PROFILE Optional. Specifies the name of the profile to be used for reading the file. If not specified, the profile is determined by the file type. LRECL Optional. Specifies the maximum allowed record length. EDITMAC Optional. If YES is specified, Edit Macros can be issued against the file even though it is in Browse mode. Edit macros which attempt to change the file will fail with a return code 20. IMACRO Optional. Specifies the name of an ISREDIT macro to be executed after the file is read but before it is displayed. This option can only be used if EDITMAC(YES) is specified. Returns 0 Normal completion 20 Severe error Example To browse file CAP2.COB: ISPEXEC BROWSE FILE(CAP2.COB) # 37.3 {CONTROL} Purpose Use this command to set processing options for the dialog environment. ISPEXEC Syntax ISPEXEC CONTROL [ DISPLAY LOCK | DISPLAY LINE ] [ ERRORS CANCEL | ERRORS RETURN ] [ SPLIT ENABLE | SPLIT DISABLE ] Operands DISPLAY Optional. Specifies different display modes. LOCK Specifies that after the next panel or table is displayed, that keyboard input is to be disabled. The most typical use for this feature is to display an "in progress" message when a long running transaction is taking place. The "locked" condition is cleared the next time a message or panel is displayed. LINE Specifies that line output is expected from the task running on behalf of the current panel. For example, this keyword would be specified when running a system command in response to panel input. ERRORS Optional. Specifies the action to be taken when any ISPEXEC error occurs. CANCEL Set the CANCEL error code. Terminate the task with an error message. RETURN Set the RETURN error code. Don't issue an error message. Return to the task which requested the function in error. SPLIT Optional. Use this keyword to specify whether SPLIT screen operations are allowed. ENABLE Enable SPLIT screen operations. DISABLE Disable SPLIT screen operations. Returns 0 Normal completion 8 SPLIT screen mode already enabled or disabled. 20 Severe error Example ISPEXEC CONTROL DISPLAY LOCK ISPEXEC CONTROL ERRORS RETURN ISPEXEC CONTROL SPLIT ENABLE # 37.4 {DISPLAY} Purpose Use this command to display a panel or table. After the INIT section of the panel is processed, the panel is displayed with corresponding dialog variables filled in and an optional message is displayed. After [SPF-Enter] is pressed, user input is stored in dialog variables and the PROC section of the panel is processed. After the PROC section is processed, control returns to the calling function. ISPEXEC Syntax ISPEXEC DISPLAY [ PANEL(panel-ID) ] [ MSG(message-ID) ] [ CURSOR(field-name) ] [ CSRPOS(cursor-position) ] Operands PANEL Optional. Specifies the panel-id for the panel which you want displayed. If no panel-ID is specified, the last panel requested is re-displayed; the REINIT section is processed prior to display. MSG Optional. Specifies the message-ID of a message that you want displayed along with the requested panel. CURSOR Optional. Specifies the name of the input field in which you want the cursor placed when the panel is displayed. If not specified, the cursor is placed in the first input field. CSRPOS Optional. Specifies the cursor position within the current input field. If not specified, 1 is assumed. Returns 0 Normal completion 8 User requested termination via END, RETURN, or =... 12 The specified, panel, message, or field could not be found. 16 TRUNC or TRANS error in processing input variables. 20 Severe error Example To display a panel: ISPEXEC DISPLAY PANEL(S2XXS015) To display a panel with a message: ISPEXEC DISPLAY PANEL(S2XXS015) MSG(SPFD211) To display a panel and put the cursor in field NAME: ISPEXEC DISPLAY PANEL(S2XXS015) CURSOR(NAME) To display a panel with the cursor in field DISP at char position 5: ISPEXEC DISPLAY PANEL(S2XXS015) CURSOR(DISP) CSRPOS(5) To re-display the last panel that was displayed: ISPEXEC DISPLAY # 37.5 {EDIT} Purpose Use this command to edit a file or files. ISPEXEC Syntax ISPEXEC EDIT FILE(file-name) [ PANEL(panel-ID) ] [ MACRO(edit-macro-name) ] [ PROFILE(profile-name) ] [ LRECL(max-lrecl) ] [ XMACRO(macro-name) ] [ ERRORFILE(file-name) ] Operands FILE Required. Specifies the name of the file to EDIT. If the file name is a directory, or is ambiguous (contains * or ?), or is not specified, a select list of the corresponding files is presented. You can subsequently select the desired files from the list. PANEL Optional. Specifies the panel ID for the panel to be used in place of the standard EDIT panel. MACRO Optional. Specifies the name of an ISREDIT macro to be executed after the file is read but before it is displayed. (You can also specify IMACRO.) PROFILE Optional. Specifies the name of the profile to be used for reading and writing the file. If not specified, the profile is determined by the file type. LRECL Optional. Specifies the maximum allowed record length. XMACRO Optional. Specifies the name of an ISREDIT macro to be executed as the edit session is ending before the file is written. XMACRO is not executed when SAVE is processed. ERRORFILE Optional. Specifies the name of a compiler error message file that is to be merged with the file before it is displayed. Returns 0 Normal completion 20 Severe error Example To edit file CAP2.COB: ISPEXEC EDIT FILE(CAP2.COB) # 37.6 {GETMSG} Purpose Use this command to retrieve information related to a particular message. ISPEXEC Syntax ISPEXEC GETMSG MSG(message-ID) [ SHORTMSG(sm-var-name) ] [ LONGMSG(lm-var-name) ] [ ALARM(al-var-name) ] [ HELP(hl-var-name) ] Operands MSG Required. Specifies the message-ID for the message to be queried. If only the MSG parameter is specified, the existence of the message is checked and indicated by the return code; 0 = message present, 12 = message not found. SHORTMSG Optional. Specifies the name of the variable into which the short message text will be stored. LONGMSG Optional. Specifies the name of the variable into which the long message text will be stored. ALARM Optional. Specifies the name of the variable into which the alarm status will be stored. The status will be "YES" or "NO". HELP Optional. Specifies the name of the variable into which the help panel-ID will be stored. Returns 0 Normal completion 12 The specified message could not be found. 20 Severe error Example To retrieve the long message text for message SPFD102 and place it in variable LMSGTXT: ISPEXEC GETMSG MSG(SPFD102) LONGMSG(LMSGTXT) # 37.7 {PDSCREATE} Purpose Use this command to create a new PDS file. ISPEXEC Syntax ISPEXEC PDSCREATE PDSFILE(pds_name) SIZE(allocation_unit_size) Operands PDSFILE Required. Specifies the path and name of the new PDS file. SIZE Required. Specifies the internal allocation unit size of the new PDS. When a PDS member is imported, space is allocated as necessary to accomodate the new member. The space allocation is done in allocation units. In the ideal case, the allocation unit size for a particular PDS will closely match the size of most members. For example, if 300 members have a size <= 1024, and 50 members have a size > 1024, set the allocation unit size to 1024. In this case 300 of the members will fit into a single allocation unit, while 50 of the members will require two or more allocation units. If you are in doubt at to how to set the allocation unit size use the average size of the members: TOTAL SIZE / TOTAL MEMBERS = MEAN MEMBER SIZE If you are still in doubt, use 1024. Returns 0 Normal completion 20 Severe Error 101 PDS is corrupt 102 Out of memory 103 PDS exists 104 PDS does not exist 105 PDS is open and locked 106 Could not open PDS 107 PDS read error, seek 108 PDS read error 109 PDS write error 110 PDS close error 111 Member not found 112 Member is read-only 113 Member name too long 114 PDS too big, Out of allocation units 115 PDS too big, Out of directory entries 116 Bad unit address 117 PDS compression error 118 PDS CHsize error 119 PDS too big, compression error 120 Member name invalid 121 Unknown error Example To create a new PDS: ISPEXEC PDSCREATE PDSFILE(c:\test.pds) SIZE(1024) # 37.8 {PDSDELETE} Purpose Use this command to delete a member from a PDS file. ISPEXEC Syntax ISPEXEC PDSDELETE PDSFILE(pds_name) MEMBER(member_name) Operands PDSFILE Required. Specifies the path and name of the PDS file. MEMBER Required. Specifies the member you wish to delete. Returns 0 Normal completion 20 Severe Error 101 PDS is corrupt 102 Out of memory 103 PDS exists 104 PDS does not exist 105 PDS is open and locked 106 Could not open PDS 107 PDS read error, seek 108 PDS read error 109 PDS write error 110 PDS close error 111 Member not found 112 Member is read-only 113 Member name too long 114 PDS too big, Out of allocation units 115 PDS too big, Out of directory entries 116 Bad unit address 117 PDS compression error 118 PDS CHsize error 119 PDS too big, compression error 120 Member name invalid 121 Unknown error Example To delete a member of a PDS: ISPEXEC PDSDELETE PDSFILE(c:\test.pds) MEMBER(test.pan) # 37.9 {PDSEXPORT} Purpose Use this command to create a new file from a member in the PDS. This DOES NOT remove the member from the PDS. ISPEXEC Syntax ISPEXEC PDSEXPORT PDSFILE(pds_name) MEMBER(member_name) FILE(file_name) Operands PDSFILE Required. Specifies the path and name of the PDS file. MEMBER Required. Specifies the member you wish to export. FILE Required. Specifies the path and filename you wish to create. Returns 0 Normal completion 20 Severe Error 101 PDS is corrupt 102 Out of memory 103 PDS exists 104 PDS does not exist 105 PDS is open and locked 106 Could not open PDS 107 PDS read error, seek 108 PDS read error 109 PDS write error 110 PDS close error 111 Member not found 112 Member is read-only 113 Member name too long 114 PDS too big, Out of allocation units 115 PDS too big, Out of directory entries 116 Bad unit address 117 PDS compression error 118 PDS CHsize error 119 PDS too big, compression error 120 Member name invalid 121 Unknown error Example To export a member from a PDS: ISPEXEC PDSEXPORT PDSFILE(c:\test.pds) MEMBER(test.pan) FILE(c:\test.out) # 37.10 {PDSIMPORT} Purpose Use this command to add a member to a PDS. If the member already exists, it is overwritten. ISPEXEC Syntax ISPEXEC PDSIMPORT PDSFILE(pds_name) MEMBER(member_name) FILE(file_name) Operands PDSFILE Required. Specifies the path and name of the PDS file. MEMBER Required. Specifies the member you wish to import. FILE Required. Specifies the path and filename of the file you wish to add to the PDS. Returns 0 Normal completion 20 Severe Error 101 PDS is corrupt 102 Out of memory 103 PDS exists 104 PDS does not exist 105 PDS is open and locked 106 Could not open PDS 107 PDS read error, seek 108 PDS read error 109 PDS write error 110 PDS close error 111 Member not found 112 Member is read-only 113 Member name too long 114 PDS too big, Out of allocation units 115 PDS too big, Out of directory entries 116 Bad unit address 117 PDS compression error 118 PDS CHsize error 119 PDS too big, compression error 120 Member name invalid 121 Unknown error Example To import a member from a PDS: ISPEXEC PDSIMPORT PDSFILE(c:\test.pds) MEMBER(test.pan) FILE(c:\test.out) # 37.11 {POPUPMENU} Purpose This command causes a popup menu to appear at the specified location with a user defined list of actions. This allows you to enhance your SPF/Pro applications with context sensitive menus which can be controlled by the mouse. ISPEXEC Syntax ISPEXEC POPUPMENU MENUNAMES(list) MENUVAR(result) PAIRS(YES|NO) [ POPLOC(fieldname) ] [ ROW(rowpos) COLUMN(colpos) ] Operands MENUNAMES Required. Takes one of two forms: - If PAIRS(NO), only menu names are specified. Menu names are returned when a menu item is picked. - If PAIRS(YES), menu names and corresponding menu values are specified. Menu values are returned when a menu item is picked. Elements of the list are separated by vertical bar (|) characters. The first item in the list is not preceded by a vertical bar nor is the last item succeeded by a vertical bar. An under score character (_) can be used to cause the display of a full length horizontal separator in the popup menu to help in grouping the elements of the menu. Items in the list can be 'grayed out' by preceding their menu entry with a minus sign (-). A plus sign can be used to mean show the entry but this can be omitted as it is the default. Nested menus can also be defined by including the nested menu within brackets in the list. This sub-menu conforms to the same rules as described above. MENUVAR Required. The variable specified contains the value of the menu item selected by the user. If PAIRS(YES), it contains the second value from the pair. If PAIRS(NO), it contains the actual menu entry selected. If no item is selected, it contains null values. PAIRS Required. The choice of YES says that the data in the MENUNAMES list consists of a menu entry and the value it stands for. PAIRS(NO) indicates that the MENUNAMES list is of menu entries only. POPLOC Optional. If COLUMN and ROW are not specified, the POPLOC field name must be. The popup menu is displayed in this field. ROW Optional. If ROW is specified, so must COLUMN be. The top left hand corner of the menu is displayed here. COLUMN Optional. If COLUMN is specified, so must ROW be. The top left hand corner of the menu is displayed here. Returns 0 Normal completion 4 Nothing was selected 20 Severe Error Example A simple menu: list = 'Exit and save|Exit without saving' 'ISPEXEC POPUPMENU('list') MENUVAR(result) PAIRS(NO) ROW(5) COLUMN(10)' if rc = 4 then ... A simple menu in PAIRS: list = 'Exit and save|END|Exit without saving|CANCEL' 'ISPEXEC POPUPMENU('list') MENUVAR(result) PAIRS(YES) ROW(5) COLUMN(10)' if rc = 4 then ... A simple menu with a group and grayed out items: list = 'SAVE|EXIT|_|PRINT[ALL|PART|SELECTED]|_|-CheckOut|-CheckIn|+Add' 'ISPEXEC POPUPMENU('list') MENUVAR(result) PAIRS(NO) POPLOC(ZFNAME)' if rc = 4 then ... # 37.12 {PRNCLOSE} Purpose Use this command to close a print service opened via PRNOPEN. ISPEXEC Syntax ISPEXEC PRNCLOSE Returns 0 Normal completion 20 Severe Error Example To print two records defined as RECORD1 and RECORD2: RECORD1 = "This is record 1" RECORD2 = "This is record 2" 'ISPEXEC PRNOPEN Example Print' 'ISPEXEC PRNRECORD' record1 'ISPEXEC PRNRECORD' record2 'ISPEXEC PRNCLOSE' # 37.13 {PRNOPEN} Purpose Use this command to start a print process. ISPEXEC Syntax ISPEXEC PRNOPEN [ title ] Operands title Optional. Specifies the title printed on the header or footer of the print job. This only appears if Title has been set for the active printer in option 0.2. Returns 0 Normal completion 20 Severe Error Example To print two records defined as RECORD1 and RECORD2: RECORD1 = "This is record 1" RECORD2 = "This is record 2" 'ISPEXEC PRNOPEN Example Print' 'ISPEXEC PRNRECORD' record1 'ISPEXEC PRNRECORD' record2 'ISPEXEC PRNCLOSE' # 37.14 {PRNRECORD} Purpose Use this command to start a print process. ISPEXEC Syntax ISPEXEC PRNRECORD record Operands record Required. The string to be printed. It can be a null string. Returns 0 Normal completion 8 Print process not started 20 Severe Error Example To print two records defined as RECORD1 and RECORD2: RECORD1 = "This is record 1" RECORD2 = "This is record 2" 'ISPEXEC PRNOPEN Example Print' 'ISPEXEC PRNRECORD' record1 'ISPEXEC PRNRECORD' record2 'ISPEXEC PRNCLOSE' # 37.15 {REMPOP} Purpose Use this command to remove the current pop-up window. ISPEXEC Syntax ISPEXEC REMPOP Returns 0 Normal completion 12 No ADDPOP window present. 20 Severe error Example To display and then remove a window: 'ISPEXEC ADDPOP POPLOC(ZCMD) ROW(5) COL(5)' 'ISPEXEC DISPLAY TESTPAN' 'ISPEXEC REMPOP' # 37.16 {SELECT} Purpose Use this command to display a selection panel (menu), or invoke a function. To process non-menu panels, it is necessary to invoke a function which uses DISPLAY to put up the panel and then services it when [SPF-Enter] is pressed. ISPEXEC Syntax ISPEXEC SELECT PANEL(panel-ID) [ OPT(option) ] [ NEWAPPL(command-table) [ PASSLIB ] ] ISPEXEC SELECT CMD(REXX-proc-name) [ PARM(parms) ] [ NEWAPPL(command-table) [ PASSLIB ] ] ISPEXEC SELECT CTC(CTC-function-id) [ PARM(parms) ] [ NEWAPPL(command-table) [ PASSLIB ] ] ISPEXEC SELECT BACKPGM(program-name) [ PARM(parms) ] [ NEWAPPL(command-table) [ PASSLIB ] ] ISPEXEC SELECT PGM(program-name) [ PARM(parms) ] [ NEWAPPL(command-table) [ PASSLIB ] ] [ ASCII | EBCDIC ] Operands PANEL Optional. Specifies the panel-ID for the menu panel to be displayed. The function pool is unchanged. OPT Optional. Specifies the menu option to invoke. In this case the menu is not displayed, the option is invoked just as if it had been entered directly. CMD Optional. Specifies the name of a REXX procedure to be given control. The REXX procedure can display and service all types of panels. A new function pool is created. CTC Optional. Specifies the name of an internal CTC function to be given control. A new function pool is created. CTC functions can be used to perform tasks on your behalf, however they can not be altered as they are internal to SPF/Pro. BACKPGM Optional. Specifies the name of an external program which is to be given control. The program is launched and detached from SPF/Pro to run as a separate task. SPF/Pro is not suspended. A new function pool is created. BACKPGM() operates in the same fashion as PGM(), with the following exceptions: 'program-name' is executed in the "background", and SPF/Pro immediately returns to normal operation without waiting for the newly launched program to terminate. PGM Optional. Specifies the name of an external program which is to be given control. A new function pool is created. SPF/Pro is suspended until the program has completed. The following optional parameters apply to PANEL, CMD, CTC, PGM, and BACKPGM. NEWAPPL Optional. Specifies that a new command table is to be activated. The new command table has the name xxxxCMDS.TBF, where xxxx is a 1-4 character alphanumeric, DOS-legal string. Note that CMDS is attached to the character string by the parser. If xxxxCMDS.TBF is not found on the ZPRFPATH, the entire statement is ignored. PASSLIB Optional. Specifies that any existing user command table(s) currently in effect are to be assumed by the NEWAPPL. The search sequence becomes: table-name then PASSLIB Tables then SYSTEM Tables and finally the Intrinsic Tables. If PASSLIB is not specified, then only table-name is added to the search list the search sequence becomes: table-name then SYSTEM Tables and finally Intrinsic Tables The following optional parameters apply to CMD and CTC: PARM Optional. Specifies a parameter list for the procedure, function or program. You can specify a variable name preceded by an ampersand (&) or a literal string with or without quotes. Alternatively, parameters may be passed along with the procedure, function, or program name. For example: PGM(XYZPROG.EXE A B C) However, these two methods of passing parameters may not be mixed, as in: PGM(XYZPROG.EXE A B C) PARM(X Y Z) In this case, SPF/Pro would try to execute "XYZPROG.EXE A B C" with the parameters "X Y Z", presumably not the intended action. The following optional parameter applies only to PGM: Some programs that SPF/Pro executes require a DOS style, console window to appear, even if the program does not display console information. SPF/Pro tries to launch all programs as a native Windows program. However, if that fails, it then re-launches the program using the command interpreter in a TTY window. The FORCE KEY PRESS AFTER COMMAND EXECUTION switch on Panel 6 only applies to console applications. If you execute a Windows application that does not use a console window, SPF/Pro does not force a key after the command finishes executing. Returns For selection panels (menus): 0 Normal completion. END command entered. 4 Normal completion. RETURN command entered. 12 The panel specified could not be found. 16 TRUNC error storing ZCMD or ZSEL. 20 Severe error For functions: 0 Normal completion. 3 Command not found For programs: 0 Normal completion. -3 Program not found 'n' The value returned by the program's own return code. Example To display the first menu in a hierarchy of panels and/or functions: ISPEXEC SELECT PANEL(S2XXS000) To select an option without displaying the menu: ISPEXEC SELECT PANEL(S2XXS000) OPT(5) To invoke a REXX procedure (SAMPLE.ISP) which displays and services panels: ISPEXEC SELECT CMD(SAMPLE) To invoke an internal function which displays and services panels: ISPEXEC SELECT CTC(S2XXS015) To launch a program and wait for it to conclude: ISPEXEC SELECT PGM(PROGMAN.EXE) To launch a program and continue processing in SPF/Pro: ISPEXEC SELECT BACKPGM(G:\UTIL\REPORT.EXE) PARM(&TODAY) # 37.17 {SETMSG} Purpose Use this command to display a message on the next panel to be displayed. ISPEXEC Syntax ISPEXEC SETMSG MSG(message-ID) Operands MSG Required. Specifies the message-ID for the message to be displayed. Returns 0 Normal completion 12 The specified message was not found. 20 Severe error Example To display message SPFD102 on the next panel to be displayed: ISPEXEC SETMSG MSG(SPFD102) # 37.18 {TBADD} Purpose Use this command to add a row to a table. The new row is comprised of variables which were identified at table create time. For un-keyed tables, the new row is inserted at the current row pointer (CRP). Optionally for keyed or sorted tables, the new row is inserted at the proper sort position for the key or sort specification. If a duplicate key is detected, the row is not added and a return code is set. ISPEXEC Syntax ISPEXEC TBADD table-name [ SAVE(var-name-list) ] [ ORDER ] Operands table-name Required. Specifies the name of the table into which the new row is to be added. The table name is initially specified in TBCREATE. The row is added immediately after the current row pointer (CRP) unless ORDER is specified. SAVE Optional. Specifies a list of variable names which are not part of the original TBCREATE specification. The contents of these variables are appended to the row. Variables that are not part of the MODEL section are called extension variables. ORDER Optional. Specifies that the new row must be inserted in proper sort sequence according to the key specification of TBCREATE or the sort specification of TBSORT. This keyword is ignored if the table is non-keyed or non-sorted. If a duplicate key is detected, the row is not added. If the table was re-ordered via TBSORT, and a subsequent TBADD occurs without specifying ORDER, the TBSORT specification is cleared and the table is treated as un-ordered after that. To resume ordering, specify TBSORT again. Returns 0 Normal completion 8 The row to be added has a duplicate key. The new row is not added. The CRP is set to 0 (top of table). 12 The table is not open. 16 Numeric conversion error in sorted table. (See TBSORT) 20 Severe error Example To add a row to an un-ordered table: ISPEXEC TBADD MYTBL To add a row to an ordered table: ISPEXEC TBADD MYTBL ORDER To add a row with extension variables: ISPEXEC TBADD MYTBL SAVE(EV1 EV2 EV3) # 37.19 {TBBOTTOM} Purpose Use this command to position to the bottom row of a table. Optionally you can read the contents of the bottom row in the same call. You can also retrieve extension variables if desired. ISPEXEC Syntax ISPEXEC TBBOTTOM table-name [ SAVENAME(save-var-name) ] [ ROWID(row-var-name) ] [ NOREAD ] [ POSITION(pos-var-name) ] Operands table-name Required. Specifies the name of the table to be positioned. SAVENAME Optional. Specifies the name of a variable where the list of extension variable names (if any) is to be stored. The retrieved variable names are stored in a parenthesized list with blanks separating the var names (e.g. "(V1 V2 ...)"). ROWID Optional. Specifies the name of a variable into which the unique ID of the bottom row is to be stored. This id can be used later to position via TBSKIP. NOREAD Optional. Specifies that the variables corresponding to the bottom row are not to be retrieved. If not specified, the variables are retrieved. POSITION Optional. Specifies the name of a variable into which the current row pointer (CRP) after repositioning is to be stored. Returns 0 Normal completion 8 Table is empty. The CRP is set to 0 (top). 12 The table is not open. 20 Severe error Example To position to the bottom of table MYTBL and retrieve all variables: ISPEXEC TBBOTTOM MYTBL To position to the bottom of a table without retrieving variables: ISPEXEC TBBOTTOM MYTBL NOREAD To position to the bottom of a table and save the bottom row id in var BOTROWID: ISPEXEC TBBOTTOM MYTBL ROWID(BOTROWID) To position to the bottom of a table saving the current row position (CRP) after repositioning in var CROWPOS: ISPEXEC TBBOTTOM MYTBL POSITION(CROWPOS) To position to the bottom of a table retrieving the names of the extension vars that are part of the bottom row in var EXVARLST: ISPEXEC TBBOTTOM MYTBL SAVENAME(EXVARLST) # 37.20 {TBCLOSE} Purpose Use this command to close a table when it is no longer needed in memory. If the table was opened in write mode, it is written to disk upon close. ISPEXEC Syntax ISPEXEC TBCLOSE table-name [ NAME(alternate-name) ] Operands table-name Required. Specifies the name of the table to be closed. NAME Optional. Specifies an alternate name under which the table is to be stored. The original table file on disk, is unchanged. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To close table MYTBL: ISPEXEC TBCLOSE MYTBL To close table MYTBL creating a new disk based copy named MYTBL2: ISPEXEC TBCLOSE MYTBL NAME(MYTBL2) # 37.21 {TBCREATE} Purpose Use this command to create a new table. The table may reside in memory only or in memory and on disk. ISPEXEC Syntax ISPEXEC TBCREATE table-name [ KEYS(key-name-list) ] [ NAMES(field-name-list) ] [ NOWRITE ] [ REPLACE ] [ SHARE ] Operands table-name Required. Specifies the name of the table. The name can be one to eight alphanumeric characters in length. KEYS Optional. Specifies the names of key variables. NAMES Optional. Specifies the names of non-key variables. If no names are specified, the table can only have extension variables which must be specified at TBADD time. NOWRITE Optional. Specifies that the table is to reside in memory only, no disk copy is written when TBCLOSE is called. If NOWRITE is not specified, the table is assumed to be in WRITE mode, a disk based copy of the table is written at TBCLOSE time. REPLACE Optional. If a disk based table of the same name exists, it is replaced when the new table is written to disk (unless the new table is NOWRITE). SHARE Optional. Specifies that the table be made concurrently accessible to all SPF/Pro sessions. Returns 0 Normal completion 4 Normal completion. A duplicate table was found; REPLACE was specified; it is replaced. 8 A duplicate table was found; REPLACE was not specified; new table can not be created. 12 Unable to open, table already in use. 20 Severe error Example To create a table named PHONEBK with rows comprised of vars NAME, ADDR, and PHONE: ISPEXEC TBCREATE PHONEBK NAMES(NAME ADDR PHONE) To create PHONEBK with key var NAME, and non-key vars ADDR, and PHONE: ISPEXEC TBCREATE PHONEBK KEYS(NAME) NAMES(ADDR PHONE) To create PHONEBK replacing a pre-existing copy. ISPEXEC TBCREATE PHONEBK ... REPLACE To create PHONEBK so that it can be shared with all SPF/Pro sessions: ISPEXEC TBCREATE PHONEBK ... SHARE # 37.22 {TBDELETE} Purpose Use this command to delete a row from the table. If the table is non-keyed, the current row pointer (CRP) is used to determine which row is deleted. If the table is keyed, the value of the key vars determines the row to be deleted. For example, if the key var was NAME, and the value in NAME was "SMITH", the row matching "SMITH" would be deleted. After the row is deleted (keyed or non-keyed), the CRP is set to the row preceding the deleted row. ISPEXEC Syntax ISPEXEC TBDELETE table-name Operands table-name Required. Specifies the name of the table from which the row is to be deleted. Returns 0 Normal completion 8 A key was specified but no match was found. No row is deleted. The CRP is set to 0 (top). 12 The table is not open. 20 Severe error Example To delete a row from table MYTBL: ISPEXEC TBDELETE MYTBL # 37.23 {TBDIRCREATE} Purpose TBDIRCREATE creates an empty table services table with the following columns of information: Key: NAMEFULL Columns: DIR NAMESHRT NAMEBASE NAMEFULL NAMEPATH NAMEEXT CSIZE DATE CDATE TIME CTIME CATTRIB ISPEXEC Syntax ISPEXEC TBDIRCREATE table-name [ TITLE(title) ] [ NOWRITE ] [ REPLACE ] Operands table-name Required. Specifies the name of the table. The name can be one to eight alphanumeric characters in length. TITLE Optional. Specifies the title of the list which will appear when the table is displayed using TBDIRDISPL. NOWRITE Optional. Specifies that the table is to reside in memory only, no disk copy is written when TBCLOSE is called. If NOWRITE is not specified, the table is assumed to be in WRITE mode, a disk based copy of the table is written at TBCLOSE time. REPLACE Optional. If a disk based table of the same name exists, it is replaced when the new table is written to disk (unless the new table is NOWRITE). Returns 0 Normal completion 12 The table is already open. 20 Severe error Example To create a table of the files on the root directory: ISPEXEC TBDIRCREATE TITLE(File List of Root) # 37.24 {TBDIRDISPL} Purpose Operates similar to TBDISPL function, except that it chooses its own panel id to display the directory list based upon the contents of the directory table. If PANEL() is specified, then the enclosed panel id is forced, and the TBDIRDISPL panel selection logic is ignored. The selection field use by all of the SPF/Pro directory table panels is SEL. See information on TBDISPL in this bound documentation for more information on how to perform Table Display handling, including how to handle multiple selections. Use the above directory table services commands in addition to the existing standard table services commands. For example, once you perform a TBDIRCREATE, you are given a regular TB services table -- it is only special in that it has a predefined list of columns and keys. Normal TB Services commands like TBMOD, TBEXIST, TBDELETE, TBPUT, etc, may be used to manipulate the contents of the table. Remember, just like any TBServices table, be sure to TBEND or TBCLOSE the table when you are completed with it. Also, if you do not want the table to be written to disk, use the NOWRITE flag when you perform your initial TBDIRCREATE. ISPEXEC Syntax ISPEXEC TBDIRDISPL table-name [ PANEL(forcepanel) ] [ MSG(msgid) ] [ CURSOR(csrid) ] Operands table-name Required. Specifies the name of the table to be displayed which has been created by TBDIRCREATE and populated by TBDIRPOPULATE. PANEL Optional. Specifies the name of the panel containing the )MODEL statements for this table. If not specified, the default directory services panel is used. MSG Optional. Specifies the message-ID of a message to be displayed with the table. If not specified, no message is displayed. CURSOR Optional. Specifies the field name into which the cursor is to be placed when the table is displayed. If not specified, the cursor is placed in the first input field. Returns 0 Normal completion 4 More than one SEL field changed 20 Severe error Example To display a table of the files on the root directory: ISPEXEC TBDIRPOPULATE roottabl FILE(C:\*.*) ISPEXEC TBDIRDISPL roottabl # 37.25 {TBDIRPOPULATE} Purpose TBDIRPOPULATE adds rows to a table representing files that are found during a directory search. TBDIRPOPULATE may be called indefinitely on each table to further update the existing table contents. ISPEXEC Syntax ISPEXEC TBDIRPOPULATE table-name FILE(filespec) [ RECURSE(ON|OFF) ] [ SHOWMSG(ON|OFF) ] Operands table-name Required. Specifies the name of the table to be displayed which has been created by TBDIRCREATE. FILE Required. The file specification which is the argument to this option can be any valid file specification including wild cards. RECURSE If RECURSE(ON) is used, sub-directories are searched recursively downward from the specified directory. SHOWMSG If SHOWMSG(ON) is specified, directory names are displayed as short messages as each directory is populated. Returns 0 Normal completion 20 Severe error Example To display a table of the files on the root directory: ISPEXEC TBDIRPOPULATE roottabl FILE(C:\*.*) ISPEXEC TBDIRDISPL roottabl # 37.26 {TBDISPL} Purpose Use this command to display a table. You must call TBOPEN or TBCREATE before calling TBDISPL. Using TBSARG you can specify criteria which limits the rows displayed. The panel definition for a table normally contains a fixed portion and a scrollable portion. The fixed portion is defined by the )BODY section and is typically comprised of the title line, command field, scroll field, and column headers. The scrollable portion is defined by the )MODEL section. It may contain input fields, output fields, and text. When you enter data into input vars in the scrollable portion of the display, the vars are set in their respective variable pools and may be processed in the )PROC section when [SPF-Enter] is pressed. TBDISPL supports an automatic ZMARKED variable for determining whether a row has been highlighted via the mouse. TBDISPL returns with each highlighted row as well as each modified row. High lighted rows can be detected by checking the contents of the ZMARKED variable, with the results: * Y - the row was highlighted * N - the row was highlighted and subsequently unhighlighted * BLANK - no mouse selection was performed on the field As with all table display modifications, the ZMARKED values are not kept from one TBDISPL to the next. For example, TBDISPL is executed, and 3 rows are highlighted. The REXX calls TBDISPL 2 additional times after the initial display to retrieve and process the last highlighted lines. Finally, the routine calls TBDISPL an additional time to redisplay the table and the formally highlighted rows are unselected. To store the highlight status between displays and saves, add ZMARKED as a row in your table. During TBDISPL processing, if you wish to store the updated ZMARKED value for a particular row, perform a TBPUT to store the value back into the table permanently. ISPEXEC Syntax ISPEXEC TBDISPL table-name [ PANEL(panel-ID) ] [ MSG(message-ID) ] [ CURSOR(field-name) ] [ CSRROW(tbl-row-number) ] [ CSRPOS(cursor-pos) ] [ AUTOSEL( YES | NO ) ] [ POSITION(row-pos) ] [ ROWID(row-id) ] Operands table-name Required. Specifies the name of the table to be displayed. PANEL Optional. Specifies the name of the panel containing the )MODEL statements for this table. If not specified, the last panel displayed is used. MSG Optional. Specifies the message-ID of a message to be displayed with the table. If not specified, no message is displayed. CURSOR Optional. Specifies the field name into which the cursor is to be placed when the table is displayed. If not specified, the cursor is placed in the first input field. CSRROW Optional. Specifies the row number within the table where the table should be positioned (the CRP). If not specified, one is assumed. If AUTOSEL(YES) was specified, the row is also retrieved even if there was no explicit selection of the row. If control var .CSRROW is set in the panel definition, it is used in place of this parameter. CSRPOS Optional. Specifies the cursor position within the current field (see CURSOR). If not specified, one is assumed. AUTOSEL Optional. Specifies whether auto-selection is to be performed. If not specified, YES is assumed. YES If the CSRROW Parameter is specified, or the .CSRROW control var is set, the row is retrieved even if no explicit selection takes place. This is called auto-selection. NO Rows are not retrieved unless you make an explicit selection. POSITION Optional. Specifies the var name where the current row pointer (CRP) is to be stored. If not specified, the CRP is not stored. ROWID Optional. Specifies the var name where the unique row-ID for the current row is to be stored. If not specified, the row-ID is not stored. Returns 0 Normal completion. One of the following has occured: - One row was selected, the CRP points to it, the input vars are stored. - Data was entered in the fixed portion of the display, the input vars are stored. - No data was entered, only [SPF-Enter] was pressed. 4 Normal completion. Two or more rows were selected, the CRP points to the first row in the set, the input vars are stored. Var ZTDSELS contains the number of rows selected. Subsequent calls to TBDISPL without a panel ID advance the table to the next selected row until no more selected rows remain. On the last selected row, ZTDSELS has the value 1. 8 END or RETURN was entered. 12 One of the following occured: - The panel was not found. - The message was not found. - The table was not open. 20 Severe error Example To display table PHONEBK using panel PHBK001: ISPEXEC TBDISPL PHONEBK PANEL(PHBK001) Table applications are complex. There is not enough space here to give adequate coverage to the subject. For further understanding, please read the Sample Applications chapter. # 37.27 {TBEND} Purpose Use this command to close a table without writing to disk. You could think of this as a table cancel. ISPEXEC Syntax ISPEXEC TBEND table-name Operands table-name Required. Specifies the name of the table to end. If the table is shared, the use count is decremented by one. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To close table MYTBL without writing to disk: ISPEXEC TBEND MYTBL # 37.28 {TBERASE} Purpose Use this command to erase a table from the disk. ISPEXEC Syntax ISPEXEC TBERASE table-name Operands table-name Required. Specifies the name of the table to be erased. Returns 0 Normal completion 8 The table does not exist. 12 The table is in use. 20 Severe error Example To erase table MYTBL from the disk: ISPEXEC TBERASE MYTBL # 37.29 {TBEXIST} Purpose Use this command to determine if a particular keyed row exists in a table. The appropriate key variables must be set up prior to calling TBEXIST. ISPEXEC Syntax ISPEXEC TBEXIST table-name Operands table-name Required. Specifies the name of the table in which the search is to take place. Returns 0 Normal completion. The CRP is set to the row which matches the search criteria. 8 A row matching the criteria could not be found. The CRP is set to 0 (top). 12 The table is not open. 20 Severe error Example To search table PHONEBK for an entry with a NAME field matching "SMITH": NAME = 'SMITH' 'ISPEXEC TBEXIST PHONEBK' IF RC = 0 THEN ... row exists ... # 37.30 {TBGET} Purpose Use this command to fetch the contents of a table row. Dialog variables are set to the corresponding values in the table row. For keyed tables, a search is performed based on the setting of the key variables. The matching row, if present, is fetched. For non-keyed tables, the row pointed to by the CRP is fetched. In all cases, the CRP is set to the row that was fetched. ISPEXEC Syntax ISPEXEC TBGET table-name [ SAVENAME(save-name) ] [ ROWID(row-id) ] [ NOREAD ] [ POSITION(row-pos) ] Operands table-name Required. Specifies the name of the table from which the row is to be fetched. SAVENAME Optional. Specifies a var name into which a list of extension var names is to be stored. The extension var name list takes the form "(v1 v2 ...)". ROWID Optional. Specifies a var name into which the unique ID of the row being fetched is to be stored. NOREAD Optional. Specifies that row values are not to be loaded into corresponding dialog variables. POSITION Optional. Specifies a var name into which the row number of the row being fetched is to be stored. Returns 0 Normal completion 8 A row matching the criteria could not be found. The CRP is set to 0 (top). 12 The table is not open. 20 Severe error Example To retrieve the row with NAME field matching "SMITH" from table PHONEBK: NAME = 'SMITH' 'ISPEXEC TBGET PHONEBK' IF RC = 0 THEN ... row values are automatically loaded ... ... into corresponding dialog vars ... # 37.31 {TBMOD} Purpose Use this command to update a row in a keyed table. If the requested key is not found, TBMOD performs the same operation as TBADD. For non-keyed tables, TBMOD performs the same operation as TBADD. ISPEXEC Syntax ISPEXEC TBMOD table-name [ SAVE(var-name-list) ] [ ORDER ] Operands table-name Required. Specifies the name of the table to be updated. SAVE Optional. Specifies a list of variable names which are not part of the original TBCREATE specification which are to be appended to the row. These added variables are called extension variables. ORDER Optional. Specifies that after update, the table is to be sorted based on the most recent TBSORT specification. Returns 0 Normal completion. Matching key found, row updated. For non-keyed tables, row was added. 8 Matching key not found, new row was added. 12 Table was not open. 16 Sort numeric conversion error (see TBSORT). 20 Severe error Example To update the row containing key NAME with value "SMITH": NAME = 'SMITH' ... other row vars set to desired value ... 'ISPEXEC TBMOD PHONEBK' IF RC = 0 THEN ... row updated with new values ... # 37.32 {TBOPEN} Purpose Use this command to read a table from disk and make it accessible to other table services. ISPEXEC Syntax ISPEXEC TBOPEN table-name [ NOWRITE ] [ SHARE ] Operands table-name Required. Specifies the name of the disk based table to be opened. NOWRITE Optional. Specifies that the table is to be loaded but not written by TBSAVE or TBCLOSE. If not specified, the table is writable. SHARE Optional. Specifies that the table is to be accessible across sessions. In this case a use count is maintained. On the first TBOPEN the table is loaded into memory and the use count is set to one. For each subsequent TBOPEN the use count is increased by one. For each subsequent TBCLOSE the use count is decreased by one. When the use count goes to zero (the last TBCLOSE), the table is written. If not specified, the table is not sharable. After the first TBOPEN, subsequent TBOPENs by other sessions would fail with return code 12. Returns 0 Normal completion 8 The table does not exist. 12 The table is already in use and it was not opened with SHARE. 20 Severe error Example To open disk based table MYTBL to allow other table services to be performed: ISPEXEC TBOPEN MYTBL # 37.33 {TBPUT} Purpose Use this command to update a row in a non-keyed table. For non-keyed tables, the row pointed to by the current row pointer (CRP) is updated. Use TBSCAN, TBSKIP, TBTOP, or TBBOTTOM to set the CRP. For keyed tables, the keys in the table row at the CRP must match the corresponding dialog vars or the row is not updated. Use TBMOD to update keyed table rows. ISPEXEC Syntax ISPEXEC TBPUT table-name [ SAVE(var-name-list) ] [ ORDER ] Operands table-name Required. Specifies the name of the table to be updated. SAVE Optional. Specifies a list of variable names which are not part of the original TBCREATE specification which are to be appended to the row. These added variables are called extension variables. ORDER Optional. Specifies that the rows should be maintained in the order specified by TBSORT. Returns 0 Normal completion 8 For keyed tables, no matching key found, CRP set to 0 (top), record not updated. 12 The table is not open. 20 Severe error Example To update a specific record in non-keyed table MYTBL: 'ISPEXEC TBSCAN MYTBL ...' (position to desired record) ... set function vars for row update ... 'ISPEXEC TBPUT MYTBL' (update row pointed to by CRP) # 37.34 {TBQUERY} Purpose Use this command to obtain information about a table. ISPEXEC Syntax ISPEXEC TBQUERY table-name [ KEYS(key-names) ] [ NAMES(field-names) ] [ ROWNUM(row-num) ] [ KEYNUM(key-num) ] [ NAMENUM(name-num) ] [ POSITION(row-pos) ] Operands table-name Required. Specifies the name of the table about which you want information. KEYS Optional. Specifies a variable name to receive the names of the key fields in the form "(key1 key2 ...)". NAMES Optional. Specifies a variable name to receive the names of the non-key fields in the form "(name1 name2 ...)". ROWNUM Optional. Specifies a variable name to receive the number of rows in the table. KEYNUM Optional. Specifies a variable name to receive the number of key fields. NAMENUM Optional. Specifies a variable name to receive the number of non-key fields. POSITION Optional. Specifies a variable name to receive current row pointer (CRP). Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To fetch the number of rows in table MYTBL into var ROWS: ISPEXEC TBQUERY MYTBL ROWNUM(ROWS) # 37.35 {TBSARG} Purpose Use this command to set up a filter for positioning to, or display of, a particular row or rows within a table. After setting up a filter with TBSARG, you must call either TBSCAN to position the table, or TBDISPL to display the table. ISPEXEC Syntax ISPEXEC TBSARG table-name [ ARGLIST(var-name-list) ] [ PREVIOUS ] [ NAMECOND(name-condition-pairs) ] Operands table-name Required. The table for which the search criteria is being specified. ARGLIST Optional. Specifies names of extension variables to be included in the search criteria in the form "ARGLIST(name1 name2 ...)" PREVIOUS Optional. Specifies that the search is to proceed from the current record minus one toward the top of the table. If not specified, the search proceeds from the current record plus one toward the bottom of the table. NAMECOND Optional. Pairs consisting of a field name followed by a condition for comparison to the field value. For example, to specify that field NAME be compared for equality to the value in dialog variable NAME you would specify: NAMECOND(NAME,EQ) Multiple pairs may be specified separated by commas. The following conditional operators are available: EQ Evaluates TRUE if named field is equal to var, otherwise evaluates FALSE. NE Evaluates TRUE if named field is not equal to var, otherwise evaluates FALSE. LT Evaluates TRUE if named field is less than var, otherwise evaluates FALSE. GT Evaluates TRUE if named field is greater than var, otherwise evaluates FALSE. LE Evaluates TRUE if named field is less than or equal to var, otherwise evaluates FALSE. GE Evaluates TRUE if named field is greater than or equal to var, otherwise evaluates FALSE. Returns 0 Normal completion 8 Insufficient arguments to construct search criteria. 12 The table is not open. 20 Severe error Example To set up search criteria to compare the NAME field of table PHONEBK for equality to name "SMITH": NAME = 'SMITH' ISPEXEC TBSARG PHONEBK NAMECOND(NAME,EQ) After the TBSARG call, you can either call TBSCAN to position the table, or TBDISPL to display only those rows which match the search criteria. # 37.36 {TBSAVE} Purpose Use this command to write a disk-based table without closing it. ISPEXEC Syntax ISPEXEC TBSAVE table-name [ NAME(alternate-table-name) ] Operands table-name Required. Specifies the name of the table to be written. If the table already exists on disk, it is replaced with the current copy. NAME Optional. Specifies an alternate name to be used for writing the table. The original table is unchanged. If the alternate table already exists on disk, it is replaced with the current copy. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To write table MYTBL to disk: ISPEXEC TBSAVE MYTBL To write table MYTBL to disk under alternate name MYTBL2: ISPEXEC TBSAVE MYTBL NAME(MYTBL2) # 37.37 {TBSCAN} Purpose Use this command to position the table to a row which matches specific search criteria. After positioning, current row values are loaded into corresponding variables. For any parameters not specified, the most recent TBSARG specification is used. ISPEXEC Syntax ISPEXEC TBSCAN table-name [ ARGLIST(arg-name-list) ] [ SAVENAME(var-name) ] [ ROWID(row-id) ] [ PREVIOUS ] [ NOREAD ] [ POSITION(row-pos) ] [ CONDLIST(condition-list) ] Operands table-name Required. Specifies the name of the table to be searched. ARGLIST Optional. Specifies the names of fields to be examined for conformance with the specified criteria. The list takes the form "(name1 name2 ...)". SAVENAME Optional. Specifies the var name to receive a list of extension var names. ROWID Optional. Specifies the var name to receive the unique row id of the matching row. PREVIOUS Optional. Specifies that the search is to proceed from the current record minus one toward the top of the table. If not specified, the search proceeds from the current record plus one toward the bottom of the table. NOREAD Optional. Specifies that when the matching row is found, the row values are not to be stored into corresponding variables. If not specified, the row values are stored. POSITION Optional. Specifies the var name to receive the row number of the matching row. CONDLIST Optional. Specifies the conditions to be evaluated for each of the fields specified in ARGLIST. For example, ARGLIST(LASTNAME,ZIP) CONDLIST(EQ,EQ) The example specifies that fields LASTNAME and ZIP are to be searched for equality to values in their corresponding dialog variables. If the number of fields in ARGLIST does not conform to the number of conditions in CONDLIST, TBSCAN returns with return code 20. The following conditional operators are available: EQ Evaluates TRUE if named field is equal to var, otherwise evaluates FALSE. NE Evaluates TRUE if named field is not equal to var, otherwise evaluates FALSE. LT Evaluates TRUE if named field is less than var, otherwise evaluates FALSE. GT Evaluates TRUE if named field is greater than var, otherwise evaluates FALSE. LE Evaluates TRUE if named field is less than or equal to var, otherwise evaluates FALSE. GE Evaluates TRUE if named field is greater than or equal to var, otherwise evaluates FALSE. Returns 0 Normal completion 8 A row matching the search criteria could not be found. 12 The table is not open. 20 Severe error Example To scan table PHONEBK for a row with NAME field matching value "SMITH": NAME = 'SMITH' ISPEXEC TBSCAN PHONEBK ARGLIST(NAME) CONDLIST(EQ) # 37.38 {TBSKIP} Purpose Use this command to move the current row pointer forward or backward a number of rows. After positioning, the row values are stored in corresponding variables. ISPEXEC Syntax ISPEXEC TBSKIP table-name [ NUMBER(number) ] [ SAVENAME(var-name) ] [ ROWID(var-name) ] [ ROW(number) ] [ NOREAD ] [ POSITION(row-pos) ] Operands table-name Required. Specifies the name of the table which is to be positioned. NUMBER Optional. Specifies the number of rows to move. A positive number moves forward (toward the bottom). A negative number moves backward (toward the top). If zero is specified, no positioning is done and the current record is retrieved. If NUMBER and ROW are not specified, the table is positioned one row beyond the current row pointer. SAVENAME Optional. Specifies the name of a variable where the list of extension variable names (if any) is to be stored. The retrieved variable names are stored in a parenthesized list with blanks separating the var names (e.g. "(V1 V2 ...)"). ROWID Optional. Specifies the name of a variable into which the accessed row id is to be stored. ROW Optional. Specifies the unique ID for the desired row. The row id is obtained via TBBOTTOM, TBDISPL, TBGET, or TBSCAN. If NUMBER and ROW are not specified, the table is positioned one row beyond the current row pointer. If both NUMBER and ROW are specified, the table is positioned to ROW and then the number of rows specified in NUMBER is skipped. NOREAD Optional. Specifies that the variables corresponding to the accessed row are not to be retrieved. If not specified, the variables are retrieved. POSITION Optional. Specifies the var name where the accessed row pointer is to be stored. Returns 0 Normal completion 8 The number specified would go beyond the end (or beginning) of the table. 12 The table is not open. 20 Severe error Example To skip forward one row in table MYTBL: ISPEXEC TBSKIP MYTBL To skip forward five rows in table MYTBL: ISPEXEC TBSKIP MYTBL NUMBER(5) To skip forward in table MYTBL to the row id held in var CURROWID: 'ISPEXEC TBSKIP MYTBL ROW(' CURROWID ')' # 37.39 {TBSORT} Purpose Use this command to sort a table. The sort specification is remembered uniquely for each table so that when rows are subsequently updated, inserted, or added, the table is kept in proper order. ISPEXEC Syntax ISPEXEC TBSORT table-name FIELDS(field-sort-list) Operands table-name Required. Specifies the name of the table to be sorted. FIELDS Required. Specifies the fields to be sorted. Multiple field specifications may be entered with intervening blanks. Fields to be sorted are specified in the following form: field-name,field-type,sort-direction field-name Specifies the name of the field. This can be a KEY field or a NAME field. field-type The field can be one of: C - character, consider case, or I - character, ignore case, or N - number If not specified, "C" is assumed. sort-direction Specifies the sort direction, one of: A - ascending, or D - descending If not specified, "A" is assumed. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To sort table ADDRBOOK based on the NAME and ZIP fields: ISPEXEC TBSORT ADDRBOOK FIELDS(NAME,C,A,ZIP,N,A) # 37.40 {TBSTATS} Purpose Use this command to get statistical data about a table. ISPEXEC Syntax ISPEXEC TBSTATS table-name [ UDATE(use-date) ] [ UTIME(use-time) ] [ ROWCURR(curr-row) ] Operands table-name Required. Specifies the name of the table about which statistics are requested. UDATE Optional. Specifies a var name into which the date when the table was last updated (written) is to be stored. UTIME Optional. Specifies a var name into which the time of day when the table was last updated (written) is to be stored. ROWCURR Optional. Specifies a var name into which the total number of rows in the table is to be stored. Returns 0 Normal completion 20 Severe error Example To get statistics for table MYTBL: ISPEXEC TBSTATS MYTBL UDATE(LASTDATE) UTIME(LASTTIME) # 37.41 {TBTOP} Purpose Use this command to set the current row pointer (CRP) to the top of the table (before the first row). This corresponds to a CRP value of 0. ISPEXEC Syntax ISPEXEC TBTOP table-name Operands table-name Required. Specifies the name of the table to be positioned to the top. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To position table MYTBL to the top: ISPEXEC TBTOP MYTBL # 37.42 {TBVCLEAR} Purpose Use this command to clear the variables in the current row. All their values are set to null. ISPEXEC Syntax ISPEXEC TBVCLEAR table-name Operands table-name Required. Specifies the name of the table whose current row is to be cleared. Returns 0 Normal completion 12 The table is not open. 20 Severe error Example To clear the top row of MYTBL: ISPEXEC TBTOP MYTBL ISPEXEC TBVCLEAR MYTBL # 37.43 {VGET} Purpose Use this command to copy a var from the shared, global, or profile pool to the function pool. ISPEXEC Syntax ISPEXEC VGET (var-name-list) [ ASIS | SHARED | GLOBAL | PROFILE ] Operands var-name-list Required. Specifies one or more var names to be copied from their respective variable pools into the function pool. If a single variable name is specified, no parentheses are required. If multiple variable names are specified, they must be enclosed in parentheses and separated by commas. ASIS Optional. Copy first from the shared pool, if not there, copy from the global pool, if not there, copy from the profile pool. SHARED Optional. Copy exclusively from the shared pool. GLOBAL Optional. Copy exclusively from the global pool. PROFILE Optional. Copy exclusively from the profile pool. If no pool is specified, ASIS is assumed. Returns 0 Normal completion 8 Variable not found 20 Severe error Example To retrieve a PF key definition from the profile pool: ISPEXEC VGET ZPF01 PROFILE Function var "ZPF01" now contains the PF key definition for F1. To retrieve multiple PF key definitions: ISPEXEC VGET (ZPF01,ZPF02,ZPF03) PROFILE Function vars "ZPF01,ZPF02,ZPF03" now contain the PF key definitions for F1, F2, and F3. # 37.44 {VPUT} Purpose Use this command to copy a function variable into the shared, global, or profile pool. ISPEXEC Syntax ISPEXEC VPUT (var-name-list) [ ASIS | SHARED | GLOBAL | PROFILE ] Operands var-name-list Required. Specifies one or more var names to be copied from the function pool to the shared, global, or profile pool. If a single variable name is specified, no parentheses are required. If multiple variable names are specified, they must be enclosed in parentheses and separated by commas. ASIS Optional. The function variable is copied in one of the following ways: - if var exists in shared pool, the function variable is copied to there, otherwise - if var exists in global pool, the function variable is copied to there, otherwise - if var exists in profile pool, the function variable is copied to there, otherwise - the function variable is copied to the shared pool SHARED Optional. Copy exclusively to the shared pool. GLOBAL Optional. Copy exclusively to the global pool. PROFILE Optional. Copy exclusively to the profile pool. If no pool is specified, ASIS is assumed. Returns 0 Normal completion 20 Severe error Example To set a new PF key definition in the profile pool: ZPF01 = '... new definition ...' ISPEXEC VPUT ZPF01 PROFILE PF key definition for F1 now contains text "... new definition ..."