YggRep.mesa
Copyright Ó 1988 by Xerox Corporation. All rights reserved.
Bob Hagmann May 26, 1988 3:56:14 pm PDT
This interface defines the representation of objects, both in stable and volatile forms
DIRECTORY
Basics USING [charsPerWord, UnsafeBlock],
BasicTime USING [GMT],
Rope USING [ROPE],
YggDID USING [DID],
YggFile USING [FileHandle],
YggEnvironment USING [AccessRights, LockOption, TransID];
YggRep: CEDAR DEFINITIONS
~ BEGIN
ROPE: TYPE ~ Rope.ROPE;
Volatile object representation
TypedPrimitiveElement: TYPE ~ RECORD [docType: DocType, bits: Bits];
Basic elemental object part, with its type.
DocType: TYPE ~ CARD;
Type of the primitive element.
Reserved document types are 0-65535. Here are some well known types.
unknown: CARD = 0; -- place holder during various operations; never should be seen by clients
int: CARD = 1; -- 32 bit integers
rope: CARD = 2; -- (long null containing) strings
shortRope: CARD = 3; -- strings that are short and null terminated
float: CARD = 4; -- 32 bit floating point
date: CARD = 5; -- GMT date
uninterpretedBytes: CARD = 6; -- (long) byte sequences
lastReservedDocType: CARD = 1023; -- all of types up to and including this one are reserved by the system
Bits: TYPE ~ REF; -- For well known types, Bits is a REF to an INT32, ROPE, REAL32, or YggRep.AccurateGMT. Otherwise it is a REF BitsRep.
BitsRep: TYPE ~ RECORD [
validBytes: CARD,
b: PACKED SEQUENCE length: CARD OF BYTE
];
Uninterpreted bytes of a small object.
BytesFromBits: PROC [bits: Bits, startByte: CARD, block: Basics.UnsafeBlock];
Fetch some bytes from an "uninterpreted bytes" object.
SizeOfBits: PROC [bits: Bits] RETURNS [size: CARD];
Size in bytes of an "uninterpreted bytes" object.
SetSizeOfBits: PROC [bits: Bits, size: CARD] RETURNS [newRef: BOOL, newBits: Bits];
Set the size in bytes of an "uninterpreted bytes" object. If this grows the object, the new bytes are uninitalized. This may grow the object and change its representation. All callers must look at the newRef and newBits return values. If newRef is TRUE, then the old bits object is no longer valid. The caller is responsible for updating the data structure from which it obtained the bits.
BytesToBits: PROC [bits: Bits, startByte: CARD, block: Basics.UnsafeBlock] RETURNS [newRef: BOOL, newBits: Bits];
Store some bytes into an uninterpreted bytes" object. This may grow the object and change its representation. All callers must look at the newRef and newBits return values. If newRef is TRUE, then the old bits object is no longer valid. The caller is responsible for updating the data structure from which it obtained the bits.
AccurateGMT: TYPE ~ REF AccurateGMTRep;
AccurateGMTRep: TYPE ~ RECORD [
gmt: BasicTime.GMT, -- 1968 to 2036 (231 seconds)
usecs: INT32
];
AccurateGMTRepByteSize: INT = WORDS[AccurateGMTRep] * Basics.charsPerWord;
VDoc: TYPE ~ REF VDocRep;
VDocRep: TYPE ~ RECORD [
did: YggDID.DID, -- document identifier for the document
contents: TypedPrimitiveElement ← [unknown, NIL],
attributes: LIST OF Attribute ← NIL -- the attributes of the document
];
the volatile representation of an object
Attribute: TYPE ~ RECORD [
attributeName: ROPE, -- name of the attribute (not unique for a given document)
ordered: BOOL, -- whether the the valueSet is ordered
value: LIST OF AttributeValue -- set of values for attribute
];
An attribute for an object.
AttributeValue: TYPE ~ RECORD [
fieldName: ROPE, -- name of the attribute (not unique for a given document)
valueSet: LIST OF TypedPrimitiveElement -- set of values for field
];
An attribute for an object.
VolatizeFromDID: PROC [transID: YggEnvironment.TransID, did: YggDID.DID, access: YggEnvironment.AccessRights ← readOnly, lock: YggEnvironment.LockOption ← [intendRead, wait]] RETURNS [document: VDoc];
Given a DID, return the volatile form of the document it refers to.
StabilizeToFiles: PROC [transID: YggEnvironment.TransID, did: YggDID.DID, document: VDoc, contents, attributes, links: YggFile.FileHandle];
Given a document, write it out to the files.
Attribute coding
Attributes are written to a stream by following this algorithm.
Write the type of the contents.
Do for all attributes:
Write a preamble byte.
bit meaning
0 0 = ordered
1 0 = no field names
2 0 = singleton attribute value (i. e., there is only one field)
3 0 = singleton field value(s) (i. e., every field has only one value)
4-6 code for type of data
 0 - each one is separate
 1 - integer (32 bit)
 2 - rope (may be large and contain nulls)
 3 - rope (shorter and null terminated)
 4 - float (32 bit)
 5 - date (GMT)
 6 - uninterpreted bytes
 7 - to be defined
7 to be defined
Write the attribute name. It starts at byte 1, fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
If there isn't a singleton attribute value, then write the number of attributes in a word.
For each attribute:
If there isn't a singleton field value, then write the number of fields in a word.
For each field:
If there is a field name, or the field name is NIL but no field names is not set, then write the field name. It starts at byte 0, fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
For each field value:
If the code for type of data is each one is seperate, then write the type word.
Write the type value:
integers take a 32 bit word
rope (may be large and contain nulls) is preceeded by a size word
rope (shorter and null terminated) fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
floats take a 32 bit word
dates takes a 32 bit word
everything else is bits: write a 32 bit size field and the bits, null fill if necessary
charsPerWord: CARD ~ BITS[WORD]/8;
AttributePreamble: TYPE ~ PACKED ARRAY [0..charsPerWord) OF AttributePreambleByte;
use this to generate a pointer to a AttributePreambleByte; { apb: AttributePreambleByte; ... @apb ... } is wrong!
AttributePreambleByte: TYPE ~ MACHINE DEPENDENT RECORD [
ordered (0:0..0): BOOL ← FALSE, -- true if the attribute values are ordered
noFieldNames (0:1..1): BOOL ← FALSE, -- true if there are no field names
singletonAttribute (0:2..2): BOOL ← FALSE, -- true if there is only one field in the attribute
singletonField (0:3..3): BOOL ← FALSE, -- true if there is only one value in each of the fields
typeCode (0:4..6): AttributePreambleType ← separate, -- code for type of data
spare (0:7..7): BOOL ← FALSE
];
Preamble byte for each attribute.
AttributePreambleType: TYPE ~ MACHINE DEPENDENT { separate (0), integer (1), ropeLarge (2), ropeShort (3), float (4), date (5), uninterpretedBytes (6), spare2 (7)};
Information about the attribute.
END.