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.