# 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 ..."
|
|