Copyright © 1993, 1994 by Brian Schenkenberger and TMESIS Consulting All rights reserved. ------------------------- This software is provided "as is" and is supplied for informational purpose only. No warranty is expressed or implied and no liability can be accepted for any actions or circumstances incurred from the use of this software or from the information contained herein. The author makes no claim as to the suitability or fitness of this software or information contain herein for a particular purpose. ------------------------- This software may be copied and distributed only with the inclusion of this copyright notice. ------------------------------------------------------------------------- * * * S Y M B O L * * * ------------------------- Description: ----------- SYMBOL provides the capability to define, display and delete DCL symbols in the context of any process in a VMScluster. When installed, SYMBOL can be used by any user in the VMScluster to define, display, or delete symbols in its own symbol table or in the symbol table of any process in the VMScluster. Privileges are required to affect any process which the user does not own or have rights to access. SYMBOL displays the symbol table's contents using the same output format as the OpenVMS DCL command '$ SHOW SYMBOL'. A single equal sign '=' is used to denote LOCAL symbols and, the double equal sign '==' is used for denoting GLOBAL symbols. Binary symbols are formatted with the familiar decimal, hexadecimal and octal presentation. SYMBOL can be a valuable utility for both the system manager and the DCL programmer. Using SYMBOL, the system manager can easily modify and view a user's DCL environment. Developers of DCL command procedures can use SYMBOL as a DCL debugging utility which provides the ability to observe both the symbol, by name, and its equivalence string while the procedure is executing in a process. ------------------------------------------------------------------------- Release Information: ------------------- This is an updated SYMBOL package. (v3.4%062) This release of SYMBOL represents a significant reworking of the original SYMBOL package. The major goal for this release was to provide SYMBOL on OpenVMS AXP and maintain a similar and/or common code base for both Alpha and VAX platforms. The crux of this effort involved redesigning the code to provide a mechanism whereby the target AST routines would functions on the OpenVMS AXP platform. Due to the number of differences between Alpha and VAX environments such as: support for position-independent-code(PIC); assembled code verses compiled code; and the need to relocate and 'fixup' the code and linkage on Alpha; the AST routines were placed in a Loadable Executive Image (LEI), a supported mechanism for loading code into system space on both OpenVMS AXP and OpenVMS VAX. The migration of the AST code to a LEI provides a common code base for both platforms. Only a minimal number of conditional statements will be found in SYMBOL -- Most of them, a consequence of system routine name changes (ie. EXE$EPID_TO_PCB is now called EXE$CVT_EPID_TO_PCB), promotion of a system data field to aligned londwords or quadwords (ie. EXE$GL_BASIMGMTX was promoted from a longword to a quadword and is now referred to as EXE$GQ_BASIMGMTX on Alpha) or, as a consequence of MACRO32 requirements on Alpha such as, required compiler directives like .JSB_ENTRY. There are, however, two fundamental environment differences which require the use of platform biased conditional statements. The first is related to the LEI. The INITIALIZATION_CODE section of the LEI is JSBed to on the VAX and CALLed on the Alpha. On VAX, addresses of the LDRIMG block and the LDRIMG$L_FLAGS are passed to the INITIALIZATION routine via registers R4 and R5, respectfully. On Alpha, they are passed as arguments to the routine at 4(AP) and 8(AP), respectfully. Since the INITIALIZATION code is invoked differently on each platform, conditional statements determine whether to RSB or RET to the caller. A second is directly related to fundamental architecture differences. To provided access to the DCL dispatcher on the VAX, the code could simply JuMP around an access mode check and into the dispatcher. On the Alpha, this ability to JuMP into a code thread is thwarted by the fact that the routine is responsible for its own stack maintenance. JuMPing into code on the Alpha would mean reproducing prologue code and updating registers which maintain the address of the linkage section and the current frame. This problem occurs in the SUPERVISOR_AST routine in SYMBOL$AST_LEI.MAR. The comment section of SYMBOL$AST_LEI.MAR outlines how this problem was dealt with in greater detail. This release incorporates a number of new features: -------------------------------------------------- o SYMBOL is now supported on OpenVMS VAX and OpenVMS AXP platforms. o The AST routines, the crux of SYMBOL's functionality, have been put into a Loadable Executive Image(LEI) called SYMBOL$AST_LEI.EXE. It is located in the system directory SYS$LOADABLE_IMAGES:. This LEI is loaded into system space using the INSTALL_SYMBOL.COM proceedure. This change was necessary for the Alpha OpenVMS AXP support. To make SYMBOL as compatible as possible on both platforms, the OpenVMS VAX version of SYMBOL also uses the LEI. o SYMBOL can now be used to display, define and delete DCL symbols in processes on any active node in a VMScluster. This functionality is provided by the same shareable library routines which provide remote command capabilities (ie. DO) in the SYSMAN utility. This requires the TMPMBX privilege and access privileges to the remote node. (ie. login capability on the remote node.) o A new command qualifier /BINARY provides the capability for defining binary (integer) symbols. Previous releases of SYMBOL provided only string definition. o The /IDENTIFICATION qualifier is now optional. If the qualifier is omitted or the PID is specified as zero (0), SYMBOL will default to the current process. o New process privilege checks. SYMBOL may now be installed with the CMKRNL privilege so that all users can utilize the command. Users without GROUP and WORLD privilege can affect only their processes. Users with GROUP can affect processes within their own group. WORLD privilege is required to affect processes in multiple groups. TMPMBX, with addition of GROUP or WORLD privilege, is required to affect processes on a remote VMScluster node. Privilege checks are performed in both, the local and the target processes. o Enhanced error reporting. Both /SET and /DELETE will report errors to the process executing the SYMBOL command. SYMBOL has been coded to reflect and report the errors in a similar fashion to those which would normally occur with DCL symbol operations. o Errors reported by SYMBOL are now formatted to reflect SYMBOL in the error message. (ie. %SYMBOL-F-NOGROUP, operation requires GROUP privilege) o The symbol name is now checked by SYMBOL to insure that is conforms with the accepted rules for formulating symbol names. o The symbol name is now checked to insure that it exists prior to the delete callback. If the symbol does not exists, an error is returned. o The symbol name is also checked to insure that it does not conflict with any abbreviated symbol prior to the define symbol callback. If a symbol conflicts with one already defined in an abbreviated context, an error is returned. o SYMBOL may be activated from a foreign command symbol definition. A new executable, included with this release, will allow this symbol definition to be defined as a permanent definition. Thus, it can not be inadvertently deleted from the process's symbol table. o A SYMBOL.CLD file is provided to allow SYMBOL to be defined as a DCL verb instead of invoking SYMBOL via a foreign command definition. o A bug-fix which corrects the improper display of binary symbols. o A bug-fix which corrects the improper display of abbreviated symbols. * (V2%4-012) New functionality now places the SUPERVISOR mode code into the per-process user "core-common" area of the process P1 space. The Module PROCESS_PAGE_DEFINITIONS defines two areas referred to as the DEC "CORE COMMON" PAGES and USER "CORE COMMON" PAGES. The following is an excerpt from PROCESS_PAGE_DEFINITIONS. | COMMON = 4 | ... | P1PTE COMMON,UW,K,DZRO ; DEC "CORE COMMON" PAGES |DEFINE_CONSTANT CTL$A_COMMON,VA..., ; BASE ADDRESS | P1PTE COMMON,UW,K,DZRO ; USER "CORE COMMON" PAGES | ... This change should avoid problems with programs which call run-time library routines LIB$PUT_COMMON and LIB$GET_COMMON or programs that are written in BASIC which use the CHAIN statement. (This common region "duality" also exists on Alpha OpenVMS AXP.) ------------------------------------------------------------------------- Acknowledgements: ---------------- Special thanks goes to... Eric M. LaFranchi for suggesting that I add the /SHOW capability to the original SYMBOL release and for pointing out that there are two per-process common regions maintained of P1 space. (ref: PROCESS_PAGE_DEFINITIONS) Hunter Goatley for suggesting that I make SYMBOL a foreign command and for his insistance and assistance which made the Alpha OpenVMS AXP port a reality... Jon Pinkley for his many suggestions and comments on a previous SYMBOL release including his suggestion that I add the privilege checks for GROUP and WORLD privileges to allow SYMBOL to be installed... and... my source code listings and micro-fiche. ------------------------------------------------------------------------- Any feedback on SYMBOL will be appreciated. Send comments or suggestions to: brians@advsyscon.com or Schenkenberg@Eisner.DECUS.Org. ------------------------------------------------------------------------- Distribution Information: ------------------------ SYMBOL requires CMKRNL privilege and executes code at kernel mode access. Therefore, SYMBOL is distributed in source form for inspection. *** This package contains the following files: ----------------------------------------- $$$SYMBOL.INFORMATION .. This file. Backgroung and release information. $$$SYMBOL.INSTALLATION . Information on installing and using SYMBOL. BUILD_SYMBOL.COM ... Compile and link the sources. Create .HLP source file. INSTALL_SYMBOL.COM . Simple command file to install SYMBOL during startup. SYMBOL.RNH ......... Digital Standard Runoff(DSR) source for .HLP file. SYMBOL.CLD ......... SYMBOL command definition (to add SYMBOL to DCLTABLES) SYMCLITBL.CLD ...... SYMBOL command definition (for internal command parsing) SYMBOL.MAR ......... The SYMBOL command parser and dispatcher. SYMCLUSTER.MAR ..... Source for SYMBOL VMScluster support. SYMDELSETB.MAR ..... Source for SYMBOL /SET, /BINARY and /DELETE functions. SYMDISPLAY.MAR ..... Source for SYMBOL /SHOW function. SYMFINDLEI.MAR ..... Source for SYMBOL$AST_LEI locator. SYMBOL$AST_LEI.MAR . Source for SYMBOL$AST_LEI Loadable Executive Image. SYMLOADER.MAR ...... Source for dynamic SYMBOL$AST_LEI.EXE loading. SYMLOADER.MAR ...... Source for dynamic SYMBOL$AST_LEI.EXE unloading. SYMBOLPERM.MAR ..... Source for permanent definition of SYMBOL. *** BUILD_SYMBOL.COM will create the following files: ----------------------------------------- SYMBOL.HLB ......... OpenVMS help library file for SYMBOL. SYMBOL.HLP ......... OpenVMS help library source file for SYMBOL. SYMBOL.LIS ......... OpenVMS VAX & AXP listing file from SYMBOL.MAR. SYMCLUSTER.LIS ..... OpenVMS VAX & AXP listing file from SYMCLUSTER.MAR. SYMDELSETB.LIS ..... OpenVMS VAX & AXP listing file from SYMDELSETB.MAR. SYMDISPLAY.LIS ..... OpenVMS VAX & AXP listing file from SYMDISPLAY.MAR. SYMFINDLEI.LIS ..... OpenVMS VAX & AXP listing file from SYMFINDLEI.MAR. SYMBOL$AST_LEI.LIS . OpenVMS VAX & AXP listing file from SYMBOL$AST_LEI.MAR. SYMLOADER.LIS ...... OpenVMS VAX & AXP listing file from SYMLOADER.MAR. SYMUNLOAD.LIS ...... OpenVMS VAX & AXP listing file from SYMUNLOAD.MAR. SYMBOLPERM.LIS ..... OpenVMS VAX & AXP listing file from SYMBOLPERM.MAR. SYMBOL.OBJ ......... OpenVMS VAX & AXP object file from SYMBOL.MAR. SYMCLITBL.OBJ ...... OpenVMS VAX & AXP object file from SYMCLITBL.CLD. SYMCLUSTER.OBJ ..... OpenVMS VAX & AXP object file from SYMCLUSTER.MAR. SYMDELSETB.OBJ ..... OpenVMS VAX & AXP object file from SYMDELSETB.MAR. SYMDISPLAY.OBJ ..... OpenVMS VAX & AXP object file from SYMDISPLAY.MAR. SYMFINDLEI.OBJ ..... OpenVMS VAX & AXP object file from SYMFINDLEI.MAR. SYMBOL$AST_LEI.OBJ . OpenVMS VAX & AXP object file from SYMBOL$AST_LEI.MAR. SYMLOADER.OBJ ...... OpenVMS VAX & AXP object file from SYMLOADER.MAR. SYMUNLOAD.OBJ ...... OpenVMS VAX & AXP object file from SYMUNLOAD.MAR. SYMBOLPERM.OBJ ..... OpenVMS VAX & AXP object file from SYMBOLPERM.MAR. SYMBOL.EXE ......... OpenVMS VAX & AXP executable file for SYMBOL. SYMBOL.MAP ......... OpenVMS VAX & AXP linker map file for SYMBOL. SYMBOL$AST_LEI.EXE . OpenVMS VAX & AXP Loadable Executive Image for SYMBOL. SYMBOL$AST_LEI.MAP . OpenVMS VAX & AXP linker map file for SYMBOL$AST_LEI. SYMBOL$AST_LEI.STB . OpenVMS VAX & AXP symbol table file for SYMBOL$AST_LEI. SYMLOADER.EXE ...... OpenVMS VAX & AXP executable file for SYMLOADER. SYMLOADER.MAP ...... OpenVMS VAX & AXP linker map file for SYMLOADER. SYMUNLOAD.EXE ...... OpenVMS VAX & AXP executable file for SYMUNLOAD. SYMUNLOAD.MAP ...... OpenVMS VAX & AXP linker map file for SYMUNLOAD. SYMBOLPERM.EXE ..... OpenVMS VAX&AXP executable file for SYMBOLPERM. SYMBOLPERM.MAP ..... OpenVMS VAX&AXP linker map file for SYMBOLPERM. ----- .END.