HP 3000 Manuals HP 3000 Manuals
Generating Switch Stubs Automatically
The Switch Assist Tool and its user interface help you create the Switch
stub source code, which has the following components:
* Compiler commands
* Data structures
* Logic
Specifically, in producing the source code of a stub procedure, SWAT does
the following:
1. Converts the SPL procedure name and variable names to
valid HP Pascal/XL names
2. Generates the top global area code
3. Generates the stub procedure declaration and parameters
4. Generates the stub procedure local variables and its
BEGIN statement
5. Generates the stub procedure body code to prepare the
Switch call parameters
6. Generates the code to call the Switch intrinsic
7. Generates the code to check the status and calls the
QUIT intrinsic when Switch encounters an error
8. Generates the END statement of the stub procedure
9. Generates the bottom global area code
NOTE SWAT output is a stub written in HP Pascal/XL, no matter what
language the original application was written in. The Switch stub
source code produced by SWAT is, in turn, input for the HP
Pascal/XL compiler, which produces Switch stub object code. For
more information on how to invoke this compiler, see the discussion
of the PASXL command in the MPE XL Commands Reference Manual
(32650-90003). Compilation of that source must be on an MPE
XL-based machine. The resulting object code is input to the MPE XL
Link Editor, where you can either install the object code in an NM
Executable Library or link it into an NM program file. For more
information on the Link Editor, refer to Link Editor/XL Reference
Manual (32650-90030).
Invoking SWAT
To invoke SWAT, enter the following at the system prompt:
RUN SWAT.PUB.SYS
What SWAT Needs to Know
In order to generate NM--> CM Switch stubs, SWAT needs to know the
following information:
* Name of the text file into which SWAT should place the generated
source code
* Name of the procedure to be called
* Location of that procedure (for example, CM system, account, or group
Segmented Library)
* Type (expressed in SPL terminology) of the function return value if
the Switch call is to a function
* Whether the stub procedure should pass any condition code to the
caller
* Number of parameters Switch is to pass to the procedure
* Addressing method, data type, I/O type, and length of each parameter
in the calling sequence of the procedure Switch is to invoke (for
arrays, length is specified as the number of elements)
NOTE The process of gathering information about parameters is iterative.
How SWAT Obtains Information
When you run SWAT, SWAT uses VPLUS screens to prompt you for this
required information. There are a total of seven screens that you may
encounter as you enter the information required by SWAT, request help on
how to complete a form screen, edit forms or confirm your satisfaction
with the completed forms, and await the result of the stub generation
process. The names of the screens (discussed in detail below) are as
follows:
* MAIN menu screen (see Figure 2.3)
* PROCINFO menu screen (see Figure 2.4)
* PARMINFO menu screen (see Figure 2.5)
* ARRAYLEN menu screen (see Figure 2.6)
* HELP facility screens (see Figure 2.7 and Figure 2.10)
* COMMIT screen (see Figure 2.11)
* PROGRESS MESSAGES screen (see Figure 2.12)
Typical SWAT Work Session
The normal progression in a work session with SWAT is to complete the
MAIN menu information first and then the PROCINFO menu. Based on the
information you entered in the MAIN menu, the PARMINFO menu appears
repeatedly, once for every parameter you entered by name in the MAIN
menu. If, in the course of filling out the PARMINFO menu, you indicate
that a parameter is an array, the ARRAYLEN menu will appear.
The contents of a HELP screen depend on the menu you are in at the time
of the request for help.
After committing your menu selections via the COMMIT screen, stub
generation begins and you are placed in the PROGRESS MESSAGES screen so
you can track the generation process.
After generation of Switch stub source code is complete, the MAIN menu
screen reappears, allowing you to build another stub or to exit SWAT and
return to the system Command Interpreter.
Inputting Information
You move from field to field and item to item within a menu by means of
the Cursor Control keys or the Tab key. To complete some fields, you
must enter a name or numerical value. In other instances, the field
consists of a list of options. You complete such fields by placing a
nonblank character next to the option of your choice.
At any point before actually committing the information in the menus and
beginning the generation of a stub, you can move back and forth through
the menus in order to change their contents or request help on how to
complete a menu item.
To input the information entered on the menu to SWAT, press the [[Enter]]
key. This records your selections, but does not prevent you from
reviewing and editing them. When you press the [[Enter]] key, SWAT
performs error-checking on your selections.
Resolving Errors
The Switch Assist Tool helps you resolve any problems that may arise in
completing a menu.
The tool uses highlighting to indicate any fields that contain errors.
It also prints a diagnostic message at the bottom of the screen. You can
use the highlighting and the message to make corrections to the menu.
SWAT places the cursor in the topmost field containing an error. After
making the correction suggested by the message, press [[Enter]]. If your
correction resolves the error, both the message and the highlighting
disappear. If not, the highlighting remains, and a new message may
appear to help you resolve the problem.
If your menu contains more than one error, you can resolve them one by
one in this same manner. After you resolve the topmost field, the
highlighting of other errors remains, the cursor moves to the next field
containing an error, and a message appropriate to that error appears at
the bottom of the screen. In this way, the tool guides you through the
correction process.
When the last error is resolved, the Switch Assist Tool records your
entries when you press [[Enter]] and brings up the next menu.
MAIN Menu Screen
The MAIN menu screen is the first to appear upon invoking SWAT. To
complete this menu, you need to supply the following information:
* Name of the file to hold the source code generated by SWAT
* Name of the target procedure
* Names of the target's parameters (up to 32)
Designating the Source Code File. The file name to hold the source code
generated by SWAT can have a maximum of eight characters. SWAT creates a
fixed ASCII type file in the group and account in which you are currently
logged on. If you do not enter a file name, you receive a message
indicating that you cannot leave this field blank. The cursor is
repositioned to the file name field.
NOTE Fully qualified file names and passwords are not allowed.
Designating the Target CM Procedure. The target procedure is the
procedure to be called by means of the SWAT-generated stub. Its name can
have a maximum of sixteen characters. Again, if you do not enter a name,
you receive a message indicating that it is not possible to leave this
field blank. The cursor returns to the beginning of this field.
Designating the Target Procedure Parameters. SWAT allows calls to target
procedures with up to 32 parameters. It is important to note that you
must enter target parameters in the same order as the calling sequence of
the target procedure. Parameter names can be up to a maximum of 32
characters long. You may leave these fields blank, indicating that the
target procedure has no parameters.
NOTE Procedure and parameter names are not localizable. They are
limited to the alphanumeric characters of the English alphabet.
All entries are checked for validity. However, the Switch Assist
Tool does not check for use of HP Pascal/XL reserved words and
predefined routines as names. For more information about reserved
words and predefined routine names in HP Pascal/XL, refer to the HP
Pascal/XL Reference Manual (31502-90001).
Refer to Figure 2.3 for an illustration of the MAIN menu screen.
![[]](../../pic3k/M000070/F02033c50.gif)
Figure 2.3. MAIN Menu Screen
MAIN Menu Function Keys. There are several function key options
available to you on the MAIN menu screen:
* Press F4 to refresh the screen.
* Press F6 to proceed to the next menu (used for reviewing and editing
menu contents).
* Press F7 to view the HELP screen on the MAIN menu.
* Press F8 to exit SWAT and return to the system Command Interpreter.
CAUTION Pressing F8 at any time returns you immediately to the system
prompt, causing you to lose any information entered up to that
point.
Completing the MAIN Menu Screen. To input the information entered on the
menu to SWAT and initiate error-checking, press the [[Enter]] key.
The process of correcting MAIN menu errors is the same as that described
in "Resolving Errors" .
PROCINFO Menu Screen
The PROCINFO menu screen collects information concerning the procedure to
be invoked by the SWAT-generated stub. The name of this procedure is
displayed at the top of the PROCINFO menu. It is the same name that you
entered on the MAIN menu screen. You can change that name on the
PROCINFO screen if you desire. Switch needs to know the following
information about this procedure:
* Location of the target procedure (CM system, account, or group
Segmented Library)
* Data type of its return value if it is a function
* Privilege level of the target procedure
* Whether the target procedure returns a condition code
For each of the five fields listed above, the appropriate number of legal
options is provided on the PROCINFO menu. You can select one value for
each field. You make your selection by placing a nonblank character in
the space provided next to the appropriate value. For some fields,
default values are provided.
You cannot leave any of the five fields blank. If you do so, the cursor
is repositioned at the blank field, and an appropriate error message is
sent to the screen.
Designating the Location of the Target Procedure. The target procedure
must be located in some CM Segmented Library (SL). This may be the system
library, an account library, or a group library. If you specify the
system library, only the system SL is searched. If you specify an
account library, the account library is searched first, then the system
library. Finally, if you specify a group library, the group library is
searched first, followed in turn by that group's account library and the
system library. The target procedure need not be installed in order for
SWAT to generate Switch stub source code for calling the target.
Designating the Function Return Type of the Target Procedure. If the
target procedure is not a function (that is, does not return a value as a
functional return value), you should select the NONE value in the field
designating the function return type. Otherwise, select the appropriate
data type from the list of possibilities.
Designating the Privilege Level of the Target Procedure. SWAT designates
NON-PRIVILEGED as the default value for the privilege level of the target
procedure. To access user-written CM SL procedures, simply accept this
default value.
Designating Whether the Target Procedure Returns a Condition Code. Every
process has an associated condition code. A condition code is a
temporary value that provides information about process execution. From
the condition code value, you can learn some basic information regarding
what happened during execution of the process. This code has three
possible values, which are assigned as follows:
* CCE, or Condition Code Equal (=), generally indicating that the
process executed successfully
* CCG, or Condition Code Greater Than (>), indicating that a special
condition occurred, but may not have affected the execution of the
process
* CCL, or Condition Code Less Than (<), indicating that the process did
not execute successfully, but the error condition may be recoverable
Since this code is affected by many processes, you should check its value
immediately upon return from a process. To return the condition code
from the target CM routine, select the YES, RETURN CONDITION CODE option
on the PROCINFO screen.
Figure 2.4 provides an example of the PROCINFO menu screen.
![[]](../../pic3k/M000070/F02043c50.gif)
Figure 2.4. PROCINFO Menu Screen
PROCINFO Menu Function Keys. There are several function key options
available to you on the PROCINFO menu screen:
* Press F1 to return to the MAIN menu.
* Press F4 to refresh the screen.
* Press F5 to go back to the previous menu.
* Press F6 to proceed to the next menu (for reviewing/editing
information, not recording it).
* Press F7 to view the HELP screen on the PROCINFO menu.
* Press F8 to exit SWAT and return to the system Command Interpreter.
Completing the PROCINFO Menu. To input the information entered on the
menu to SWAT and initiate error checking, press the [[Enter]] key.
The process of correcting PROCINFO menu errors is the same as that
described in "Resolving Errors" .
PARMINFO Menu Screen
The PARMINFO menu screens collect information concerning the parameters
to be passed to the target routine. This screen appears repeatedly, once
for each parameter you entered on the MAIN menu screen. The name of each
parameter appears at the top of the PARMINFO menu screen, just as you
entered it on the MAIN menu. You can change that name on the PARMINFO
screen, if desired. The order in which the PARMINFO screens appear
reflects the order in which you entered these parameter names and, thus,
the call sequence of the target routine.
The type of information about each parameter that Switch needs includes
the following:
* Addressing method of the parameter
* Data type of the parameter
* I/O type of the parameter, relative to the target CM procedure
* Whether the parameter is an array
The appropriate legal options are provided on the PARMINFO menu. You can
select one value for each field. You make your selection by placing a
nonblank character in the space provided next to the appropriate value.
You cannot leave any of the fields blank. If you do so, the cursor is
repositioned at the blank field. SWAT also checks that you have not
specified a multi-element item as a value parameter.
Designating a Parameter's Addressing Method. In specifying the
addressing method of a parameter, you indicate whether the parameter is
passed as a reference parameter or as a value parameter.
NOTE In COBOL, all parameters are passed by reference unless surrounded
by \\.
Designating a Parameter's Data Type. The data type of a parameter must
be specified in SPL terminology. SWAT does not handle the following data
types: pointers, labels, plabels, and arrays passed by value. Any types
not covered require manual programming of Switch stubs. The section
entitled "Special Cases" provides more detail about unsupported data
types.
NOTE For further details on SPL addressing methods and data types, refer
to Systems Programming Language Reference Manual (30000-90024).
Designating a Parameter's I/O Type. In the field designating the I/O
type, you designate whether the parameter is an input parameter, an
output parameter, or an input/output parameter, relative to the target CM
procedure. If the parameter is an input parameter, data goes from the NM
to the CM stack, but not back. On the other hand, for an output
parameter, data is returned from the CM stack to the NM stack. In the
case of input/output parameters, data goes from the NM to the CM stack,
and back again.
Designating Whether a Parameter Is an Array. You must indicate whether a
parameter is an array. You do so by designating the appropriate option
in the ARRAY SPECIFICATION field. If you indicate that a parameter is an
array, the ARRAYLEN menu screen subsequently appears to collect
information about the length of the array parameter.
A sample PARMINFO menu screen appears in Figure 2.5.
![[]](../../pic3k/M000070/F02053c50.gif)
Figure 2.5. PARMINFO Menu Screen
PARMINFO Menu Function Keys. There are several function key options
available to you on the PARMINFO menu screen:
* Press F1 to return to the MAIN menu.
* Press F4 to refresh the screen.
* Press F5 to go back to the previous screen.
* Press F6 to proceed to the next screen (for reviewing/editing
information, not recording it).
* Press F7 to view the HELP screen on the PARMINFO menu.
* Press F8 to exit SWAT and return to the system Command Interpreter.
Completing the PARMINFO Menu. To input the information entered on the
menu to SWAT and initiate error checking, press the [[Enter]] key.
The process of correcting PARMINFO menu errors is the same as that
described in "Resolving Errors" .
ARRAYLEN Menu Screen
The ARRAYLEN menu screen appears only if you have indicated that a
parameter is an array on the PARMINFO menu screen. The ARRAYLEN screen
collects information concerning array parameters to be passed to the
routine you want to call in the Compatibility Mode environment.
The array information required by the Switch Assist Tool includes the
following:
* Length of the array parameter
* How the length value should be interpreted
You cannot leave any of the fields blank. If you do so, the cursor is
repositioned at the blank field.
Designating the Length Value of an Array Parameter. You have two options
when specifying the length (size) of an array parameter. One way is to
designate a specific constant value in the range of 1 to 65,535. If that
is your choice, enter a decimal number in the space provided. The number
of array elements allowed depends on the SPL data type in the target CM
array parameter. Table 2-1 lists the allowed array element ranges for
the various SPL data types.
Table 2-1. Number of Allowed Array Elements By Type
-----------------------------------------------------------------------------
| SPL Array Element Type | No. of Array Elements Allowed |
-----------------------------------------------------------------------------
| Byte | 1...65,535 |
| Integer | 1...32,767 |
| Logical | 1...32,767 |
| Double | 1...16,383 |
| Real | 1...16,383 |
| Long | 1...8,191 |
-----------------------------------------------------------------------------
You can also use the value of a parameter to specify the length of an
array. If that is your choice, enter the parameter name in the space
provided. The name specified must be the name of another parameter being
passed to the target procedure. If it is not, SWAT displays an error
message.
Designating How to Interpret the Array Length Usage Value. In addition
to indicating the length of an array (either as a constant value or by
means of a parameter name), you must also indicate how SWAT should
interpret that value. The length usage value specifies one of the
following:
* Number of array elements.
* Number of bytes in the array.
* Negative = Bytes / Positive = Elements Rule
If you select the third option, the following apply:
* If the parameter has a positive value, that value represents the size
as the number of elements.
* If the value of the parameter is negative, the parameter represents
the size as the number of bytes.
Select the appropriate option by placing a nonblank character in the
space provided next to your choice.
CAUTION If you specify an array size larger than its declared size,
unpredictable results occur when the stub is executed.
A sample ARRAYLEN menu screen appears in Figure 2.6.
![[]](../../pic3k/M000070/F02063c50.gif)
Figure 2.6. ARRAYLEN Menu Screen
ARRAYLEN Menu Function Keys. There are several function key options
available to you on the ARRAYLEN menu screen:
* Press F1 to return to the MAIN menu.
* Press F4 to refresh the screen.
* Press F5 to go back to the previous screen.
* Press F6 to proceed to the next screen (for reviewing/editing
information, not recording it).
* Press F7 to view the HELP screen on the ARRAYLEN menu.
* Press F8 to exit SWAT and return to the system Command Interpreter.
Completing the ARRAYLEN Menu. To input the information entered on the
menu to SWAT and initiate error checking, press the [[Enter]] key.
The process of correcting ARRAYLEN menu errors is the same as that
described in "Resolving Errors" .
HELP Screens
There are HELP screens for each of the menu screens that make up the SWAT
user interface.
There are several function key options available to you in the HELP
facility:
* Press F4 to refresh the screen.
* Press F5 to go back to the previous screen.
* Press F6 to proceed to the next screen.
* Press F8 to exit the HELP facility.
MAIN Menu HELP Screen. The MAIN menu HELP screen provides information to
help you complete the items requested in the MAIN menu screen:
* Name of the file to hold source code generated by SWAT
* Name of the target procedure
* Name(s) of the parameters of the target procedure (up to 32)
Figure 2.7 illustrates the appearance of the introductory MAIN menu HELP
screen.
The MAIN screen gathers the following global information:
* the name of the file to hold the source code produced
by the Switch Assist Tool
* the name of the target procedure you want to call in
the Compatibility Mode (CM) environment
* the names of the target procedure's parameters (up to 32)
From the MAIN screen, you may:
1. Press (F4) to refresh the screen.
2. Press (F6) to proceed to the PROCINFO screen.
3. Press (F7) to enter the HELP facility, where you are now.
4. Press (F8) to exit the program entirely, returning to MPE.
5. Fill in the empty fields on the form, and press (ENTER).
Figure 2.7. Main Menu Help Screen
PROCINFO Menu HELP Screen. The PROCINFO menu HELP screen provides
information to help you complete the items requested in the PROCINFO menu
screen:
* Location of the target procedure
* Type of the return value if the target procedure is a function
* Privilege level of the target procedure
* Whether the target procedure returns a condition code
Figure 2.8 illustrates the appearance of the introductory PROCINFO menu
HELP screen.
The PROCINFO screen collects information about the procedure
you want to call in the Compatibility Mode environment. The
Switch Assist Tool needs the following information about the
target procedure:
* the location of the target procedure
* the type of its return value if it is a function
* the privilege level of the target procedure
* whether the target procedure returns a condition code
From the PROCINFO screen, you may:
1. Press (F1) to return to the MAIN screen.
2. Press (F4) to refresh the screen.
3. Press (F5) to return to the previous screen.
4. Press (F6) to proceed to the next screen.
5. Press (F7) to enter the HELP facility, where you are now.
6. Press (F8) to exit the program entirely, returning to MPE.
7. Fill in the empty fields on the form, and press (ENTER).
Figure 2.8. PROCINFO Menu Help Screen
PARMINFO Menu HELP Screen. The PARMINFO menu HELP screen provides
information to help you complete the items requested in the PARMINFO menu
screen:
* Addressing method of a parameter
* Data type of a parameter
* I/O type of a parameter
* Whether the parameter is an array and, if so, how many elements are
in that structure
Figure 2.9 illustrates the appearance of the introductory PARMINFO menu
HELP screen.
The PARMINFO screens collect information concerning the
parameters to be passed to the routine you want to call in the
Compatibility Mode environment. The parameter information
required by the Switch Assist Tool includes the following:
* the addressing method of the parameter
* the data type of the parameter
* the I/O type of the parameter
* whether the parameter is an array
From the PARMINFO screen, you may:
1. Press (F1) to return to the MAIN screen.
2. Press (F4) to refresh the screen.
3. Press (F5) to return to the previous screen.
4. Press (F6) to proceed to the next screen.
5. Press (F7) to enter the HELP facility, where you are now.
6. Press (F8) to exit the program entirely, returning to MPE.
7. Fill in the empty fields on the form, and press (ENTER).
Figure 2.9. PARMINFO Menu Help Screen
ARRAYLEN Menu HELP Screen. The ARRAYLEN menu HELP screen provides
information to help you complete the items requested in the ARRAYLEN menu
screen:
* Length of the array parameter
* How the array length value (either a constant value or a parameter
name) should be interpreted
Figure 2.10 illustrates the appearance of the introductory ARRAYLEN menu
HELP screen.
The ARRAYLEN screens collect information concerning the arrays
to be passed to the routine you want to call in the
Compatibility Mode environment. The array information
required by the Switch Assist Tool includes the following:
* the length of the array parameter
* how the length value should be interpreted
From the ARRAYLEN screen, you may:
1. Press (F1) to return to the MAIN screen.
2. Press (F4) to refresh the screen.
3. Press (F5) to return to the previous screen.
4. Press (F6) to proceed to the next screen.
5. Press (F7) to enter the HELP facility, where you are now.
6. Press (F8) to exit the program entirely, returning to MPE.
7. Fill in the empty fields on the form, and press (ENTER).
Figure 2.10. ARRAYLEN Menu Help Screen
COMMIT Screen
The COMMIT screen does not request that you supply information to
complete a menu. Instead, this screen presents you with the following
function key options:
* Press F1 to return to the MAIN menu.
* Press F2 to commit your menu selections and allow SWAT to begin stub
generation.
* Press F4 to refresh the screen.
* Press F5 to return to the previous screen.
* Press F7 to view the HELP screen that deals with the COMMIT screen.
* Press F8 to leave SWAT.
These options let you decide whether SWAT should begin generating Switch
stub source code or whether you need to edit information entered in the
menu screens. Recall that the Previous (and Next) function keys allow
you to review and edit any SWAT menu screen. The COMMIT screen does not
allow you to begin Switch stub generation if any menus remain unresolved.
The COMMIT screen presents messages that indicate which menus or items
need resolution.
Figure 2.11 illustrates the appearance of the COMMIT screen:
![[]](../../pic3k/M000070/F02113c50.gif)
Figure 2.11. COMMIT Screen
PROGRESS MESSAGES Screen
The PROGRESS MESSAGES screen appears after you have committed your menu
selections by means of the COMMIT screen. In addition to displaying the
name of the stub procedure and the line number currently being processed,
the PROGRESS MESSAGES screen has space to display any progress, result,
or error messages that SWAT has to report as it generates the source code
for the stub. An example PROGRESS MESSAGES screen follows in Figure
2.12:
![[]](../../pic3k/M000070/F02123c50.gif)
Figure 2.12. PROGRESS MESSAGES Screen
Completion of Stub Generation
After generation of Switch stub source code is complete, the MAIN menu
screen reappears, allowing you to build another stub or to exit SWAT and
return to the system Command Interpreter.