|
|
|
The flags, opt, data, and
result parameters are common to many NetIPC intrinsics. Remote
Process Management intrinsics also use these parameters, with the exception of
the data parameter. The following discussion of these
parameters may help to clarify the more condensed information given under each
intrinsic.
Flags Parameter
The flags parameter is a bit representation, 32 bits long, of
various options. Normally an option is invoked if the appropriate bit is on
(that is, set equal to 1). Borrowing Pascal-type syntax, we shall use
flags [0] to refer to the high order bit in the parameter,
flags [31] to refer to the low order bit, and a similar
designation to refer to each of the bits in between. Bits which are not
defined for a given intrinsic must be off (zero).
Opt Parameter
The opt parameter, which denotes various options, contains an
integer code for each option along with associated information. It is not
necessary to know the internal structure of this parameter in order to use it.
Several opt parameter manipulation intrinsics have been
provided to enable you to add option information without concerning yourself
with the parameter's structure. However, a knowledge of the structure of the
opt parameter can help you to determine an appropriate size
for the array.
The opt parameter must be defined as a byte array or as a
record structured in the manner described below. If your program is written in
a language which supports dynamically allocated arrays, the
OPTOVERHEAD intrinsic may be used to determine the size of the array.
The opt parameter consists of these fields as shown in
Figure 3-1 "OPT Parameter Structure".
- length, in bytes, of option entries and data (2-byte
integer);
- number of entries (2-byte integer);
- option entries (8 bytes per option entry). Each 8-byte option
entry, in turn, consists of the following fields:
- option code (2-byte integer);
- offset (2-byte integer) byte offset relative to the base
address of the opt parameter indicating the
location of the data for this option entry;
- data length, in bytes(2-byte integer);
- Reserved (2 bytes).
- data associated with the option entries (variable length).
If the parameter is declared as a simple byte array, it must be large enough
to contain 4 bytes for the first two fixed-length fields, 8 bytes for each
option entry, plus the actual data. That is:
4 + 8 * numentries + datalength
 |
NOTE: Use of certain opt parameter options may result
in the loss of portability between different Hewlett-Packard systems.
|
Figure 3-1 OPT Parameter Structure
Figure 3-2 "Option Entry Structure." shows
the structure of an option entry.
Figure 3-2 Option Entry Structure.
Data Parameter
The data parameter is defined as a byte array. It can be in
one of two formats: either holding the actual data or in a vectored format. In
the case of vectored data, the data parameter does not contain
actual data but rather the addresses from or to which the data will be
gathered or distributed.
The addresses of the data are represented by data location descriptors. For
all intrinsics supporting vectored data, a maximum of two data location
descriptors is permitted.
For vectored data, the parameter must be a record structured as described
below. The format of a compatibility mode data location descriptor is
different than a native mode data location descriptor as shown in
Figure 3-3 "Data Location Descriptor —
Vectored Data".
Combining a compatibility mode vector with a native mode vector in the same
NetIPC call is not supported.
Figure 3-3 Data Location Descriptor — Vectored Data
Compatibility Mode
In compatibility mode, the data location descriptor is eight bytes long and
consists of four 2-byte fields. If the vector points to the stack, that is,
type = 0, the value you input into the Data Segment Table (DST) is zero (DST
= 0).
A compatibility mode data location descriptor consists of the following
fields:
- descriptor type (represented by a 2-byte integer); The
compatibility mode descriptor type field can have one of the following
values:
0 — (Stack) the offset is a DB-relative byte address on the
calling process's data stack (the DST is ignored);
1 — (DST Index) DST is the logical index number returned by the
MPE XL HPGETDSEG intrinsic;
2 — (DST Number) DST is an actual data segment number. All data
segment references, that is, calls in split-stack mode, require
privileged mode.
- DST (data segment table) number or index;
- byte offset indicating the start of the data to be transmitted.
(This would be the byte count from DB on the calling process's stack or
segment relative from the extra data segment (XDS)).
- byte length of the vectored data.
Native Mode
In native mode, the data location descriptor is 12-bytes long. It contains two
2-byte fields and a 64-bit native mode address. The DST field is unnecessary
because DSTs do not exist in native mode. The three fields in the native mode
vectored data descriptor are:
- descriptor type (2-byte integer); in this field, only Type = 4
for NM addressing is valid;
- byte length of the data;
- native mode address (64-bits long); this is a long pointer (in
Pascal terminology) to the data.
Example:
nm_address:= globalanyptr(addr(data));
DLEN Parameter
In both compatibility and native mode, the dlen parameter
indicates the full length of the data parameter. If the data
are vectored, dlen must give the total length of each data
location descriptor, not the length of the actual data buffer. For example,
the length of a single or double vectored descriptor would be 8 or 16 bytes
in compatibility mode; and 12 or 24 bytes for native mode.
Result Parameter
If a NetIPC (or Remote Process Management) intrinsic call is successful, the
result parameter returns a value of zero. Otherwise the value
returned represents a NetIPC error code (SOCKERR). NetIPC error
messages are listed in Appendix A "IPC Interpreter
(IPCINT)" of this manual. You can also obtain the corresponding error
message by calling IPCERRMSG.
|
|
NOTE: When nowait I/O is used, the result
parameter is not updated upon completion of an intrinsic. Therefore, the
value of result only indicates whether the call was
successfully initiated. To determine if the call completed successfully, you
can use the IPCCHECK intrinsic immediately afterward.
|
Condition Codes
On an HP 3000, NetIPC intrinsics cause MPE condition codes to be set. CCE
indicates successful completion, CCL indicates failure, and CCG is either not
used or represents a warning.
|
![[OPT Parameter Structure]](img/gfx15.gif)
![[Option Entry Structure.]](img/gfx16.gif)
![[Data Location Descriptor — Vectored
Data]](img/gfx17.gif)
