HP 3000 Manuals HP 3000 Manuals
Common Parameters
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.
* 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).
Figure 3-2 shows the structure of an option entry.
* 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.
![[FIG31]](../../pic3k/M010427/FIG31.gif)
Figure 3-1. OPT Parameter Structure.
![[FIG32]](../../pic3k/M010427/FIG32.gif)
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.
Combining a compatibility mode vector with a native mode vector in the
same NetIPC call is not supported.
![[FIG33]](../../pic3k/M010427/FIG33.gif)
Figure 3-3. Data Location Descriptors--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 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.