HP 3000 Manuals HP 3000 Manuals
Using the New Switch Assist Tool
by Alex Trujillo
Commercial Systems Division
The second release of the Switch Assist Tool (SWAT), version A.01.00, has
a number of improvements over the original release of SWAT (version
A.00.00). These enhancements include:
* SWAT script functionality
* Privilege level of target routine no longer necessary
* Ability to overwrite existing files
* New function keys added
* SWAT version and stub generation time added
The most significant functionality added to SWAT is the ability to
recognize and use a script, which is a small set of keywords that
characterize a switch stub. The enhancements listed above will be
described in detail with the major emphasis on the new SWAT script
functionality.
SWAT SCRIPT FUNCTIONALITY
There are two components to the SWAT script functionality:
* The Script Session
* The SWAT Script
The relationship between these two components is simple: a script
session uses the SWAT script as input to the SWAT program. Together the
SWAT session and script provide you with the following:
* A method of characterizing a switch stub inside a source file
* An alternative way of creating/modifying switch stub source files
The following information describes both the SWAT script session and the
SWAT script in detail as well as the following:
* Insertion of the SWAT script into a file
* How to create a SWAT script
* How to use the new FILE screen associated with the SWAT script
functionality
* How SWAT helps you resolve errors that occur during a script session
Script Session
Prior to this release of SWAT, you had only one way of specifying switch
stub information, i.e., interactively on each and every VPLUS screen.
This version of SWAT provides a second alternative to creating a switch
stub: a SWAT script session.
A script session is the process of reading a file containing a SWAT
script, which is a small set of keywords characterizing a switch stub,
and loading the appropriate VPLUS screens for modification and switch
stub generation. During this session, no VPLUS screens will be displayed
and the script session ends one of two ways: 1) At the COMMIT screen
with or without error messages or 2) at the FILE screen with syntax
errors. SWAT will help you resolve errors whenever possible.
SWAT Script
The SWAT script is a small set of keywords that describe a switch stub.
It has information about the filename that will hold the switch stub
source code, the target CM procedure, and the target CM procedure's
parameters. It also contains information that starts and stops the
script session. This version of SWAT (A.01.00) will be able to identify
the following script format:
![[]](../../pic3k/M000120/GENERAL3c50.gif)
Figure 7-1. General SWAT Script Format
There are five parts to the SWAT script format, each with its own
purpose. The first part of the SWAT script is the script open
specification. It tells SWAT that a SWAT script may exist and that
parsing may start. It is important to specify this part exactly as SWAT
expects to find it, otherwise, the script will not be found.
The second part of the SWAT script is the file specification. This
allows you to specify the MPE file where the generated switch stub source
will reside. SWAT expects a valid MPE filename.
Next comes the procedure specification. The procedure specification
allows you to name the target Compatibility Mode procedure, what type of
value this target procedure returns, the SL location of the target
procedure, and whether or not the target procedure sets a condition code.
The comma (,) is used as a separating character between fields.
The fourth part of the SWAT script is the parameter specification. This
section of the script is used to describe each of the target procedure's
parameters. Up to thirty-two parameters (32) can be recognized. Each
parameter must have an associated data type, an addressing method, an I/O
type, and must be identified as an array or nonarray type. If the
parameter is an array, then the array length and the usage of this length
will be required. The separator between parameter fields is the comma
(,) while the separator between parameters is the semicolon (;). The
parameter specification is not required for target procedures with no
parameters. Open and close parenthesis are used to begin and end the
parameter specification.
The final part of the format is the script close specification. The
semicolon (;) character notifies SWAT that the end of the script has been
reached. Parsing ends when this character is encountered. SWAT proceeds
to the COMMIT screen when parsing is finished.
Together, these five parts comprise a SWAT script that can be read and
interpreted by the SWAT program.
Insertion of the SWAT Script Into a File
There are two ways a SWAT script gets created: 1) By SWAT during the
code generation process or 2) by creating a SWAT script in an ASCII file
using an editor.
Insertion During Code Generation. During the source generation process,
SWAT will automatically place a SWAT script in two locations (near the
top and bottom) of the designated target file. A sample script generated
by SWAT is shown below:
{ Swat Script *****************************************}
{* FILE TESTFILE *}
{* TESTPROCEDURE NONE, GROUP, NOCCODE *}
{* (PARM1 BYTE, REFERENCE, INOUT, ARRAY, 3000, BYTES; *}
{* PARM2 INTEGER, REFERENCE, INOUT, ARRAY, PARM3, *}
{* NEGRULE; *}
{* PARM3 INTEGER, VALUE, INPUT, NOTARRAY); *}
{******************************************************}
The SWAT script shown above is embedded in Pascal comments for
compilation purposes. If the script was not commented out, then the
final switch stub source file would not compile due to syntax errors. As
you can see, SWAT keeps all relevant information about the switch stub
using the appropriate keywords. What is the benefit from keeping this
information in your file? First of all, you will actually have a record
of your interactive SWAT session for later reference. Secondly, and more
importantly, you will be able to recreate your interactive SWAT session,
make modifications to the switch stub via SWAT's screens, and then
regenerate another switch stub in a short period of time. The actual
keywords that characterize the switch stub are discussed in the section
entitled "Creating a SWAT Script."
Insertion Using an Editor. If you do not want to use SWAT to create a
script, then you can use your favorite editor and create your own script.
After opening an ASCII file, you can simply follow the general script
format discussed earlier along with the information provided in the next
section to build a script that SWAT can recognize and use in a script
session. The section titled "Creating a SWAT Script" tells you how to
write a SWAT script. Please refer to the SWAT script format diagram for
proper placement of commas, semicolons, and parenthesis.
Creating a SWAT Script
The SWAT script format discussed in the "SWAT Script" section must be
used in order to create a SWAT script. The general format of a SWAT
script is:
* The Script Open Specification
* The Target File Specification
* The Target Procedure Specification
* The Target Procedure's Parameter Specifications
* The Script Close Specification
These five items must be present in order for the script to be used by
SWAT. Please refer to the "SWAT Script" section for details on the
format. The following section will discuss the keyword options for each
specification. A SWAT script format diagram is provided at the end of
this section showing the script format along with the keyword options for
each specification.
The Script Open Specification
The identifying comment lets SWAT know that the currently opened file may
have a SWAT script. The comment is shown below and must appear exactly
the same way in the SWAT script:
{ Swat Script *****************************************}
The comment consists of an open brace, followed by a space, followed by
"Swat Script", followed by a space, followed by forty-one asterisks (*),
and finally ends with a close brace. Once this Pascal comment is found,
then the SWAT script parsing will start. If this comment is not found,
then SWAT will return the following error message:
File exists, but does not contain a SWAT script
The Target File Specification
The target file specification exists so that you may specify a filename
to hold the SWAT switch stub. The file specification will consist of a
keyword followed by a valid MPE filename:
FILE filename
The script keyword, FILE, or any other keyword, cannot be used as user
supplied information. The filename you specify will be the actual MPE
file which will hold the switch stub at code generation time. The errors
you may encounter are:
Expected the FILE keyword
Expected a valid filename
The filename cannot be longer than 8 characters in length
For more detailed information about a valid MPE filename, refer to the
"MAIN Menu Screen" section of the Switch Programming Guide (P/N
32650-60030).
The Target Procedure Specification
The four items required for target procedure specification are:
* The name of the target procedure
* The functional return type of the procedure
* The SL location of the target procedure
* Whether or not the procedure sets a condition code
For detailed information on these parameters, refer to the "PROCINFO Menu
Screen" section of the Switch Programming Guide.
Specifying the Target Procedure Name. The target procedure name must be
specified and can have a maximum of sixteen characters. SWAT will check
the procedure name for validity, but does not check for the use of HP
Pascal XL reserved words and predefined routines as names. If SWAT
detects a long or invalid procedure name then you will see the following
error messages:
A procedure/function name cannot be longer than 16 characters
Expected a valid procedure name
Refer to the "PROCINFO Menu Screen" of the Switch Programming Guide for
determining what constitutes a valid procedure name.
Specifying the Functional Return Type. The type of value that the
procedure will return must be specified. The user has the following
options when specifying the functional return type:
NONE BYTE INTEGER LOGICAL DOUBLE REAL LONG
A SWAT script session would expect to find one of these keywords right
after the target procedure name has been found. If this keyword is
missing or invalid, then SWAT will report the following error message:
Expected a valid functional return data type
Specifying the Segmented Library Location. The keywords which specify
the target procedure's SL are:
GROUP PUB SYS
If the keyword is invalid, SWAT will report the following error message:
Expected a valid SL library specification
Specifying Whether the Target Procedure Sets A Condition Code. The
target procedure may or may not have a condition code associated with it.
One of the following two keywords is expected after specifying the SL
location:
CCODE NOCCODE
If the condition code is invalid, SWAT will report the following error
message:
Expected a valid condition code return option
The Target Procedure's Parameter Specifications
The items required for the parameter specification are:
* The Name of the Parameter
* The Parameter's Data Type
* The Addressing Method
* The Parameter's I/O type
* An Array Specification
* The Array Length (only if parameter is an array)
* The Array Length Usage (only if parameter is an array)
For more detailed information on these fields, please refer to the
"PARMINFO Menu Screen" section of the Switch Programming Guide
Specifying the Parameter's Name. The parameter name must be specified
and can be up to 32 characters in length. The procedure name should not
be a script keyword or a Pascal reserved keyword. Valid parameter names
are discussed in the Switch Programming Guide.
Specifying the Parameter's Data Type. The next piece of information SWAT
expects to find is the parameter's data type. The following data types
will be recognized by the SWAT script parser:
BYTE INTEGER LOGICAL DOUBLE REAL LONG
The following error message will be displayed if SWAT cannot find a valid
data type:
Expected a valid data type
Specifying the Parameter's Addressing Method. The addressing method
describes how the parameter is going to be accessed. One of the
following addressing methods will be recognized by the SWAT script
parser:
REFERENCE VALUE
The following error message will be displayed if an invalid parameter
addressing method is specified:
Expected a valid addressing method specification
Specifying the Parameter's I/O Type. The I/O type describes how
parameters are being sent into the target procedure. There are three
choices that will be recognized by the SWAT script parser:
INPUT OUTPUT INOUT
INOUT is shortened for the INPUT/OUTPUT I/O type. The following error
message will be displayed if an invalid I/O type is specified:
Expected a valid I/O direction specification
Specifying Whether the Parameter is an Array. The following keywords
specify whether or not the parameter is an array:
ARRAY NOTARRAY
If the parameter is an array, then the array length and the array length
usage must be specified, otherwise the parameter can be considered fully
described. The following error message is displayed if SWAT is given an
invalid array specification:
Expected a valid array or not array specification
Specifying the Length Value of an Array Parameter. If the ARRAY option
is chosen, then this field will be expected to follow immediately. This
is the length of the array and can be a positive integer or another
parameter name. See the "ARRAYLEN Menu Screen" section of Switch
Programming Guide for the limitations when specifying this script field.
Specifying the Interpretation of the Array Length Usage Value. If the
array option was chosen, then this field will be expected directly after
the specification of the array length. The three array length usage
keywords are:
ELEMENTS BYTES NEGRULE
NEGRULE is short for the Negative=Bytes/Positive=Words rule. If this
field is specified incorrectly then the following error message will be
displayed:
Expected a valid array usage specification
For more information on array lengths see the "ARRAYLEN Menu Screen" of
the Switch Programming Guide (P/N 32650-60030). Once this script field
has been defined, the user can now close the parameter by appending a
semicolon (;) after it. If it is the final parameter, then the user can
finalize the parameter specification by appending a close parenthesis.
This signals the end of the parameter specification.
Separating Parameters. After each parameter is finished being defined, a
semicolon (;) must be placed between the array specification of the last
parameter and the beginning of the next parameter. When the last
parameter has been defined, you must end the parameter specification
using a close parenthesis ')' (no semicolon) after the array
specification.
The Script Close Specification
Once the final script has been read, SWAT will expect to find a semicolon
(;). In this case, the semicolon acts as a terminator and tells SWAT
that the end of the script has been reached and parsing can stop. By the
time SWAT reaches this point, all information about the switch stub has
been loaded into the appropriate VPLUS fields and ready for modification
or switch stub generation.
All the keywords and syntax have now been discussed. Figure 7-2
illustrates the SWAT script format with all the available keyword options
for each of the script fields.
![[]](../../pic3k/M000120/DETAILED3c50.gif)
Figure 7-2. SWAT Script Format With Keyword Options
Using the SWAT Script
The new FILE screen illustrated in Figure 7-3 was added specifically for
the new SWAT script functionality. It is the first screen which appears
when the SWAT program is run and prompts you for a filename. If the file
specified exists, then SWAT will search for the script open specification
and, if found, start a script session. If the file does not contain a
script then SWAT will print the following error message at the bottom of
the screen:
File exists, but does not contain a SWAT script
If the file you specify does not exist, i.e., a new file, then SWAT
assumes you want an interactive session and you are sent to the MAIN
screen where you can start creating your switch stub.
The FILE screen provides you with the following function keys: 1) a GOTO
MAIN key F1, 2) ENTER MODE key F3, 3) REFRESH SCREEN key F4, 4) NEXT key
F6, 5) HELP key F7, and 6) an EXIT key F8. This screen also has a window
for reporting syntax errors which occur during a script session.
__________________________________________________________________________________________
| |
| HP30363 Switch Assist Tool FILE |
| COPYRIGHT (C) HEWLETT-PACKARD 1986. ALL RIGHTS RESERVED. |
| |
| |
| |
| [ ] FILENAME |
| |
| |
| |
| SCRIPT PROCESSING ERRORS |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| GOTO ENTER REFRESH NEXT HELP EXIT |
| MAIN MODE SCREEN |
__________________________________________________________________________________________
Figure 7-3. New FILE Screen For SWAT Script Session
NOTE You should always specify the filename at the FILE screen and not
the MAIN screen. Only the FILE screen will check the file for a
SWAT script. However, the MAIN screen does not check the file for
a SWAT script and will allow you to overwrite it. Hence you may
end up overwriting a file that is not intended to be a switch stub
source file.
Error Resolution in SWAT
SWAT tries to help you as much as possible with error resolution. If
there are any syntax errors with your script, then SWAT will display them
on the FILE screen. Other errors will be displayed on the COMMIT screen
after all the parameters have been read correctly. Figure 7-4
illustrates a SWAT syntax error generated from a script with an illegal
I/O type (the keyword INOUT was expected):
_______________________________________________________________
| |
| SCRIPT PROCESSING ERRORS |
| |
| {* TESTPROCEDURE INTEGER, GROUP, NOCCODE *}|
| {* (PARM1 BYTE, REFERENCE, INPUTOUT, NOTARRAY; *}|
| ^^^^^^^^ |
| Expected a valid I/O direction specification |
| |
_______________________________________________________________
Figure 7-4. SWAT Script Error Display
The error display is located on the FILE screen. When SWAT detects an
error in the script, it will print the last two lines it parsed and
carets ('^') under the offending portion of the script. After
discovering an error, you may edit the switch stub source file and make
corrective modifications. A quick reference of the SWAT script keywords
can be found on the first help page of the FILE screen.
Once syntax errors have been resolved, SWAT will be able to interpret the
script and load all the corresponding VPLUS fields. Any remaining errors
will be displayed on the COMMIT screen and can be corrected within SWAT
so that a new switch stub source file can be generated.
PRIVILEGE LEVEL OF TARGET ROUTINE NO LONGER NECESSARY
Because of enhancements made to the switch subsystem, specifying the
privilege level of a switch stub is no longer necessary. The privilege
level of a switch stub will be determined by the switch subsystem after
the call to HPSWITCHTOCM is made. Hence there is no need for SWAT to try
and match the privilege level of the stub with the privilege level of the
target procedure so there won't be any need to emit the following Pascal
compiler options when privileged level procedures are called:
$EXEC_PRIVILEGE 1$
$CALL_PRIVILEGE 1$
Note that a nonprivileged procedure has always been able to call a
privileged target procedure, however, it has never been able to call an
uncallable privileged target procedure.
The PROCINFO screen has been modified to reflect this change. The
PRIVILEGE LEVEL OF TARGET field will no longer appear on this screen (see
the "PROCINFO Menu Screen" section of the Switch Programming Guide for a
diagram of the old PROCINFO screen). The new PROCINFO screen is
illustrated in Figure 7-5.
ABILITY TO OVERWRITE EXISTING FILES
Previous versions of SWAT would not allow you to overwrite a file if it
previously existed on the system. Now you have the flexibility to
specify a file for reuse by SWAT. If SWAT determines that a specified
file already exists then you will receive the following warning and
prompt on the MAIN screen:
File specified already exists, press ENTER to overwrite.
________________________________________________________________________________________
| |
| HP30363 Switch Assist Tool PROCINFO |
| COPYRIGHT (C) HEWLETT-PACKARD 1986. ALL RIGHTS RESERVED. |
| |
| [ ] NAME OF TARGET ROUTINE |
| |
| LOCATION OF TARGET PROCEDURE RETURN CONDITION CODE |
| ---------------------------- |
| |
| [ ] GROUP SL [ ] YES, RETURN CONDITION CODE |
| [ ] PUT SL [ ] NO, DO NOT RETURN CODE |
| [ ] SYSTEM SL |
| |
| FUNCTION RETURN TYPE |
| -------------------- |
| |
| [ ] NONE |
| [ ] BYTE |
| [ ] INTEGER |
| [ ] LOGICAL |
| [ ] DOUBLE |
| [ ] REAL |
| [ ] LONG |
| |
| |
| |
| GOTO GOTO ENTER REFRESH PREV NEXT HELP EXIT |
| |
| MAIN COMMIT MODE SCREEN |
________________________________________________________________________________________
Figure 7-5. PROCINFO Screen Without Target Routine Privilege Level Specification
If you do not want to overwrite the file, simply change the filename and
press ENTER. If you want to reuse the file press ENTER to confirm that
you would like to overwrite the file. Once ENTER is pressed, SWAT will
be able to reuse that file and record the new switch stub contents in
this file. Note that the file does not get overwritten until you begin
stub generation at the COMMIT screen.
NEW FUNCTION KEYS ADDED
Two new function keys have been added to SWAT. The first is the GOTO
COMMIT key that allows you to escape to the COMMIT screen and the second
is the ENTER MODE key that enables the screen traversal keys to function
as ENTER before performing their functionality.
GOTO COMMIT Function Key. The GOTO COMMIT was added in order to speed
the switch stub generation process. Pressing the GOTO COMMIT function
key will take you directly to the COMMIT screen allowing you to skip over
the remaining SWAT screens. The following screens have been enhanced to
include this new functionality: The MAIN screen, the PROCINFO Screen,
the PARMINFO screen, and the ARRAYLEN screen. The HELP and FILE screens
do not have this new feature. Remember that in order to keep any changes
made to the current screen, you must press ENTER before pressing the GOTO
COMMIT function key, unless you have ENTER MODE enabled (discussed next
in the "ENTER MODE Function Key" section). Refer to Figure 7-6 for the
position of the GOTO COMMIT function key, F2, on the SWAT screens.
_____________________________________________________________________________________________
| |
| HP30363 Switch Assist Tool MAIN |
| COPYRIGHT (C) HEWLETT-PACKARD 1986. ALL RIGHTS RESERVED. |
| |
| [ ] NAME OF FILE TO HOLD GENERATED SOURCE CODE |
| [ ] NAME OF TARGET CM PROCEDURE |
| |
| P #1 [ ] #2 [ ] |
| A [ ] [ ] |
| R [ ] [ ] |
| A [ ] [ ] |
| M [ ] [ ] |
| E [ ] [ ] |
| T [ ] [ ] |
| E [ ] [ ] |
| R [ ] [ ] |
| [ ] [ ] |
| N [ ] [ ] |
| A [ ] [ ] |
| M [ ] [ ] |
| E [ ] [ ] |
| S [ ] [ ] |
| #31 [ ] #32 [ ] |
| |
| GOTO GOTO ENTER* REFRESH NEXT HELP EXIT |
| |
| FILEFORM COMMIT MODE SCREEN |
_____________________________________________________________________________________________
Figure 7-6. MAIN Screen Illustratin New GOTO COMMIT and ENTER MODE Function Keys
ENTER MODE Function Key. This key introduces the concept of ENTER MODE
and allows you to modify switch stubs faster. The ENTER MODE key (shown
enabled on the MAIN screen above) allows the screen traversal keys (those
labeled with GOTO as well as the PREV and NEXT keys) to act as if you had
first pressed ENTER. Suppose you pressed the PREV key and ENTER MODE is
enabled. SWAT would first process any changes made to the current screen
and then would perform the PREV functionality. If new errors were
introduced with the changes, then SWAT would prompt you to correct them
and would not perform the PREV functionality. If ENTER MODE was disabled
and a screen traversal key was pressed, SWAT would not process any
changes but would perform the action specified on the function key.
To enable and disable ENTER MODE, simply toggle the ENTER MODE function
key, f3, on or off. An asterisk (*) appears on f3 if ENTER MODE is
enabled (on) and disappears if ENTER MODE is disabled (off). ENTER MODE
has no meaning with the HELP, EXIT, or the REFRESH SCREEN functionality.
The HELP, EXIT, and REFRESH SCREEN keys will work the same whether ENTER
MODE is enabled or disabled.
SWAT VERSION AND STUB GENERATION TIME ADDED
The Switch Assist Tool now places the SWAT version and the stub
generation date into the Pascal switch stub source via the following
compiler options:
$version 'STUB GENERATION DATE: MON, NOV 13, 1989, 2:11 PM'$
$version 'CREATED BY SWAT VERSION: A.01.00'$
When the switch stub source is compiled, these two lines of Pascal code
will place the SWAT version that created the stub and the stub generation
date into the system object module (SOM). You can then use the
VERSION.PUB.SYS program to extract this information from the SOM. The
following example illustrates the VERSION program on a SOM that has been
compiled with the two compiler options listed above:
Example
:VERSION somname
VERSION A.22.05 Copyright (C) Hewlett-Packard 1987. All Rights Reserved.
somname.GROUP.ACCOUNT
.
.
.
CREATED BY SWAT VERSION: A.01.00
STUB GENERATION DATE: MON, NOV 13, 1989, 2:11 PM
.
.
.
:
This example shows how using the version program will display the SWAT
version and stub generation date from a SOM. The VERSION program can be
found in PUB.SYS.
SWAT ENHANCEMENT BENEFITS
The five enhancements discussed in this article improve the usability of
SWAT. The benefits to you are summarized below:
* Faster and Easier Modification of Switch Stubs
* Faster Creation of Similar Switch Stubs
* Alternative Method of Creating Switch Stubs
* Ability to Overwrite Files
* Switch Stub Creation Information Saved in SOMs
* Increased Screen Maneuverability
* Less User Information Required to Create a Switch Stub
The most significant enhancement to SWAT is the script functionality.
The SWAT session provides you with an entirely different way of creating
and modifying switch stubs while the SWAT script provides you with a way
of characterizing a switch stub within the source code. The SWAT script
functionality, along with the other enhancements, expands the SWAT
capabilities and greatly improves the usability of the product.