The Internals of Logical Names David Schwab Demax Software San Mateo, CA VA061 Friday, 10 May 1991 Room 364-6 ----------------------------------------------------------------------------- Overview o Logical Name Translation Block (LNMX) o Logical Name Block (LNMB) o Logical Name Table Header (LNMTH) o Logical Name Hash Tables (LNMHSH) o Logical Name Cache Blocks (LNMC) o Synchronization o Sample Program ------------------------------------------------------------------------------ LNMX o Logical Name Translation Block (LNMX) holds information about a single equivalence name o Contained as part of LNMB (forward) o Offsets found in module $LNMSTRDEF in LIB.MLB. ------------------------------------------------------------------------------- LNMX Structure ------------------------------------------------------------ | LNMX$W_HASH | LNMX$B_INDEX | LNMX$B_FLAGS | ------------------------------------------------------------ | LNMX$T_XLATION | | | | | | | ------------------------------------------------------------ ------------------------------------------------------------------------------- LNMX Fields o LNMX$B_FLAGS - flags for equivalence name attributes LNMX$V_CONCEALED LNMX$V_TERMINAL LNMX$V_XEND - a marker for the last LNMX in a LNMB. In this case the rest of the LNMX is not present. o LNMX$B_INDEX - equivalence name index. Indices 0-127 available for users. -1 to -128 reserved for system use. -126 indicates that the equivalence string is a logical name table header. -127 indicates that the equivalence string is a back pointer, the address of another data structure (the UCB of a mailbox, connecting the mailbox logical name to the mailbox, or connecting the LNMB to a mounted volume list entry). o LNMX$W_HASH - the result of hashing the logical name (only for table names). o LNMX$T_XLATION - the equivalence name as a counted string ------------------------------------------------------------------------------- LNMB o Each defined logical name is described by a Logical Name Block (LNMB) o A LNMB contains one or more LNMX o LNMBs are always an integral number of quadwords in length o Process-private LNMBs are allocated in P1 space. Shareable LNMBs are allocated from paged pool. o Offsets found in module $LNMSTRDEF in LIB.MLB ------------------------------------------------------------------------------- LNMB Structure ------------------------------------------------------------ | LNMB$L_FLINK | ------------------------------------------------------------ | LNMB$L_BLINK | ------------------------------------------------------------ |LNMB$B_ACMODE | LNMB$B_TYPE | LNMB$W_SIZE | ------------------------------------------------------------ | LNMB$L_TABLE | ------------------------------------------------------------ | LNMB$T_NAME |LNMB$B_FLAGS | | | | | ------------------------------------------------------------ | | | LNMX for first equivalence name | | | ------------------------------------------------------------ | | / / / / | | ------------------------------------------------------------ | | | LNMX for last equivalence name | | | ------------------------------------------------------------ | 4 | --------------- Note: The ending byte of 4 is a LNMX with only the flags field present, bit LNMX$V_XEND turned on. ------------------------------------------------------------------------------- LNMB Fields o LNMB$L_FLINK - hash chain forward link o LNMB$L_BLINK - hash chain back link o LNMB$W_SIZE - size of the LNMB, including all LNMXs o LNMB$B_TYPE - marks the structure as a LNMB (DYN$C_LNM = 64) o LNMB$B_ACMODE - access mode of the logical name o LNMB$L_TABLE - address of the header of the containing logical name table o LNMB$B_FLAGS - logical name attributes LNMB$M_NO_ALIAS - no outer mode logicals allowed LNMB$M_CONFINE - do not propagate to spawned subprocesses LNMB$M_CRELOG - defined through superseded $CRELOG service LNMB$M_TABLE - logical name is the name of a logical name table LNMB$M_NODELETE - prevents deletion of a directory table name o LNMB$T_NAME - the logical name as a counted string ------------------------------------------------------------------------------- LNMTH o A Logical Name Table Header (LNMTH) describes a logical name table. o A LNMTH is contained in a LNMB as the first LNMX. The LNMX has index -126 to show it contains a LNMTH rather than an equivalence name. ------------------------------------------------------------------------------- LNMTH Structure ---------------- |LNMTH$B_FLAGS | ------------------------------------------------------------ | LNMTH$L_HASH | ------------------------------------------------------------ | LNMTH$L_ORB | ------------------------------------------------------------ | LNMTH$L_NAME | ------------------------------------------------------------ | LNMTH$L_PARENT | ------------------------------------------------------------ | LNMTH$L_CHILD | ------------------------------------------------------------ | LNMTH$L_SIBLING | ------------------------------------------------------------ | LNMTH$L_QTABLE | ------------------------------------------------------------ | LNMTH$L_BYTESLM | ------------------------------------------------------------ | LNMTH$L_BYTES | ------------------------------------------------------------ ------------------------------------------------------------------------------- LNMTH Fields o LNMTH$B_FLAGS - table flags LNMTH$V_SHAREABLE LNMTH$V_DIRECTORY LNMTH$V_GROUP LNMTH$V_SYSTEM o LNMTH$L_HASH - address of either the shareable hash table or the process-private hash table (forward) o LNMTH$L_ORB - For shareable tables only, the address of an object rights block (ORB) associated with the table (UIC and ACL protection) o LNMTH$L_NAME - address of the beginning of the LNMB that contains this header. o LNMTH$L_PARENT \ These contain addresses of other LNMTHs and link o LNMTH$L_CHILD > logical names into a quota and access hierarchy o LNMTH$L_SIBLING / of singly linked lists. o LNMTH$L_QTABLE - address of the LNMTH of the table's quota holder table. For a table with limited quota, this is self-referential. Otherwise, it points to some ancestor. o LNMTH$L_BYTESLM - the quota for a table with limited or infinite quota (the largest possible positive integer for infinite quota). Not used for tables with pooled quotas. o LNMTH$L_BYTES - bytes of quota remaining. Not used for tables with pooled quota. ------------------------------------------------------------------------------- LNMHSH o Each process has a logical name hash table to locate process-private logical names. There is a single system-wide hash table for shareable logical names. o Entries in the hash table are 0 or a pointer to a linked list of LNMBs with the same hash value (linked on the LNMB$L_FLINK and LNMB$L_BLINK fields). o The order of LNMBs in a hash list is as follows: - Shorter names precede longer names - For names with the same length, ASCII ordering is used - For identical names, they are ordered on the address of the containing table (LNMB$L_TABLE) - For identical names in the same table, they are ordered on access mode (outermost first). o The SYSGEN parameter LNMPHASHTBL specifies the number of longword entries in process-private hash tables. The parameter LNMSHASHTBL is similarly used for the system-wide hash table. (Both are 128 by default.) o The first longword at global location LNM$AL_HASHTBL points to a longword containing the address of the shareable table. The second longword at this location contains the address of CTL$GL_LNMHASH (in P1 space) which contains a pointer to the process-private hash table. o The hash algorithm is as follows: a) Start with the size of the logical name in a longword. b) While there are more than 4 bytes remaining in the name: i) Convert the next 4 bytes to an upper case longword ii) XOR this into the hash value computed so far iii) Rotate the new value 9 bits left c) For each remaining byte, if any, XOR it into the hash value and rotate the result 13 bits left. d) Multiply by 71279461 (hex) e) Mask out the high bits specified by LNMHSH$L_MASK to obtain a number no larger than the number of entries in the hash table - 1. The hash value for the logical name is stored in LNMX$W_HASH ------------------------------------------------------------------------------- LNMHSH Structure ------------------------------------------------------------ | LNMHSH$L_MASK | ------------------------------------------------------------ | (unused) | ------------------------------------------------------------ | (unused) |LNMHSH$B_TYPE | LNMHSH$W_SIZE | ------------------------------------------------------------ | | | LNMPHASHTBL | | or | | LNMSHASHTBL | | longword | | entries | | | | | | | | | ------------------------------------------------------------ ------------------------------------------------------------------------------- LNMHSH Fields o LNMHSH$L_MASK - mask used to clear a certain number of high bits at the end of the hash algorithm. Related to the number of entries in the hash table. o LNMHSH$W_SIZE - the total size of the hash table o LNMHSH$B_TYPE - marks this structure as a logical name hash table (DYN$C_WQE = 38) ------------------------------------------------------------------------------- LNMC o Logical Name Cache Blocks (LNMCs) are used to speed up logical name table name translation. o LNMC records the result of a particular table name translation. o Contains the LNMB of the table name and up to 25 LNMTHs obtained from translating that name. A table name that resolves to more than 25 table headers cannot be cached. o May contain valid but incomplete data because a logical name translation was found before all tables were searched. If the cache block is complete, the valid entries are followed by a -1 longword. o LNMCs are process-private. o Each LNMC is 128 bytes and there are (LNMPHASHTBL * 8)/128 of them (8 by default). o LNMCs are in a double linked list, with list head at CTL$GQ_LNMTBLCACHE. ------------------------------------------------------------------------------ LNMC Structure -------------------------------------------------------------------- | LNMC$L_FLINK | -------------------------------------------------------------------- | LNMC$L_BLINK | -------------------------------------------------------------------- |LNMC$B_CACHEINDX| LNMC$B_TYPE | LNMC$W_SIZE | -------------------------------------------------------------------- | LNMC$L_TBLADDR | -------------------------------------------------------------------- | LNMC$L_PROCDIRSEQ | -------------------------------------------------------------------- | LNMC$L_SYSDIRSEQ | -------------------------------------------------------------------- | LNMC$L_ENTRY (address of LNMTH) | -------------------------------------------------------------------- | (Room for 24 more LNMTH addresses) | | | | | | | | | | | -------------------------------------------------------------------- | 0 | -------------------------------------------------------------------- ------------------------------------------------------------------------------ LNMC Fields o LNMC$L_FLINK - forward link o LNMC$L_BLINK - backward link o LNMC$W_SIZE - total size of the LNMC (fixed) o LNMC$B_TYPE - marks structure as a LNMC (Not used - 0) o LNMC$B_CACHEINDX - index of the entry most recently entered or examined. o LNMC$L_TBLADDR - address of the LNMB of the table name for which this is a translation cache. o LNMC$L_PROCDIRSEQ - The current value of CTL$GL_LNMDIRSEQ when the LNMC was created. o LNMC$L_SYSDIRSEQ - The current value of LNM$GL_SYSDIRSEQ when the LNMC was created. If either this or the last field differ from the current values when trying to use the cache, then the cache may be invalid and cannot be used. o LNMC$L_ENTRY - The first LNMTH in the cache list. ------------------------------------------------------------------------------- Synchronization o Mutex LNM$AL_MUTEX is used for synchronization to the shareable logical name database. o Muliple users may lock the mutex for read access (i.e. translation). o Only one user at a time may lock the mutex for write access (i.e. definition or deletion). ------------------------------------------------------------------------------- For Further Information o Chapter 28 of the VMS 4.4 Internals and Data Structures book. (not completely up to date at this point) o Chapter 35 of the VMS 5 Internals and Data Structures book (Vol 3). o LNMSUB.LIS and SYSLNM.LIS in the SYS directory of the VMS listings.