1 12/24/82 -- New features of the PL/I Compiler
  2 
  3 This info segment contains information on new PL/I features not documented in
  4 the current PL/I Language Manual AG94-2.  The new features are:
  5 
  6 (1)       wordno builtin function
  7           charno builtin function
  8           bitno builtin function
  9           segno builtin function
 10 (2)       addbitno builtin function
 11           setbitno builtin function
 12           addcharno builtin function
 13           setcharno builtin function
 14           setwordno builtin function
 15           addwordno builtin function
 16 
 17 
 18 New Pointer Manipulation Builtins:
 19 The following paragraphs describe new builtins for manipulating pointers that
 20 effectively replace the char_offset_ family of subroutines. These builtins,
 21 like the subroutines, reflect a model of pointer values that is neither that
 22 of the PL/I standard nor that of the Multics hardware. Users should read the
 23 following section, which describes the model, before using the new facilities.
 24 
 25 
 26 Multics PL/I model of pointers:
 27 In PL/I, a pointer may point to an arbitrary element of a structure or
 28 array. In the case of unaligned quantities, then, a pointer may point to a
 29 location that is not aligned on a 36 bit word boundary.
 30 
 31 
 32 In standard PL/I, no provisions are made for addressing some subportion of a
 33 value. In particular, the only way standard PL/I allows a pointer to point to
 34 a substring of a string is to use a defined string or array to overlay the
 35 desired location.
 36 
 37 
 38 The Multics PL/I pointer manipulation builtins allow the user to consider any
 39 segment to be considered as a vector of either bits, characters, or words,
 40 and to construct pointers that point to arbitrary elements of the vector.
 41 There are three primitive operations: set, add, and extract. Set constructs a
 42 pointer to an arbitrary element of a segment. Add takes a pointer and moves
 43 it some distance up or down in a segment. Extract returns the position of the
 44 pointer in the segment.
 45 
 46 
 47 Note that these are relative to a segment, NOT to some pl1 datum within the
 48 segment. The examples below should make this clear.
 49 
 50 
 51 The setwordno, setcharno, and setbitno builtins:
 52 A reference to one of these builtins takes the form:
 53 
 54     R = setcharno (P, O);
 55 
 56 where P is a scalar pointer value, O is a value convertable to a fixed binary
 57 quantity, and R is a pointer value. The result R is a pointer that points to
 58 char or bit O if the segment specified by P, where the first character is
 59 numbered 0. Note that the offset of P is ignored; an expression like
 60 
 61    declare 1 s aligned,
 62            2 header aligned like p,
 63            2 chars char (12);
 64 
 65      s_ptr = setcharno (addr (s.chars), 4);
 66 
 67 Will NOT result in a pointer to the the 5th character in s.chars. The
 68 expression should be:
 69 
 70    s_ptr = addcharno (addr (s.chars), 4);
 71 
 72 
 73 Builtin functions addwordno, addcharno, and addbitno:
 74 A reference to one of these functions takes the form:
 75 
 76    R = addcharno (P, O);
 77 
 78 Where P is a scalar pointer value, O is convertable to a fixed binary
 79 quantity, and R is a pointer. The result R is the pointer that results when P
 80 is moved O characters, words, or bits. O may be negative. The result of the
 81 addcharno and addwordno functions is undefined if P does not address a
 82 character or word boundary, respectively.
 83 
 84 
 85 The charno, bitno, wordno, and segno functions:
 86 These builtins extract information from pointers, and are defined as follows:
 87 
 88      C = charno (P);
 89 
 90 P must be a scalar pointer value. The result, C, is a real fixed binary of
 91 precision (21, 0), containing the zero origined character address of P.
 92 
 93      B = bitno (P);
 94 
 95 P must be a scalar pointer value. The result, B, is a real fixed binary of
 96 precision (24, 0), containing the zero origined bit address of P.
 97 
 98      W = wordno (P);
 99 
100 P must be a scalar pointer value. The result, W, is a real fixed binary of
101 precision (18, 0), containing the zero origined word address of P.
102 
103      S = segno (P);
104 
105 P must be a scalar pointer value. The result, S, is a real fixed binary of
106 precision (15, 0), containing the segment number of P.