HP 3000 Manuals HP 3000 Manuals
HPSWITCH TOCM Intrinsic
The mechanism that enables mixed-mode calls in the NM--> CM direction is
the HPSWITCHTOCM intrinsic.
Specifically, HPSWITCHTOCM does the following:
* Copies value parameters to the CM stack
* Translates NM addresses of reference parameters to CM addresses when
they are within the CM data segment (split-stack mode only)
* Copies NM reference parameters to the CM data segment if they are
input parameters, converts NM addresses to CM addresses, then copies
the parameters back to the NM data space
* Changes the execution mode
* Calls the CM procedure specified by the NM caller
There are three methods of passing reference parameters to the target
procedure:
* Normal method
* Split-stack method
* No-copy method
The normal method is the only one available to callers with execution
level three (standard user level). This method does the following:
* Allocates room for the NM parameter(s) in the CM stack
* Copies the contents of the NM parameter(s) to the CM stack (if input
parameters) and allocates space for output parameters
* Copies the CM results back to the NM parameter(s) upon target
completion (if output parameters and if not already in the CM stack)
CAUTION HPSWITCHTOCM does no checking for overlapping reference
parameters. On MPE V/E-based systems, you may have used
overlapping reference parameters to obtain side effects since
both copies could share the overlap area. In Native Mode, the
parameters will overlap. In Compatibility Mode, however, the
parameters will be placed one on top of the other on the CM
stack. If you rely on this particular effect, the results will
not be as expected.
If a procedure is split-stack callable, HPSWITCHTOCM encapsulates the
reference parameters within an extra data segment and calls the target
procedure with DB at the base of the extra data segment. When the CM
target procedure returns, the extra data segment is released and the DB
register is set back to its previous value.
No extra data segment is created, even if requested, if any of the
following conditions applies:
* There are no reference parameters (DB is unchanged).
* All reference parameters are already in the CM stack (DB points to
the CM stack).
* The reference parameters are either too large or too distant from one
another to be encapsulated by an extra data segment.
* The total size of the reference parameters is less than a fixed
threshold (300 bytes), in which case copying them to the CM stack is
quicker.
* An extra data segment cannot be obtained, in which case the
parameters are copied to the CM stack.
The no-copy method is the same as the split-stack method except that the
threshold check is omitted.
NOTE Both the split-stack and the no-copy methods require Privileged
Mode.
The syntax of the HPSWITCHTOCM intrinsic and detailed explanations of its
parameters are given in the following paragraphs. Also provided are
examples of switches in the NM--> CM direction.
Syntax
Prior to calling the HPSWITCHTOCM intrinsic, your programming language
may require you to declare it. In HP Pascal/XL, the declaration is as
follows:
PROCEDURE HPSWITCHTOCM; INTRINSIC;
Next comes an example of an HP Pascal/XL call to HPSWITCHTOCM:
HPSWITCHTOCM(proc, method, nparms, parms, fretlen,
fretval, condcode, status);
You call the HPSWITCHTOCM intrinsic with eight parameters. These
parameters provide Switch with the following information:
* Name and CM library or the plabel of the target procedure.
* Whether the target procedure runs in normal, split-stack, or no-copy
mode.
* Number of parameters being passed to the target procedure.
* Array of records, each record containing a description of one
parameter being passed, including:
* Pointer to the parameter; that is, a reference to where the
parameter begins in NM memory (value parameters larger than one
byte must be 16-bit aligned).
* Length (size) of the parameter in bytes (must be positive,
nonzero integer <= 2 ** 16).
* For reference parameters, the stub must specify either a byte or
word address and also indicate whether the parameter is an input
and/or output parameter.
* Length of the function return value (0 if not a function).
* Pointer to the function return value (nil if not a function).
* CM condition code value to be returned from the target procedure.
* Status record to report on HPSWITCHTOCM's operation.
NOTE If the SPL procedure is option variable (see the MPE V/E Intrinsics
Reference Manual (32033-90007) or the header of a non-intrinsic SPL
procedure), you must construct the option variable mask and pass it
as the last parameter. See Example 3-11 for an illustration.
All this information is key to the correct interpretation of data, return
values, and status information when you make mixed-mode procedure calls.
Parameters
A detailed explanation of the parameters of the HPSWITCHTOCM intrinsic
follows.
Required parameters are shown in boldface; optional parameters are shown
in italics.
proc record (required)
Passes the target CM procedure identifier, which you can
specify either by a library to search and an ASCII name
of up to 16 characters or by a CM plabel (obtained from
the HPLOADCMPROCEDURE or LOADPROC intrinsic).
The structure of the proc record varies, depending on
how the target procedure is identified. All variants
have a p_proc_id_type field. The HP Pascal/XL
declaration of this record follows:
TYPE
BIT8 = 0..255;
BIT16 = 0..65535;
BIT8_A1 = $ALIGNMENT 1$ BIT8;
BIT16_A1 = $ALIGNMENT 1$ BIT16;
CM_PROC_NAME = PACKED ARRAY[1..16] OF CHAR;
scm_procedure = packed record
{pidt_known, pidt_load, pidt_plabel}
case p_proc_id_type : bit8 of
{proc found by number}
pidt_known : ( p_fill : bit8_a1;
p_proc_id : bit16_a1 );
{proc found by name}
pidt_load : (
{system, pub, or group library}
p_lib : bit8_a1;
{ASCII name left justified & blank padded}
p_proc_name : cm_proc_name);
{proc found by plabel}
pidt_plabel : (
{proc's CM plabel}
p_plabel : bit16_a1);
end;
If you designate the target CM procedure by means of an ASCII name, then
the following apply:
* The value of the p_proc_id_type field is 1.
* The search library is designated in a p_lib field whose value can be
0 for the system SL, 1 for the logon pub SL, 2 for the logon group
SL, 3 for the program's pub SL, or 4 for the program's group SL.
* The ASCII name is designated in the p_proc_name field and can be up
to 15 bytes long. The name is padded on the right with blanks to a
length of 16 bytes.
* The storage layout of the proc record is as follows:
Word +--------------+-----------+--------------------+
0 | p_proc_id_ | p_lib | p_proc_name |
| type (8 bits)| (8 bits) | (16 bytes) |
+--------------+-----------+--------------------+
1 | p_proc_name (cont.) |
| |
+-----------------------------------------------+
2 | p_proc_name (cont.) |
| |
+-----------------------------------------------+
3 | p_proc_name (cont.) |
| |
+--------------------------+--------------------+
4 | p_proc_name (cont.) | unused |
| | |
+--------------------------+--------------------+
The minimum alignment for this layout is an 8-bit boundary.
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.
If you designate the target CM procedure by means of a plabel, then the
following apply:
* The value of the p_proc_id_type field is 2.
* A p_plabel field designates the plabel.
* The proc record has the following storage layout:
Word +--------------+-----------------+--------------+
0 | p_proc_id_ | p_plabel | unused |
| type (8 bits)| (16 bits) | |
+--------------+-----------------+--------------+
1 | unused |
| |
+-----------------------------------------------+
2 | unused |
| |
+-----------------------------------------------+
3 | unused |
| |
+-----------------------------------------------+
4 | unused |
| |
+-----------------------------------------------+
The minimum alignment for this layout is an 8-bit boundary.
method 32-bit signed integer by value (required)
Value indicating whether the CM target procedure runs in
normal, split-stack, or no copy mode. The valid values
and their meanings follow:
0 Normal (non-split-stack) Method
1 Split-stack Method
2 No-copy Method
NOTE The split-stack method works as follows:
If all parameters are within the CM stack, or the length of the
reference parameters is less than the threshold, then use normal
method. Otherwise, wrap the reference parameters in an extra data
segment if the reference parameters are outside of the CM stack
(split-stack method). The no-copy method is the same as the
split-stack method, except that the threshold check is omitted.
Both the split-stack and the no-copy method require Privileged
Mode.
nparms 32-bit signed integer by value (required)
The number of parameters you are passing to the CM
target procedure.
parms array of records (required)
Passes descriptions of each parameter being passed to
the CM target procedure. Each parameter is located and
described by a record in this array. The fields of the
record are as follows:
pd_parmptr 64-bit address
The NM virtual address of the beginning
of the parameter to be passed.
pd_parmlen 16-bit unsigned integer
The length in bytes of the item that
pd_parmptr points to. Together with
that pointer, pd_parmlen specifies the
data area being described. The
following restriction applies:
1 <= pd_parmlen <= (2**16)
pd_parm_type 16-bit unsigned integer
Provides information needed to determine the kind of
mapping to be performed during the transfer of the
parameter. The allowed mappings are as follows:
0 Value parameter
1 Reference parameter requiring word address
2 Reference parameter requiring byte address
pd_io_type 32-bit signed integer
Applies only to reference parameters and specifies whether such a
parameter is input, output, or both. Switch uses this information to
minimize the amount of data transfer when data must be copied.
Only the two high-order bits in this word are set. Set bit (0:1)=1 to
designate an input parameter. Set bit (1:1)=1 to designate an output
parameter. Good programming practice dictates that you designate a
parameter as being input, output, or both.
The minimum alignment of the parms record is 32-bit word boundary, and
the storage layout of this record is as follows:
Word +-----------------------------------------------+
0 | pd_parmptr |
| (8 bytes) |
+ +
1 | |
| |
+----------------------+------------------------+
2 | pd_parmlen | pd_parm_type |
| (16 bits) | (16 bits) |
+----------------------+------------------------+
3 | pd_io_type |
| (32 bits) |
+-----------------------------------------------+
NOTE The pd_parmptr field is a 64-bit address that is currently
supported only in HP Pascal/XL.
Table 3-1 summarizes, according to MPE XL-supported language, the data
alignments of the common data types.
Table 3-1. Data Alignment By XL Language
---------------------------------------------------------------------------------
| Data Type | HP Pascal/XL | COBOL II/XL | FORTRAN 77/XL |
---------------------------------------------------------------------------------
| 16-bit signed | halfword | halfword | halfword |
| integer (I16) | | | |
| 32-bit signed | word | word | word |
| integer (I32) | | | |
| 64-bit signed | doubleword | doubleword | doubleword |
| integer (I64) | | | |
| 16-bit unsigned | halfword | halfword | halfword |
| integer (U16) | | | |
| 32-bit unsigned | word | word | word |
| integer (U32) | | | |
| 64-bit unsigned | doubleword | doubleword | N/A |
| integer (U64) | | | |
| 32-bit real (R32) | word | N/A | word |
| 64-bit real (R64) | doubleword | N/A | doubleword |
| Boolean (B) | byte | byte | byte |
| Character (C) | byte | byte | byte |
| 32-bit address | word | word | word |
| (@32) | | | |
| 64-bit address | doubleword | doubleword | N/A |
| (@64) | | | |
| Array (A) | Determined by | Determined by | Determined by |
| | element type | element type | element type |
| Record (REC) | Boundary of most | word | word |
| | restrictive | | |
| | element | | |
---------------------------------------------------------------------------------
fretlen 32-bit signed integer by value (optional)
The length in bytes of the optional functional return
value.
The default is 0.
fretval record (optional)
A single-element record containing a 32-bit NM pointer
to the beginning of the area to which the optional
functional return value is returned.
The HP Pascal/XL declaration of this record is as
follows:
LOCALANYPTRREC = RECORD
(rtn_addr: LOCALANYPTR);
END;
The default value of this pointer is nil. If fretval is
omitted, its place in the parameter list is taken by
nil.
condcode 16-bit signed integer by reference (optional)
Returns the condition code that the target CM procedure
returns. Valid values are in the range 0...2.
The default is nil. If condcode is omitted, its place
in the parameter list is taken by nil (32 bits of zero)
and no condition code is returned.
status status-record (optional)
Returns the status of the intrinsic call. If no errors
or warnings are encountered, status returns 32 bits of
zero. If errors or warnings are encountered, status is
interpreted as two 16-bit fields. The HP Pascal/XL
declaration of this record is as follows:
XLSTATUS = RECORD
CASE INTEGER OF
0 : (all : INTEGER);
1 : (info : SHORTINT;
subsys : SHORTINT);
END; {record}
Bits (0:16) comprise status.info. A negative value
indicates an error condition, and a positive value
indicates a warning condition.
Bits (16:16) comprise status.subsys. The value
represented by these bits defines the subsystem that set
the status information. The Switch identification
number is 100.
The values of status.info that can be returned from a call to
HPSWITCHTOCM are listed in Table 3-2.
Table 3-2. HPSWITCHTOCM Status Returns (Page 1)
-----------------------------------------------------------------------------
| Status Code | Meaning |
-----------------------------------------------------------------------------
| -20 | Invalid method parameter value (not in range 0...2) |
| -30 | Parameter bounds violation |
| -40 | Invalid number of parameters |
| -50 | Invalid parameter length |
| -60 | Privileged operation error |
| -80 | Invalid procedure type |
| -90 | Non-extant plabel |
| -110 | CM Switch-by-name table exhausted |
| -120 | Procedure not loaded |
| -130 | Invalid status parameter |
| -150 | Invalid proc address |
| -152 | Invalid parms address |
| -154 | Invalid parameter address |
| -156 | Invalid pd_parm_type value |
| -158 | Invalid parameter I/O specification |
| -160 | Invalid function return length |
| -162 | Invalid function return address |
| -164 | Invalid function return specification |
| -166 | Invalid condition code address |
| -168 | Invalid status address |
-----------------------------------------------------------------------------
Table 3-2. CM Status Returns (Page 2)
-----------------------------------------------------------------------------
| Status Code | Meaning |
-----------------------------------------------------------------------------
| -190 | Invalid proc length |
| -194 | Invalid lib length |
| -200 | Invalid function type |
| -210 | Invalid parameter type |
| -250 | Invalid number of arguments |
| -260 | Invalid process ID |
| -270 | Invalid Switch-to-NM executor |
| -290 | FINDPROC error |
| -300 | Illegal reference parameter alignment (No copy method |
| | where the actual parameter is byte-aligned and the |
| | pd_parm_type = 1, indicating a reference parameter |
| | requiring a word address) |
-----------------------------------------------------------------------------
NOTE Since call by name can result in a call to the LOADPROC intrinsic,
Switch can also return CM Loader errors. See Table 3-3.
CAUTION Since HPSWITCHTOCM can return information on the success of its
execution in the status parameter, it is good programming
practice to specify this parameter and check its value after the
intrinsic call. If an error or warning condition is encountered
and you did not specify the status parameter, HPSWITCHTOCM
causes the calling process to abort.
HPSWITCHTOCM makes the following checks on its parameters:
* If a plabel is used, it is range-checked.
* The number of the target's parameters must be less than or equal to
32 (the maximum number of parameters).
* If the split-stack or no-copy method is used, the caller must be
operating at either execution level one or zero.
* The Switch method must be valid (either 0 for normal, 1 for
split-stack, or 2 for no-copy).
* For each parameter, the pd_parm_type value must be valid (0, 1, or
2), and the pd_parm_len value must be positive and <= 2 ** 16.
Switch relies on the hardware to check for the following:
* Invalid data area
* Target procedure not user-callable (execution level violation)
If you do not specify the status parameter and the switching operation is
successful, the HPSWITCHTOCM intrinsic returns to the calling routine.
However, if an error occurs, HPSWITCHTOCM assumes the caller is HP
Pascal/XL and attempts to escape to the caller's RECOVER block. If there
is no RECOVER block, the program is aborted. Refer to TRY/RECOVER in the
HP Pascal/XL Reference Manual (31502-90001).