HP 3000 Manuals HP 3000 Manuals
Switch Stubs
A Switch stub is a routine that acts as a facade, hiding the complexity
of the actual Switch call. The primary purpose of Switch stubs is to
provide applications that must call routines residing in an other-mode
library with transparent access to Switch.
Transparency for the application making the mixed-mode call means that
the recompiled calling program usually does not require source changes to
call procedures from its original mode. The Switch stub makes this
transparency possible due to the following factors:
* The Switch stub procedure name is identical to the original procedure
name.
* The stub parameters and their types are equivalent to those of the
original procedure.
* The Switch stub sets up the special parameters required by the Switch
intrinsic (HPSWITCHTOCM, HPSWTONMNAME, or HPLOADNMPROC and
HPSWTONMPLABEL).
* The stub makes the call to the intrinsic.
* The Switch stub handles the necessary return parameters (if any).
In this way, an application program that must now call an other-mode
routine can call an identically named procedure in its own mode and
thereby avoid making changes in the application source code. The only
change required is the addition of a stub procedure to a CM Segmented
Library (SL) or an NM Executable Library (XL).
NOTE Sometimes the calling procedure must change to allow it to do
sophisticated recovery from error situations. Data alignment is an
ongoing concern and possible cause of change.
Operation
The Switch stub is responsible for doing the following:
* Setting up the data structures and parameters required by Switch
intrinsics
* Making the call to the Switch intrinsic, which translates and copies
parameters as required and triggers the change in operating mode
* Retranslating the parameters that the mixed-mode procedure call
returns through Switch
* Setting the condition code on return from the NM routine (CM--> NM
only)
* Error handling
Switch makes the data and parameters of the calling procedure
understandable to the called procedure, and vice versa. Use of a stub
concentrates the programming effort to call the Switch intrinsics in one
place. All calls to the other-mode routine are routed through the stub,
so there is no need for direct calls to the Switch intrinsics by the
application itself.
Use
For the mixed-mode call to succeed, three pieces of code are needed:
* Calling routine
* Switch stub in same mode (NM or CM) as the caller
* Other-mode routine in library of mode opposite the caller (NM
Executable Library or CM Segmented Library)
When a program is loaded (run), the loader cannot bind any unresolved
external references to procedures residing in an other-mode library.
Whenever an external reference is encountered, the loader searches the
specified libraries of the calling mode to resolve that reference. If
the external reference cannot be resolved by a search of those current
mode libraries, then the load fails.
For example, an NM program that refers to an external procedure residing
in a Compatibility Mode (CM) Segmented Library (SL) cannot be loaded.
The CM SL's are not searched by the NM Loader because all entry points in
a program file, executable library, or object library must be in the same
mode. Neither loader resolves an external reference made in one mode to
an executable library in the opposite mode, because object file formats
for the two processors are very different.
Explicit calls to Switch intrinsics resolve such external references by
identifying the file from which to load the procedure and providing the
information needed to translate parameters. This is possible because one
of the parameters passed to the Switch intrinsic designates the library
in which the external procedure can be found. The Switch stub, among
other things, calls the appropriate Switch intrinsic (HPSWITCHTOCM,
HPSWTONMNAME, or HPSWTONMPLABEL), which, in turn, calls the other-mode
procedure.
After you produce and compile a Switch stub, use the Linker or Segmenter
(depending on the mode of the caller) to place the object code in the
appropriate system library (NM Executable Library or CM Segmented
Library) or to incorporate the stub code into the calling program.
Refer to the MPE XL Commands Reference Manual (32650-90003) for
information on the commands used to invoke the various NM and CM
compilers.
Refer to the MPE Segmenter Reference Manual (30000-90011) for information
on CM Segmented Libraries.
Refer to the Link Editor/XL Reference Manual (32650-90030) for
information on linking object code modules into NM program files and
installing object modules in NM Executable Libraries.