HP 3000 Manuals HP 3000 Manuals
HPSWTONM NAME Intrinsic
The HPSWTONMNAME intrinsic allows CM user programs, user libraries, and
system code to invoke NM procedures. In a manner similar to the
HPSWITCHTOCM intrinsic, HPSWTONMNAME does the following:
* Converts the CM references in the argument list to virtual NM
addresses
* Changes the execution mode
* Invokes the NM procedure specified by the CM caller
Since NM code can address the entire CM stack, there is no copying of
reference parameters. The length of each actual parameter is not needed
because lengths are implied in the descriptor list.
The syntax of this intrinsic and detailed explanations of its parameters
are given in the following paragraphs. Also provided are examples of
switches in the CM --> NM direction.
NOTE Switches by name involve high system overhead on the first call per
name, but substantially lower overhead on each subsequent call for
that name. The HPSWTONMNAME, HPSWITCHTOCM, HPLOADCMPROCEDURE, and
HPLOADNMPROC intrinsics perform a hashing function on the name of
the other-mode procedure and store the plabel for that procedure in
a system internal hash table. The LOADPROC intrinsic, on the other
hand, does not perform any hashing and, consequently, involves high
system overhead every time it is called.
Syntax
Prior to calling the HPSWTONMNAME intrinsic, your programming language
may require you to declare it. In Pascal/V, the declaration is as
follows:
FUNCTION HPSWTONMNAME : INTEGER; INTRINSIC;
Next comes an example of a Pascal/V call to this intrinsic:
return_status := HPSWTONMNAME (procname, proclen,
libname, liblen, nparms, arglist,
argdesc, functype);
You call the HPSWTONMNAME intrinsic with eight parameters. These
parameters provide Switch with the following information:
* Name of the NM routine
* Length of the procedure name
* NM library to search for the target procedure
* Length of the library name
* Number of parameters of the NM routine
* Parameter list
* Parameter description list
* Type of the functional return value (if any)
All this information is key to the correct operation of mixed-mode
procedure calls.
CAUTION The strings you supply as values of the Procname and libname
parameters must exactly match the names of the target NM routine
and its NM library, respectively.
Parameters
A detailed explanation of the parameters of the HPSWTONMNAME intrinsics
follows.
Required parameters are shown in boldface; optional parameters are shown
in italics.
procname byte array by reference (required)
Passes the target procedure name. The target procedure
must be contained in an Executable Library (XL). If the
value of procname is invalid, blank, or does not contain
your NM procedure, NL.PUB.SYS is searched.
proclen 16-bit signed integer by value (required)
Passes the byte length of the procedure name.
libname byte array by reference (required)
Passes the name of the NM library to be searched for the
target. If the value of libname is invalid, blank or
does not contain your NM procedure, NL.PUB.SYS is
searched.
liblen 16-bit signed integer by value (required)
Passes the byte length of the library name.
nparms 16-bit signed integer by value (required)
Passes the number of parameters you are passing to the
target NM procedure. It specifies the length of the
argdesc array. You must also account for any hidden
parameters due to ANYVAR parameters, an extensible
parameter list, and so forth. For more information on
hidden parameters, refer to the HP Pascal/XL Reference
Manual (31502-90002).
arglist 16-bit signed integer array by reference (required)
Passes the actual parameters you are going to pass to
the NM procedure.
argdesc 16-bit signed integer array by reference (required)
Passes integer codes describing the parameters held in
the arglist array. Refer to Table 4-2, Table 4-3, and
4-4.
functype 16-bit signed integer by value (required)
Passes the data type of the value the target procedure
returns if it is a function. If the target is not a
function, the value of this parameter is zero. The
supported function types are described in Figure 4.3.
NOTE It is your responsibility to build and load the argument arrays and
make the call to Switch.
The arglist array is an image of the target procedure's argument list as
it would appear in the stack if the routine were in Compatibility Mode.
Space for the function return value (if any) comes first, followed in
order by the first through last parameters. Value parameters are
represented by their values, and reference parameters are represented by
their DB-relative addresses. Each entry in arglist starts on a CM 16-bit
word boundary.
NOTE A function return value is placed in the rightmost 8 bits of the
first element of the arglist array.
The leftmost 8 bits of arglist(1) is used if the NM procedure you
are switching to has a parameter declared as follows:
TYPE bit8 = 0..255;
You need to use whatever construct your MPE V/E-supported
programming language provides to move that 8-bit quantity into the
leftmost 8 bits of the value you assign to arglist(1).
The argdesc array provides additional information required to describe
the parameters in arglist. Whereas arglist specifies the location of the
parameters (value parameters are in the list; reference parameters are
pointed to by the list), argdesc specifies the type of the parameter.
There is usually a one-to-one correspondence between the entries in
argdesc (descriptors) and the parameters to be passed. The first entry
in the argdesc array describes the first parameter, and so on to the last
entry describing the last parameter. The exception (described in the
discussion of the nparms parameter) involves NM target procedures that
have hidden parameters. You must account for any hidden parameters due
to ANYVAR parameters, an extensible parameter list, and so forth. For
more information on hidden parameters, refer to the HP Pascal/XL
Reference Manual (31502-90002).
NOTE Arguments can be longer than one arglist element. For example, it
takes two arglist elements to hold one 32-bit integer passed by
value. The descriptor types map to parameters, not to arglist
elements.
Figure 4.2 illustrates the relationship between the argdesc and arglist
arrays:
![[]](../../pic3k/M000070/F04023c50.gif)
Figure 4.2. ARGDESC and ARGLIST Arrays
The descriptors in the argdesc array are intergers that represent the
type of the associated parameter. The type IDs and their NM and CM sizes
(in bits) are listed in Table 4-1. The types and their associated SPL-HP
Pascal/XL, Pascal/V-HP Pascal/XL, and COBOL II/V-HP Pascal/XL mappings
are listed in Table 4-2, Table 4-3, and Table 4-4, respectively.
Types 1 through 4 direct Switch to pass by value the corresponding
parameters you have placed in arglist
Types 5 and 6 are used to pass reference parameters only. Types 5 and 6
direct Switch to map the DB-relative addresses you place in the
corresponding locations in arglist to equivalent MPE/XL NM virtual
addresses, effectively creating NM pointers from CM pointers. The size
indicated in Table 4-1 for these types is the number of bits required to
contain the CM pointer to that parameter.
Types 7 through 9 should not be used. They are reserved for MPE XL.
Types 10 and 11 are used like types 5 and 6 when the target HP Pascal/XL
procedure expects long pointers to reference parameters.
Types 12 and 13 are used as place holders in the target procedure's
parameter list, standing for optional reference parameters that are
omitted on this call. The corresponding elements(s) of the arglist
parameter should be set to nil.
NOTE Nil is not necessarily 0. The Pascal standard defines nil as being
implementation-dependant. You should test the value of nil in the
Pascal to which you are switching if your Switch call must pass a
nil pointer.
Table 4-1. Parameter Type IDs and Their NM/CM Sizes
---------------------------------------------------------------------------------
| Call Type | Type ID | NM Size (Bits) | CM Size (Bits) |
---------------------------------------------------------------------------------
| By Value | 1 | 8 | 8 |
| | 2 | 16 | 16 |
| | 3 | 32 | 32 |
| | 4 | 64 | 64 |
---------------------------------------------------------------------------------
| By Reference, | 5 | 32 | 16 |
| Short Pointer | | | |
| | 6 | 32 | 16 |
---------------------------------------------------------------------------------
| | 7 | Do not use | Do not use |
| | 8 | Do not use | Do not use |
| | 9 | Do not use | Do not use |
---------------------------------------------------------------------------------
| By reference, | 10 | 64 | 16 |
| Long Pointer | | | |
| | 11 | 64 | 16 |
---------------------------------------------------------------------------------
| Optional | 12 | 32 | 16 |
| Reference | | | |
| Parameters | | | |
| | 13 | 64 | 16 |
---------------------------------------------------------------------------------
When calling Switch from SPL, declare two arrays as follows:
integer array argdesc(0:31);
integer array arglist(0:63);
Then, for each parameter, follow the appropriate instructions given in
Table 4-2.
Table 4-2. SPL--> HP Pascal/XL Parameter Type Mappings
---------------------------------------------------------------------------------
| If the NM procedure you | Declare it like this | And do the following to |
| are switching to has a | in Pascal/V: | pass the Pascal/V |
| parameter declared as | | variable through the |
| follows: | | switch: |
---------------------------------------------------------------------------------
| TYPE bit8 = 0..255; A : | byte A; | argdesc(n) := 1; |
| bit8; | | arglist(n) := A; |
---------------------------------------------------------------------------------
| B : shortint; | integer B; | argdesc(n) := 2; |
| | | arglist(n) := B; |
---------------------------------------------------------------------------------
| C : integer; | double C; integer | argdesc(n) := 3; move |
| | array C'(*) = C; | arglist(n) := C'(0),(2); |
---------------------------------------------------------------------------------
| D : longint; D : anyptr; | integer array D(0:3); | argdesc(n) := 4; move |
| | | arglist(n) := D(0),(4); |
---------------------------------------------------------------------------------
| TYPE pacN = packed array | byte array E(0:N-1); | argdesc(n) := 5; |
| [1..N] of char; VAR E : | | arglist(n) := @E; |
| pacN; | | |
---------------------------------------------------------------------------------
| TYPE 16_bit_ary = array | integer array | argdesc(n) := 6; |
| [1..N] of shortint; TYPE | F(0:N-1); double | arglist(n) := @F; |
| 32_bit_ary = array [1..N] | array F(0:N-1); | |
| of integer; VAR F : | | |
| 16_bit_ary; or VAR F : | | |
| 32_bit_ary; | | |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| VAR J : anyptr; | byte array J(0:N); | argdesc(n) := 10; |
| | | arglist(n) := @J; |
---------------------------------------------------------------------------------
| K : anyptr; | integer array K(0:N); | argdesc(n) := 11; |
| | | arglist(n) := @K; |
---------------------------------------------------------------------------------
| L : localanyptr; | Nothing required. | argdesc(n) := 12; |
| | | arglist(n) := 0; |
---------------------------------------------------------------------------------
| M : anyptr; | Nothing required. | argdesc(n) := 13; |
| | | arglist(n) := 0; |
---------------------------------------------------------------------------------
When calling Switch from Pascal/V, declare two arrays as follows:
TYPE
shortint = -32768..32767;
VAR
argdesc : array [1..32] of shortint;
arglist : array [1..64] of shortint;
Then, for each parameter, follow the appropriate instructions given in
Table 4-3.
Table 4-3. Pascal/V--> HP Pascal/XL Parameter Type Mappings (Page 1)
---------------------------------------------------------------------------------
| If the NM procedure you | Declare it like this | And do the following to |
| are switching to has a | in SPL: | pass the SPL variable |
| parameter declared as | | through the switch: |
| follows: | | |
---------------------------------------------------------------------------------
| TYPE bit8 = 0..255; A : | TYPE bit8 = 0..255; A | argdesc[n] := 1; |
| bit8; | : bit8; | arglist[n] := A; |
---------------------------------------------------------------------------------
| B : shortint; | B : shortint; | argdesc[n] := 2; |
| | | arglist[n] := B; |
---------------------------------------------------------------------------------
| C : integer; | TYPE split_word = | argdesc[n] := 3; |
| | record case integer | arglist[n] := C.hi; |
| | of 0 : (all : | arglist[n+1] := C.lo; |
| | integer); 1 : (hi : | |
| | shortint; lo : | |
| | shortint); end; VAR C | |
| | : split_word; | |
---------------------------------------------------------------------------------
| D : longint; or D : | TYPE split_long = | argdesc[n] := 4; |
| anyptr; | record case integer | arglist[n] := D.sh[1]; |
| | of 0:(all : | arglist[n+1] := D.sh[2]; |
| | array[1..2] of | arglist[n+2] := D.sh[3]; |
| | shortint); 1:(sh : | arglist[n+3] := D.sh[4]; |
| | array[1..4] of | |
| | shortint); end; VAR D | |
| | : split_long; | |
---------------------------------------------------------------------------------
| TYPE pacN = packed array | TYPE pacN = packed | argdesc[n] := 5; |
| [1..N] of char; VAR E : | array [1..N] of char; | arglist[n] := |
| pacN; | VAR E : pacN; | baddress(E); |
---------------------------------------------------------------------------------
TABLE 4.3 Ppascal/V--> HP Pascal/XL Parameter Type Mappings (
---------------------------------------------------------------------------------
| If the NM procedure you | Declare it like this | And do the following to |
| are switching to has a | in SPL: | pass the SPL variable |
| parameter declared as | | through the switch: |
| follows: | | |
---------------------------------------------------------------------------------
| TYPE 16_bit_ary = array | TYPE 16_bit_ary = | argdesc[n] := 6; |
| [1..N] of shortint; TYPE | array [1..N] of | arglist[n] : |
| 32_bit_ary = array [1..N] | shortint; TYPE | waddress(F); |
| of integer; VAR F : | 32_bit_ary = array | |
| 16_bit_ary; or VAR F : | [1..N] of integer; | |
| 32_bit_ary; | VAR F : 16_bit_ary; | |
| | or VAR F : | |
| | 32_bit_ary; | |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| J : anyptr; | J : packed array | argdesc[n] := 10; |
| | [1..N] of char; | arglist[n] := |
| | | baddress(J); |
---------------------------------------------------------------------------------
| K : anyptr; | K : array [1..N] of | argdesc[n] := 11; |
| | shortint; | arglist[n] := |
| | | waddress(K); |
---------------------------------------------------------------------------------
| L : localanyptr; | Nothing required. | argdesc[n] := 12; |
| | | arglist[n] := NIL; |
---------------------------------------------------------------------------------
| M : anyptr; | Nothing required. | argdesc[n] := 13; |
| | | arglist[n] := NIL; |
---------------------------------------------------------------------------------
When calling Switch from COBOL II/V, declare two arrays as follows:
01 ARGDESC PIC S9(4) COMP OCCURS 32 TIMES.
01 ARGLIST PIC S9(4) COMP OCCURS 64 TIMES.
Then, for each parameter, follow the appropriate instructions given in
Table 4-4.
Table 4-4. COBOL II/V -> HP Pascal/XL Parameter Type Mappings(Page 1)
---------------------------------------------------------------------------------
| If the NM procedure you | Declare it like this | And do the following to |
| are switching to has a | in COBOL II/V: | pass the COBOL II/V |
| parameter declared as | | variable through the |
| follows: | | switch: |
---------------------------------------------------------------------------------
| TYPE bit8 = 0..255; A : | 01 A PIC X. or 01 A | MOVE A TO ARGLIST(N). |
| bit8; | PIC 9. or 01 A PIC 9 | |
| | COMP. | |
---------------------------------------------------------------------------------
| B : shortint; | 01 B PIC S9 COMP. 01 | MOVE B TO ARGLIST(N). |
| | B PIC S9(2) COMP. 01 | |
| | B PIC S9(3) COMP. 01 | |
| | B PIC S9(4) COMP. | |
---------------------------------------------------------------------------------
| C : integer; | 01 C PIC S9(5) COMP. | MOVE C-HI TO ARGLIST(N). |
| | 01 C PIC S9(6) COMP. | MOVE C-LO TO |
| | 01 C PIC S9(7) COMP. | ARGLIST(N+1). |
| | 01 C PIC S9(8) COMP. | |
| | 01 C PIC S9(9) COMP. | |
| | 01 C-SPLIT REDEFINES | |
| | C. 05 C-HI PIC S9(4) | |
| | COMP. 05 C-LO PIC | |
| | S9(4) COMP. | |
---------------------------------------------------------------------------------
| D : longint; | 01 D PIC S9(10) COMP. | MOVE D-SHORT(1) TO |
| | 01 D PIC S9(11) COMP. | ARGLIST(N). MOVE |
| | 01 D PIC S9(12) COMP. | D-SHORT(2) TO |
| | 01 D PIC S9(13) COMP. | ARGLIST(N+1). MOVE |
| | 01 D PIC S9(14) COMP. | D-SHORT(3) TO |
| | 01 D PIC S9(15) COMP. | ARGLIST(N+2). MOVE |
| | 01 D PIC S9(16) COMP. | D-SHORT(4) TO |
| | 01 D PIC S9(17) COMP. | ARGLIST(N+3). |
| | 01 D PIC S9(18) COMP. | |
| | 01 D-SPLIT REDEFINES | |
| | D. 05 D-SHORT PIC | |
| | S9(4) COMP OCCURS 4 | |
| | TIMES. | |
---------------------------------------------------------------------------------
| TYPE pacN = packed | 01 E PIC X(80). (or | CALL ".LOC." USING E |
| array[1..N] of char; VAR | any size array) | GIVING ARGLIST(N). |
| E : pacN; or VAR E : | | |
| localanyptr; | | |
---------------------------------------------------------------------------------
| TYPE 16_bit_ary = array | 01 F PIC S9(9) COMP | CALL ".LOC." USING F |
| [1..N] of shortint; TYPE | OCCURS 10 TIMES. (or | GIVING ARGLIST(N). |
| 32_bit_ary = array [1..N] | any size array) | |
| of integer; VAR F : | | |
| 16_bit_ary; or VAR F : | | |
| 32_bit_ary; or VAR F : | | |
| localanyptr; | | |
---------------------------------------------------------------------------------
Table 4-4. COBOL II/V -> HP Pascal/XL Parameter Type Mappin
---------------------------------------------------------------------------------
| If the NM procedure you | Declare it like this | And do the following to |
| are switching to has a | in COBOL II/V: | pass the COBOL II/V |
| parameter declared as | | variable through the |
| follows: | | switch: |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| Reserved for MPE XL. | Do not use. | Do not use. |
---------------------------------------------------------------------------------
| VAR J : anyptr; | 01 J PIC X(80) OCCURS | CALL ".LOC." USING J |
| | N TIMES. | GIVING ARGLIST(N). |
---------------------------------------------------------------------------------
| K : anyptr; | 01 K PIC S9(9) COMP | CALL ".LOC." USING K |
| | OCCURS N TIMES. | GIVING ARGLIST(N). |
---------------------------------------------------------------------------------
| L : localanyptr; | Nothing required. | MOVE 0 TO ARGLIST(N). |
---------------------------------------------------------------------------------
| M : anyptr; | Nothing required. | MOVE 0 TO ARGLIST(N). |
---------------------------------------------------------------------------------
Function returns are described using a similar scheme. Those mappings
are given in Figure 4.3.
TYPE SPL Function CM Size Pascal/XL NM Size
ID Type (Bytes) Function Type (Bytes)
0 none (0) not a function (0)
1 byte (1) bit8 (1)
2 integer (2) shortint (2)
3 double (4) integer (4)
4 long (8) longreal (8)
Figure 4.3. Supported Function Type Mappings
NOTE A function return value is placed in the rightmost 8 bits of the
first element of the arglist array. The leftmost 8 bits of
arglist(1) is used if the NM procedure you are switching to has a
parameter declared as follows:
TYPE bit8 = 0..255;
You need to use whatever construct your MPE V/E-supported
programming language provides to move that 8-bit quantity into the
leftmost 8 bits of the value you assign to arglist(1).