EXTERNAL-POINTER is a pointer Reference that points to a LOCAL ID in a document brought in by IMPORT-DOC in the HEAD.

ItemValue
NameEXTERNAL-POINTER-4WORD (a 5Q bundle. See the member table below for the name of each code)
TAG ID0x02AL~0x02EL
Section1 0001 (Reference EXTERNAL), offset within section C = 10~14
KindReference · category: pointer
Hugo sidereference/external-pointer.md (that page also covers EXTERNAL-POINTER-1WORD and EXTERNAL-POINTER-2WORD)

Members

This page covers one 5Q set, five codes together. The quantification is the offset within the section, C % 5 (Reference). There is one codec document per code. The fields of the five codec documents are the same; only the DECLARE target and the name (BIND) differ.

TAG IDNameQuantificationCodec IDSpec documentTAG WORD
0x02ALEXTERNAL-POINTER-4WORD-IDENTIFIEDIdentified0x000002A00x00000000/codecs/0x000002A0/0000 0010 1010 LLLL
0x02BLEXTERNAL-POINTER-4WORD-GENERICGeneric0x000002B00x00000000/codecs/0x000002B0/0000 0010 1011 LLLL
0x02CLEXTERNAL-POINTER-4WORD-FREE-CHOICEFree-choice0x000002C00x00000000/codecs/0x000002C0/0000 0010 1100 LLLL
0x02DLEXTERNAL-POINTER-4WORD-UNIVERSALUniversal0x000002D00x00000000/codecs/0x000002D0/0000 0010 1101 LLLL
0x02ELEXTERNAL-POINTER-4WORD-VARIABLEVariable0x000002E00x00000000/codecs/0x000002E0/0000 0010 1110 LLLL

Fields (spec document)

The order of FIELDs in the document is the order of Payload fields (Codec spec document).

OrderField (BIND)FIELDWidthAccepted form (CODEC)ENUM
1import-id#2Raw value, 4 WORD
2target-id#3Remaining raw value (0xFFFF)

EXTERNAL-POINTER is a pointer Reference that points to a LOCAL ID in a document brought in by IMPORT-DOC in the HEAD.

Layout

TAG WORD          0000 001C CCCC LLLL      Codec 0x020L~0x02EL (section 1)
[Length extension TAG]
IMPORT ID         width set by the Codec (1/2/4 WORD)
Target ID         all the rest. LOCAL ID of the imported document, shortest width
Codec (Identified, Generic, Free-choice, Universal, Variable)NameIMPORT ID width
0x020L~0x024LEXTERNAL-POINTER-1WORD1 WORD
0x025L~0x029LEXTERNAL-POINTER-2WORD2 WORD
0x02AL~0x02ELEXTERNAL-POINTER-4WORD4 WORD
  • The width is set by the scheme number: if the scheme − 6 (C / 5 of the offset within the section C) is 0, 1, or 2, the width is 1, 2, or 4 WORD. The quantification is C % 5.

  • Use the narrowest Codec that fits the IMPORT ID value.

  • The IMPORT ID is a value assigned by an IMPORT-DOC of this document. No Issuer is written in an EXTERNAL-POINTER. The Issuer and document ID come from that IMPORT-DOC. The version is also set by that IMPORT-DOC (pinned or latest).

  • The same LOCAL ID in the imported document is the same target whether it is written as a LOCAL inside that document or as an EXTERNAL-POINTER here.

  • If Variable, it is a LOCAL variable of the imported document.

Validity

  • It is invalid if this document has no IMPORT-DOC that assigned that IMPORT ID.
  • If the IMPORT ID fits a narrower Codec but a wider Codec is used, it is rejected as non-minimal.
  • A target ID of 0 is invalid. The imported document itself is pointed to by DOC-POINTER.
  • A leading 0x0000 WORD in the target ID is forbidden.

Examples

TargetWORD sequence
LOCAL 5 of IMPORT ID 10202 0001 0005
LOCAL 65536 of IMPORT ID 10203 0001 0001 0000
LOCAL 5 of IMPORT ID 700000253 0001 1170 0005

Related pages

Spec document source

This is the spec document 0x00000000/codecs/0x000002A0/latest.geul as read by geul show (hex in uppercase).

SPEC-VERSION 0x0001
DOC-ID 0x042600000000000002A000000000
BODY
#1 DECLARE 0x02A0
#2 FIELD #1 0x0004
#3 FIELD #1 rest
#4 BIND #1 "EXTERNAL-POINTER-4WORD-IDENTIFIED"
#5 BIND #2 "import-id"
#6 BIND #3 "target-id"

The above is the codec document of EXTERNAL-POINTER-4WORD-IDENTIFIED (0x02AL). The codec documents of the other members (EXTERNAL-POINTER-4WORD-GENERIC, EXTERNAL-POINTER-4WORD-FREE-CHOICE, EXTERNAL-POINTER-4WORD-UNIVERSAL, EXTERNAL-POINTER-4WORD-VARIABLE) differ only in the codec ID of the DOC-ID, the DECLARE target, and the name bound in #1 (BIND).