.__________________________________________________________. |__. .___________________________________________________| | | | _______| _______| | _______| | | | | | _______|_______ | |_______ | |___|___|___|___|___________|___________|___|___________| ----------------------------- - TMESIS SYMBOL (tm) V4.0 - - Product Guide - ----------------------------- - Installation Instructions - - Product Usage Information - - Maintenance/Release Notes - ----------------------------- © 1997 TMESIS Software Jackson, NJ 08527-2320 prepared by: Brian Schenkenberger 24 May 1997 TMESIS SYMBOL (tm) V4.0 Product Guide Page 2 24 May 1997 Copyright © 1993, 1994, 1996, 1997 Brian Schenkenberger and TMESIS. ALL RIGHTS RESERVED. Notice of Disclaimer -------------------- 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 direct, indirect or consequential damages or for any damage whatsoever resulting in the loss of systems, data or profit from the use of this software or from any of the information contained herein. The author makes no claims as to the suitablility or fitness of this Software or information contain herein for any particular purpose. Redistribution or Copying ------------------------- Permission is hereby granted *ONLY* for the "not-for-profit" redistribution of this software provided that ALL SOURCE and/or OBJECT CODE remains intact and ALL COPYRIGHT NOTICES and NOTICES OF DISCLAIMER remain intact from its original distribution. Distribution audience restrictions exist and are outlined under a separate document and must be displayed prior to the installation of this software. A fee may be levied for the media upon which the software is redistributed provided that the fee charged is for the media and the production costs of the media and that the cost associated is clearly stated. Execution of the Software ------------------------- Any proper copy of this Software obtained within the guidelines expressed in the section above entitiled, "Redistribution or Copying" may be used on any CPU so desired by the proper recipient of the copy. Title and Ownership ------------------- NO TITLE TO AND/OR OWNERSHIP OF THIS SOFTWARE IS HEREBY TRANSFERRED. ANY MODIFICATION WITHOUT THE PRIOR WRITTEN CONSENT OF THE COPYRIGHT HOLDER IS PROHIBITED. TMESIS SYMBOL (tm) V4.0 Product Guide Page 3 24 May 1997 CONTENTS CHAPTER 1 PRODUCT OVERVIEW 1.1 Brief Product Overview . . . . . . . . . . . . . . 1-1 1.1.1 User Interface . . . . . . . . . . . . . . . . . 1-1 1.1.2 Beyond DCL . . . . . . . . . . . . . . . . . . . 1-2 1.1.3 Installation . . . . . . . . . . . . . . . . . . 1-2 CHAPTER 2 PRODUCT INSTALLATION 2.1 SYMBOL Installation . . . . . . . . . . . . . . . 2-1 2.1.1 SYMBOL Placement . . . . . . . . . . . . . . . . 2-1 2.1.2 SYMBOL$AST_LEI Placement . . . . . . . . . . . . 2-1 2.1.3 OpenVMS Version Support . . . . . . . . . . . . 2-2 CHAPTER 3 PRODUCT ENVIRONMENT 3.1 SYMBOL Environment . . . . . . . . . . . . . . . . 3-1 3.1.1 Starting SYMBOL . . . . . . . . . . . . . . . . 3-1 3.1.1.1 VMScluster Operation . . . . . . . . . . . . . 3-1 3.1.1.2 SYMBOL Startup Activities . . . . . . . . . . 3-2 3.1.2 Defining the SYMBOL Command . . . . . . . . . . 3-2 3.1.3 SYMBOL as a Foreign Command . . . . . . . . . . 3-2 3.1.3.1 SYMBOL as a DCL Command . . . . . . . . . . . 3-3 3.1.3.2 SYMBOL in DCLTABLES.EXE . . . . . . . . . . . 3-3 CHAPTER 4 PRODUCT FEATURES 4.1 SYMBOL Features . . . . . . . . . . . . . . . . . 4-1 4.1.1 Utility and Orthogonality . . . . . . . . . . . 4-1 4.1.2 VMScluster Support . . . . . . . . . . . . . . . 4-2 4.1.3 Sub-Procedural Level Support . . . . . . . . . . 4-2 4.1.4 Access and Security . . . . . . . . . . . . . . 4-2 4.1.5 Supported Environments . . . . . . . . . . . . . 4-2 CHAPTER 5 PRODUCT UTILIZATION 5.1 SYMBOL Use . . . . . . . . . . . . . . . . . . . . 5-1 5.1.1 SYMBOL Verb . . . . . . . . . . . . . . . . . . 5-1 5.1.2 /SHOW qualifier . . . . . . . . . . . . . . . . 5-2 5.1.3 /SET qualifier . . . . . . . . . . . . . . . . 5-2 5.1.4 /DELETE qualifier . . . . . . . . . . . . . . . 5-3 5.1.5 /IDENTIFICATION qualifier . . . . . . . . . . . 5-4 5.1.6 /GLOBAL qualifier . . . . . . . . . . . . . . . 5-4 5.1.7 /LOCAL qualifier . . . . . . . . . . . . . . . 5-4 5.1.8 /DEPTH qualifier . . . . . . . . . . . . . . . 5-5 5.1.9 /BINARY qualifier . . . . . . . . . . . . . . . 5-6 TMESIS SYMBOL (tm) V4.0 Product Guide Page 4 24 May 1997 5.1.10 /HELP qualifier . . . . . . . . . . . . . . . . 5-7 APPENDIX A RELEASE INFORMATION A.1 SYMBOL V4.0 . . . . . . . . . . . . . . . . . . . A-1 A.1.1 V4.0 %7.143 (current) . . . . . . . . . . . . . A-1 A.2 SYMBOL V3.1 (beta field test release) . . . . . . A-1 A.2.1 V3.1 %6.350: /DEPTH qualifier . . . . . . . . . A-1 A.2.2 V3.1 %6.350: /SHOW output format . . . . . . . . A-2 A.2.3 V3.1 %6.350: /SHOW output defaults . . . . . . . A-2 A.2.4 V3.1 %6.350: /HELP qualifier added . . . . . . . A-2 A.2.5 V3.1 %6.350: Abbreviated symbol changes . . . . A-2 A.2.6 V3.1 %6.350: Direct Cross-Process Copying . . . A-2 A.2.7 V3.1 %6.350: INSTALL_SYMBOL.COM procedure . . . A-3 A.2.8 V3.1 %6.350: SYMBOL Logical Names . . . . . . . A-3 A.2.9 V3.1 %6.350: PERMANENT removed . . . . . . . . . A-3 A.2.10 V3.1 %6.350: VMSINSTAL KIT . . . . . . . . . . A-3 A.2.11 V3.1 %6.350: Source Code Availability . . . . . A-3 APPENDIX B PROGRAM MAINTENANCE (BUG FIXES) B.1 SYMBOL V3.1 (beta field test) . . . . . . . . . . B-1 B.1.1 V3.1 %7.065: SMI Returned ABORT Condition . . . B-1 B.2.1 V3.1 %7.062: Sub-Procedural Symbol Selection . . B-1 B.3.1 V3.1 %7.059: Sub-Procedural Definition Problem . B-1 B.4.1 V3.1 %7.043: Current Procedure Depth Definition B-2 B.4.2 V3.1 %7.043: Modified Handling of Quoted Strings B-2 B.5.1 V3.1 %7.039: Dispatcher Computation . . . . . . B-2 B.6.1 V3.1 %6.294: Target Image Termination . . . . . B-2 APPENDIX C PROGRAMMING CHANGES C.1 SYMBOL V3.1 (beta field test) . . . . . . . . . . C-1 C.1.1 V3.1 %6.350: General Sanitization . . . . . . . C-1 APPENDIX D RELEASE NOTES AND PRODUCT FEATURES (ARCHIVED) D.1 Previous Release Information . . . . . . . . . . . D-1 D.1.1 V3.0 %4.091: Automatic dispatcher location . . . D-1 D.2.1 V3.0 %4.062: OpenVMS Alpha Port and Rewrite . . D-1 D.2.2 V3.0 %4.062: VMScluster-wide Support . . . . . . D-2 D.2.3 V3.0 %4.062: Binary Symbol Support . . . . . . . D-2 D.2.4 V3.0 %4.062: Optional Qualification . . . . . . D-3 D.2.5 V3.0 %4.062: Process Privilege Checking . . . . D-3 D.2.6 V3.0 %4.062: Enhanced Error Reporting . . . . . D-3 D.2.7 V3.0 %4.062: Symbol Name Checks . . . . . . . . D-3 D.2.8 V3.0 %4.062: Symbol Existance Checks . . . . . . D-3 D.2.9 V3.0% 4.062:Symbol Command Verb . . . . . . . . D-4 D.3.1 V2.0 %4.012: Supervisor AST Data Moved . . . . . D-4 TMESIS SYMBOL (tm) V4.0 Product Guide Page 5 24 May 1997 APPENDIX E ACKNOWLEDGEMENTS E.1 Special Recognition . . . . . . . . . . . . . . . E-1 APPENDIX F SAMPLE SYMBOL INSTALLATION F.1 VMSINSTAL of SYMBOL V4.0 . . . . . . . . . . . . . F-1 APPENDIX G FEEDBACK AND CONTACT G.1 Contacting the Author . . . . . . . . . . . . . . G-1 CHAPTER 1 PRODUCT OVERVIEW 1.1 Brief Product Overview 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 can be a invaluable utility for both the system manager and the DCL program developer. Using SYMBOL, the system manager can easily modify and view a user's DCL environment. Developers and maintainers of DCL command procedures can use SYMBOL as a DCL debugging utility because SYMBOL provides them the ability to observe both the symbol, by name, and its equivalence string while the DCL procedure is executing in a context of a process. 1.1.1 User Interface SYMBOL displays the user's symbol table's contents using an output format similar to the output format of the OpenVMS DCL command '$ SHOW SYMBOL'. A single equal sign '=' is used to denote LOCAL symbols while the double equal sign '==' is used for denoting GLOBAL symbols. Binary symbols are formatted with the familiar decimal, hexadecimal and octal presentation. The format of the SYMBOL command interface for symbol definition, display or deletion is not at all like that of the OpenVMS DCL CLI. The command interface to SYMBOL is comprised of a set of logically orthogonal functions for manipulating DCL symbols. SYMBOL has been designed to provide as many DCL-like symbol definition features as possible and then, goes well beyond DCL's native capabilities. PRODUCT OVERVIEW Page 1-2 Brief Product Overview 24 May 1997 1.1.2 Beyond DCL SYMBOL goes well beyond the capabilities inherent in the OpenVMS DCL CLI. Using SYMBOL, a user can manipulate both their process and another process's DCL environment. With DCL, the user would be resigned to and/or restricted to the environment of his or her process only. This feature makes SYMBOL an ideal development and/or debugging tool for any shop that develops and/or maintains DCL procedures for their production environments. In addition to its ability to affect another process, SYMBOL also allows its user to manipulate features of the DCL symbol environment that the DCL CLI does not provide. SYMBOL has an exhaustive set of sub-procedural symbol definition and display features. This unique to SYMBOL feature allows a user to display, define or delete any DCL symbol in any process at any procedure level. This feature is also a great debugging tool for the DCL developer. 1.1.3 Installation TMESIS SYMBOL V4.0 can be easily installed on any OpenVMS system; VAX or Alpha. SYMBOL is installed using the OpenVMS VMSINSTAL utility. Specify the product to be installed as: SYMBOL040. For further information and specific details on the installation of TMESIS SYMBOL V4.0, refer to the section titled: "SYMBOL Installation" appearing in this document. Details about TMESIS SYMBOL V4.0 features and its use can be found in the document in the section titled: "SYMBOL Features and Use". Some examples illustrating the use and features of SYMBOL will also be found in under that section. CHAPTER 2 PRODUCT INSTALLATION 2.1 SYMBOL Installation TMESIS SYMBOL V4.0 installs easily using the familiar OpenVMS VMSINSTAL facility. A sample installation of SYMBOL is provided in the appendix of this document. SYMBOL may be installed while users are actively using the system. It is recommended that SYMBOL be installed using the SYSTEM account. This will insure that the installer has all the privileges and rights to write SYMBOL's files to the device and directory selected during the installation. 2.1.1 SYMBOL Placement By default, SYMBOL will be installed on your system disk in a directory called: SYS$SYSDEVICE:[SYMBOL]. You may elect to install SYMBOL on any disk on your system; SYMBOL does not require that it be located on the system drive. The VMSINSTALlation of SYMBOL will prompt for the location of the SYMBOL product files. If you elect to place them elsewhere, specify this new location when so prompted. 2.1.2 SYMBOL$AST_LEI Placement During the initial startup of TMESIS SYMBOL V4.0, a loadable executive image file called SYMBOL$AST_LEI.EXE will be placed on your system device in the directory defined by the logical: SYS$LOADABLE_IMAGES. This execlet is the only file that must be a resident of the system device. All other product files may exist on any other drive in the VMScluster. The SYMBOL$AST_LEI.EXE loadable executive image file is copied into the SYS$LOADABLE_IMAGES directory the first time that SYMBOL is started on the system. This file will be automatically replaced if and when SYMBOL is upgraded on the system. PRODUCT INSTALLATION Page 2-2 SYMBOL Installation 24 May 1997 2.1.3 OpenVMS Version Support TMESIS SYMBOL V4.0 will install and run on the following versions of Digital Equipment Corp.'s OpenVMS operating system. o OpenVMS VAX versions V6.0 through and including V7.1 o OpenVMS Alpha versions V6.1 through and including V7.1 CHAPTER 3 PRODUCT ENVIRONMENT 3.1 SYMBOL Environment This section of the document will describe how the TMESIS SYMBOL V4.0 environment is established on the system and how to make SYMBOL available as a VERB to the user. SYMBOL was designed to allow maximum flexibility for its use in various environments. The following will describe the many ways in which SYMBOL can be made available as a DCL verb and how to start or initialize the environment which supports SYMBOL. 3.1.1 Starting SYMBOL TMESIS SYMBOL V4.0 must be installed (not to be confused with the VMSINSTALlation process) or started on the system prior to its use. This is accomplished by executing the command procedure: INSTALL_SYMBOL.COM located in the SYMBOL directory created when the product was installed. Typically, an invocation of this procedure should be added to the system startup files so that SYMBOL will be install when the system is booted or rebooted. Assuming the default directory selection for placement of the SYMBOL product files, this command would be: $ @SYS$SYSDEVICE:[SYMBOL]INSTALL_SYMBOL.COM. 3.1.1.1 VMScluster Operation TMESIS SYMBOL V4.0 can be used in a VMScluster to affect processes on any node in the cluster. To use SYMBOL cluster-wide, SYMBOL must be started on the node you which to allow SYMBOL to have access. PRODUCT ENVIRONMENT Page 3-2 SYMBOL Environment 24 May 1997 3.1.1.2 SYMBOL Startup Activities The INSTALL_SYMBOL.COM file performes the following steps: 1. Performs privilege checks. 2. Determines the product directory location. 3. Defines the system executive logical: TMESIS%SYMBOL. 4. Installs the SYMBOL executable as a known image with the appropriate privileges needed for its operation. 5. Unloads the SYMBOL$AST_LEI.EXE support execlet (if loaded). 6. Determines if a new copy of the SYMBOL$AST_LEI.EXE support execlet must be placed into SYS$LOADABLE_IMAGES and, if so, copies the file and deletes the old version. 7. Loads the SYMBOL$AST_LEI.EXE support execlet. When TMESIS SYMBOL is successfully loaded, the following confirmational message will be displayed on the system operator console. %SYMBOL, Copyright 1993,1994,1996,1997, Brian Schenkenberger and TMESIS %SYMBOL, Executive image SYMBOL$AST_LEI was successfully loaded at: %x The process executing the INSTALL_SYMBOL.COM procedure will receive the following message confirming a successful installation and startup of the TMESIS SYMBOL V4.0 environment. Copyright © 1993, 1994, 1996, 1997 Brian Schenkenberger and TMESIS. SYMBOL$AST_LEI loaded at 80CD6000 80E38300 000000B2 3.1.2 Defining the SYMBOL Command The SYMBOL command verb is used to invoke the SYMBOL utility. This command must be defined prior to using the SYMBOL utility. TMESIS SYMBOL V4.0 was designed to allow a flexible mechanism for the definition of the SYMBOL command verb. SYMBOL, as a command, can be made available to the user any one of several different ways. Each of these methods will suffice to define the SYMBOL command. This flexibility was designed into SYMBOL to allow the SYSTEM manager to decide which method is preferred for or best suited to their environment. 3.1.3 SYMBOL as a Foreign Command SYMBOL can be defined as a foreign command by using the following syntax. PRODUCT ENVIRONMENT Page 3-3 SYMBOL Environment 24 May 1997 $ SYMBOL :== $TMESIS%SYMBOL This definition may be placed in a user's LOGIN.COM file or in the system SYLOGIN.COM file. When this symbol definition is to be placed into one of the aforementioned files, it is recommended that it be defined using the following syntax. This will make the definition of the foreign command available only on the machines where SYMBOL has been installed. $ IF F$trnlnm("TMESIS%SYMBOL").NES."" THEN $ SYMBOL :== $TMESIS%SYMBOL Note that the definition of SYMBOL as a foreign command leaves it vulnerable to symbol deletion. 3.1.3.1 SYMBOL as a DCL Command SYMBOL can be added as a DCL command in the process's command tables by using the following syntax. $ SET COMMAND TMESIS%SYMBOL only after SYMBOL has been started on the system. This command definition may be placed in a user's LOGIN.COM file or in the system SYLOGIN.COM file. When this command is to be placed into one of the aforementioned files, it is recommended that it be defined using the following syntax. This will make the definition of the command verb available only on the machines where SYMBOL has been installed. $ IF F$trnlnm("TMESIS%SYMBOL").NES."" THEN $ SET COMMAND TMESIS%SYMBOL This method of definition of the SYMBOL command will not be deleted or removed by normal symbol deletions. 3.1.3.2 SYMBOL in DCLTABLES.EXE SYMBOL can added to the DCL tables file SYS$SHARE:DCLTABLES.EXE so that it exists as a default for all processes on the system. To define SYMBOL and place it into the DCLTABLES, issue the following command. $ SET COMMAND TMESIS%SYMBOL/TABLE=SYS$COMMON:[SYSLIB]DCLTABLES.EXE - _$ /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE only after SYMBOL has been started on the system. After this command has been executed, the DCLTABLES.EXE must be replaced using the OpenVMS INSTALL utility. The following commands will replace the DCLTABLES.EXE file. PRODUCT ENVIRONMENT Page 3-4 SYMBOL Environment 24 May 1997 $ INSTALL:==$INSTALL/COMMAND_MODE $ INSTALL REPLACE SYS$COMMON:[SYSLIB]DCLTABLES.EXE Defining SYMBOL in this fashion will make its definition as a DCL command available for all processes that use/map the default DCLTABLES. The above steps need to be executed only one time. Once the SYMBOL command verb has been added to the DCLTABLES.EXE file, it will be available unless specifically deleted from this file. Consult the OpenVMS documentation "Guide to OpenVMS Command Definition" for further details on adding a command to the OpenVMS DCLTABLES.EXE file. CHAPTER 4 PRODUCT FEATURES 4.1 SYMBOL Features This section is devoted to providing a description, in brief detail, of the various features of TMESIS SYMBOL V4.0. All of the SYMBOL features, its qualifiers, and examples are available to the user, on-line, via the SYMBOL /HELP qualifier discussed in a subsequent section of this document. 4.1.1 Utility and Orthogonality SYMBOL provides an interface into the OpenVMS DCL symbol tables. All of the default DCL symbol manipulation features are available with SYMBOL. In addition, SYMBOL augments these DCL capabilities with an assortment of features unique unto itself. The SYMBOL verb is used to access the features of SYMBOL. Additionally, a rich set of orthogonal functions are available via the application of command qualifiers to the SYMBOL verb. SYMBOL's command interface was developed to maintain a single, logical and orthogonal set of functions which allow the user to manipulate DCL symbols. This is unlike its DCL counterpart. With DCL, symbols are defined using a syntax which is completely foreign to the DCL functions for display of symbols and for the deletion of symbols from the process. The following lists the various syntax formats used within DCL for the manipulation of symbols. 1. $ SYMBOL_NAME == SYMBOL_VALUE 2. $ DELETE/SYMBOL SYMBOL_NAME 3. $ SHOW SYMBOL SYMBOL_NAME The non-orthogonality of the DCL symbol manipulation mechanisms is clearly depicted in the above. PRODUCT FEATURES Page 4-2 SYMBOL Features 24 May 1997 In contrast, SYMBOL uses a very orthongonal set of commands. The basic SYMBOL commands are depicted below. 1. $ SYMBOL/SET SYMBOL_NAME SYMBOL_VALUE 2. $ SYMBOL/DELETE SYMBOL_NAME 3. $ SYMBOL/SHOW SYMBOL_NAME 4.1.2 VMScluster Support Also, unlike DCL, SYMBOL can set, delete and display DCL symbols defined in another process anywhere in a VMScluster -- VAX or Alpha, mixed-architecture and mixed-version VMSclusters. 4.1.3 Sub-Procedural Level Support SYMBOL can also manipulate DCL symbols based upon their procedural level definition. Using DCL, local symbols at the current procedural level are the only local symbols accessible to DCL. SYMBOL can affect symbols at any procedure level either by absolute and relative procedural level indicies. In addition, SYMBOL can and will display all procedural level symbols defined in the target process. 4.1.4 Access and Security After TMESIS SYMBOL V4.0 has been installed, started and defined, users can immediately start to use its features. SYMBOL employs a security scheme based on the user's currently active account privileges. Users with normal non-privileged accounts can only affect processes which they own or which have their same UIC. A user's account must possess the GROUP privilege to affect a process within the definition of their UIC group. Processes possessing WORLD privilege can affect any and all processes on the system. The normal user privilege, TMPMBX, is necessary for cluster-wide use of SYMBOL. 4.1.5 Supported Environments TMESIS SYMBOL V4.0 can be used interactively, in command procedures, batch jobs and accross the network in a suitably written network task. CHAPTER 5 PRODUCT UTILIZATION 5.1 SYMBOL Use The following sections will describe, with some detail, the various command options and qualifiers of TMESIS SYMBOL V4.0. All of the SYMBOL features, its qualifiers, and examples are available to the user, on-line, via the SYMBOL /HELP qualifier discussed in this section of this document. This section is intended to provide the user with a general conceptual understanding of the various capabilites and command syntax of SYMBOL. Many of the DCL features and constructs which can be manipulated by SYMBOL may be either new to the DCL environment or DCL user or the functions which SYMBOL provides are not available with any currently available DCL commands. Therefore, this section will attempt familiarize the user with the basic command syntax of SYMBOL and some features of DCL where the user may be unfamiliar. Where it is deemed necessary, examples have been provided to illustrate and/or demonstrate a particular DCL construct which can be manipulated using SYMBOL. 5.1.1 SYMBOL Verb When the SYMBOL verb or command is issued, its default action is to display all known process symbols for the process issuing the command. By default, SYMBOL displays all global symbols and then, all local DCL symbol in order of their procedural definition. The display format is similar to the output from the DCL command SHOW SYMBOL. The display of each symbol is prefixed by a number in square brackets to denote the procedural level at which the local symbol definiton exists. Global symbols do not display a numeric value -- the brackets, instead, contain a '-'. Global symbols are also displayed with the familiar DCL double equal sign notation; local symbols have a single equal sign. Binary values are also displayed in the familiar DCL decimal, hexadecimal and octal presentation format. PRODUCT UTILIZATION Page 5-2 SYMBOL Use 24 May 1997 Below is a sample of the output using the SYMBOL command. $ SYMBOL [-] $RESTART == "FALSE" [-] $SEVERITY == "1" [-] $STATUS == "%X00000001" [-] ED*IT == "EDIT/EDT" [-] HOME == "SET DEFAULT SYS$LOGIN" [-] REC*ALL == "RECALL" [-] SHUTDOWN == "@SYS$SYSTEM:SHUTDOWN" [-] VMSINSTAL == "SPAWN @SYS$UPDATE:VMSINSTAL" [-] ZIP == "$SYS$UTILITY:[FILESERV_TOOLS]ZIP.EXE" [0] Y = 1638 Hex = 00000666 Octal = 00000003146 $ The SYMBOL verb, in this form, will accept a parameter. This parameter serves as a match-pattern for selecting symbols for display. The match-pattern will accept the standard VMS wildcard characters of '*' and '%' in any order or combination with other alpha-numeric characters. $ SYMBOL ED [-] ED*IT == "EDIT/EDT" $ $ SYMBOL $ $ $ SYMBOL $* [-] $RESTART == "FALSE" [-] $SEVERITY == "1" [-] $STATUS == "%X00000001" $ 5.1.2 /SHOW qualifier The /SHOW qualifier is the default for the SYMBOL verb. SYMBOL can be specified without the /SHOW qualifier and its existence only serves to complete the orthogonal repertiore of command qualifiers. If the /SHOW qualifier is specified with the SYMBOL command, its position must be the first qualifier to the command. All other valid qualifers will be subordinate to the /SHOW qualifier. Example output using the /SHOW qualifier are show in the previous section. 5.1.3 /SET qualifier The /SET qualifier is specified to define or modify a symbol. When the /SET qualifier is specified, the SYMBOL verb will expect two PRODUCT UTILIZATION Page 5-3 SYMBOL Use 24 May 1997 command parameters to be specified. The first parameter must be the symbol to be defined or modified. The second parameter must be the equivalence value for the specified symbol name. If either parameter is omitted, SYMBOL will prompt for their values. Note that, if SYMBOL must prompt for input of the equivalence value, certain DCL command line processing functions such as lexical translation and expression evaluation will not be performed. The processing of the /SET qualifier has been adopted to closely mimic a similar definition in DCL. For example, defining the symbol ABC using either of the following two statements will result in the same outcome. 1. $ ABC :== THIS IS "lowercase" TEXT 2. $ SYMBOL/SET ABC THIS IS "lowercase" TEXT If the /SET qualifier is specified with the SYMBOL command, its position must be the first qualifier to the command. All other valid qualifers will be subordinate to the /SET qualifier. SYMBOL follows all of the rules and conventions for normal symbol name specification. If an invalid symbol name is specified, SYMBOL will report an error. 5.1.4 /DELETE qualifier The /DELETE qualifier is specified to remove a symbol definition. When the /DELETE qualifier is specified, the SYMBOL verb will expect a single command parameter to be specified. This parameter must be the symbol to be deleted or removed. If the parameter is omitted, SYMBOL will prompt for its value. If the /DELETE qualifier is specified with the SYMBOL command, its position must be the first qualifier to the command. All other valid qualifers will be subordinate to the /DELETE qualifier. The following depicts an example of using the SYMBOL command with the /DELETE qualifier. $ SYMBOL/DELETE ABC SYMBOL follows all of the rules and conventions for normal symbol name specification. If an invalid symbol name is specified, SYMBOL will report an error. If the SYMBOL specified does not exist, SYMBOL will return an error signifying that the symbol does not exist. PRODUCT UTILIZATION Page 5-4 SYMBOL Use 24 May 1997 5.1.5 /IDENTIFICATION qualifier The /IDENTIFICATION qualifier is used when the target of the SYMBOL command is a process other than that of the process issuing the command. The /IDENTIFICATION qualifier requires the specification of the target process's process id (PID) as an argument to the qualifier. This PID can be the PID of any valid process on the system or within the VMScluster. If the process id (PID) is invalid or the user issuing the command does not possess the appropriate privileges to affect the process, an error message signifying the reason for failure will be returned. The following depicts the use of the /IDENTIFICATION qualifier with the SYMBOL command. In this example, the default /SHOW function is used to examine the target process's current values for $SEVERITY and $STATUS. $ SYMBOL/IDENTIFICATION=21200373 $S* [-] $SEVERITY == "1" [-] $STATUS == "%X00000001" $ 5.1.6 /GLOBAL qualifier The /GLOBAL qualifier is used to restrict the focus of the SYMBOL command to be global symbols. When used in conjuction with the /SHOW qualifier, the SYMBOL command will display only global symbol definitions. When used with either the /SET or /DELETE qualifiers, SYMBOL will act only on a global definition of the symbol specified. /GLOBAL is implied when used with the /SET and/or /DELETE qualifiers. Note that DCL permanent symbols are considered to be global symbols by both DCL and SYMBOL. SYMBOL will not permit permanent symbols to be redefined. This restriction may be removed in a future release. TMESIS PERMANENT can be used to somewhat augment the SYMBOL utility to create or modify permanent symbols if desired. Current versions of PERMANENT will only work in the context of the process issuing the command. 5.1.7 /LOCAL qualifier The /LOCAL qualifier is used to restrict the focus of the SYMBOL command to be local symbols. When used in conjuction with the /SHOW qualifier, the SYMBOL command will display only local symbol definitions. When used with either the /SET or /DELETE qualifiers, SYMBOL will act only on a local definition of the symbol specified. The /DEPTH qualifier may be required to correctly focus the requested PRODUCT UTILIZATION Page 5-5 SYMBOL Use 24 May 1997 action of the SYMBOL command when used with either the /SET or /DELETE qualifiers. 5.1.8 /DEPTH qualifier The /DEPTH qualifier must be used in conjunction with the /LOCAL qualifier. /DEPTH is used to specify the procedural level at which a symbol is to be acted upon by SYMBOL. The /DEPTH qualifier can be specified with a parameter value. This value is used to express the desired procedure level. If omitted, the procedure level defaults to level zero (0) which is the procedure level assigned to local symbols defined from the DCL command line. A procedural level is created whenever another command file is invoked or a DCL subroutine is invoked. Only DCL subroutines invoked using the DCL CALL and SUBROUTINE/ENDSUBROUTINE syntax will create a new procedural level. Subroutines invoked with the GOSUB syntax do not create a new procedural level. Each time a new procedural level is created, the procedural level depth count is increased by one. The maximum procedural depth supported by DCL is 31 levels. When specifying a procedural level with the SYMBOL /DEPTH qualifier, the procedural level can be expressed as either an absolute value or a relative value. Relative values are negative values and can only be used in the context of the process issuing the SYMBOL command. All other uses require an absolute value. Absolute values are always positive values. Any depth value specified, whether relative or absolute, that is outside of the maximum procedural level depth will cause SYMBOL to return an error indicating that the boundary conditions have been exceeded. A relative value expresses the procedural level higher than the current level of the process. In DCL, a higher procedure level has a lower value. Therefore, if a process is executing at procedural level 10 and SYMBOL is used to redefine a symbol at procedural level 7, a relative value of -3 could be specified as the argument to the /DEPTH qualifier. Hopefully, it is obvious that this relative feature can only be used only when the SYMBOL command is embedded within a command procedure. Expressed as an absolute value, SYMBOL can create symbols at procedural levels lower that the currently active procedure level. Normally, DCL casts away all symbols defined at a lower level when control is return to the next higher procedural level. Using SYMBOL and the /DEPTH qualifier, a symbol can be defined at a lower procedural level before is is created; thus, permitting conditional coding within a nested or recursive procedure to be governed by a higher level procedure. The following is a simple example demonstrating the use of the /DEPTH PRODUCT UTILIZATION Page 5-6 SYMBOL Use 24 May 1997 qualifier and a relative procedural depth indicator to modify a symbol's value at a higher procedural level. $ @TT _$ ABC := LEVEL'F$environment("DEPTH") _$ @TT _$ ABC := LEVEL'F$environment("DEPTH") _$ @TT _$ ABC := LEVEL'F$environment("DEPTH") _$ @TT _$ ABC := LEVEL'F$environment("DEPTH") _$ @TT _$ ABC := LEVEL'F$environment("DEPTH") _$ SYMBOL/LOCAL ABC [1] ABC = "LEVEL1" [2] ABC = "LEVEL2" [3] ABC = "LEVEL3" [4] ABC = "LEVEL4" [5] ABC = "LEVEL5" _$ SYMBOL/SET/LOCAL/DEPTH=-2 ABC "It's magic!" _$ SYMBOL/LOCAL ABC [1] ABC = "LEVEL1" [2] ABC = "LEVEL2" [4] ABC = "It's magic!" [3] ABC = "LEVEL4" [5] ABC = "LEVEL5" _$ EXIT %x2C %SYSTEM-F-ABORT, abort $ This example also depicts the output format of sub-procedural symbol definitions using the SYMBOL /SHOW capabilities. If a relative procedural depth value is specified and a process id is specified using the /IDENTIFICATION qualifier then, the PID must be that of the process issuing the command. If the PID is for a process other than the issuing process, an error will be reported and no action will be performed by SYMBOL. 5.1.9 /BINARY qualifier The /BINARY qualifier is used in conjunction with the /SET qualifier to define a binary equivalence value for a symbol. Binary symbols are those displayed by DCL and SYMBOL alike with the decimal, hexadecimal and octal presentation format. If the value specified for the symbol specified is not a numeric value, SYMBOL will report an error and will not affect the symbol specified if it already exists. PRODUCT UTILIZATION Page 5-7 SYMBOL Use 24 May 1997 5.1.10 /HELP qualifier The /HELP qualifier is used gain access to the SYMBOL on-line help information. SYMBOL's on-line help is an exhaustive reference for all of SYMBOL's parameters, qualifiers and returned errors. In addition, the on-line help provides a set of examples and some details on the internals of the DCL symbol table. APPENDIX A RELEASE INFORMATION A.1 SYMBOL V4.0 This section contains release information for the current release of TMESIS SYMBOL. The current release level of TMESIS SYMBOL at the time this document was produced is TMESIS SYMBOL V4.0 %7.143. A.1.1 V4.0 %7.143 (current) This release of SYMBOL contains several modifications and enhancements to SYMBOL in module SYMBOL$AST_LEI and the SYMBOL CLI support routines. A complete reworking of the mechanism to copy the symbol table contents from one process to another is incorporated in this release. NOTE: You may require a patch for your particular version of OpenVMS to use SYMBOL's cluster features. See the entry under Program Maintenance titled: V3.1 %7.065: SMI Returned ABORT Condition A.2 SYMBOL V3.1 (beta field test release) This section contains release information related to and incorporated into the beta field test release of V4.0 of TMESIS SYMBOL which was released as version V3.1(ß). A.2.1 V3.1 %6.350: /DEPTH qualifier This release introduces the /DEPTH qualifier. This feature allows local symbol definition, deletion and/or display to take place at the command procedure depth at which the symbol was defined or where the symbol will be defined. SYMBOL's new /DEPTH qualifier can be used within an executing DCL procedure to delete, display or define up-level symbols by relative level indicators. (eg. - ) RELEASE INFORMATION Page A-2 SYMBOL V3.1 (beta field test release) 24 May 1997 A.2.2 V3.1 %6.350: /SHOW output format The output format of the SYMBOL/SHOW command has been modified to show the procedural level at which the local symbol is defined. The familiar DCL symbol display format is now prefixed with "[n]", where 'n' is the procedure level. Global symbols are displayed with "[-]". SYMBOL will now display local symbols sorted by their command procedural level. A.2.3 V3.1 %6.350: /SHOW output defaults The /SHOW qualifier now defaults to displaying *ALL* symbols defined in the target process, both global and local, at all current DCL procedure levels. /GLOBAL or /LOCAL must now be specified to override the default behavior. A.2.4 V3.1 %6.350: /HELP qualifier added The /HELP qualifier was added to allow the user to easily display help information pertainent to the SYMBOL utility. A.2.5 V3.1 %6.350: Abbreviated symbol changes SYMBOL now treats abbreviated DCL symbol definition similar to the way that the DCL $ SHOW SYMBOL and $ DELETE/SYMBOL commands affect symbols of this type. Specifying '$ SYMBOL/SHOW ABC' will now show all symbols which match ABC and any abbreviated definitons which match ABC without specifying a wildcard character. Specifying '$ SYMBOL/DELETE ABC' will now delete any abbreviated symbol which matches this string. SYMBOL no longer requires the specification of the full symbol name to delete abbreviated symbols; only the unique portion need be supplied to delete symbols of this type. A.2.6 V3.1 %6.350: Direct Cross-Process Copying This release introduces what is being referred to as "Direct Cross-Process Copying" or "Direct Process-to-Process Copying" (DCPC) of target process's symbol table. The movement of symbol table data from the target process to the origin process no longer uses non-paged pool to move the data. In prior releases, SYMBOL would allocate a large chunk of nonpaged RELEASE INFORMATION Page A-3 SYMBOL V3.1 (beta field test release) 24 May 1997 pool and then, copy the target's symbol table's contents into this allocated region and then, copy from the nonpaged pool into the origin process's virtual address space. Two large copies and a large nonpaged pool need were not very efficient methods for moving the symbol table's contents from one process to another. This mechanism is analogous to a buffered I/O operation in an OpenVMS device driver. In this release, the origin process's address space is mapped within the special kernel AST that is queued to the target process when the display function is selected. The target's symbol table's contents are moved to the origin process's address space using a single copy operation and the mapping window SPTE allocated when SYMBOL is installed. This mechanism is analogous to a direct I/O operation in an OpenVMS device driver and, remarkably, is the same on VAX and Alpha with exception of the page size differences. A.2.7 V3.1 %6.350: INSTALL_SYMBOL.COM procedure The INSTALL_SYMBOL.COM procedure now uses the default specification of the INSTALL_SYMBOL.COM when parsing SYMBOL components for installation and logical name definition. A.2.8 V3.1 %6.350: SYMBOL Logical Names The SYMBOL product files are now located using the system-wide logical TMESIS%SYMBOL. A.2.9 V3.1 %6.350: PERMANENT removed PERMANENT is no longer being distributed with SYMBOL. PERMANENT can be obtained as a separate utility. A.2.10 V3.1 %6.350: VMSINSTAL KIT SYMBOL is now easily installed using the familiar OpenVMS VMSINSTAL KIT utility. Product name for VMSINSTAL is SYMBOL. A.2.11 V3.1 %6.350: Source Code Availability Source code for SYMBOL is no longer being shipped with the kit. Source code is freely available for the asking after the execution of a Source Code Non-Disclosure and Confidentiality Agreement. To obtain a copy of the source code, send an e-mail request to: VAXman@TMESIS.COM and state in that e-mail that you would like to RELEASE INFORMATION Page A-4 SYMBOL V3.1 (beta field test release) 24 May 1997 obtain the SYMBOL source code. APPENDIX B PROGRAM MAINTENANCE (BUG FIXES) B.1 SYMBOL V3.1 (beta field test) This section contains information on maintenance items corrected for and or during the beta field test release of V4.0 of TMESIS SYMBOL which was released as version V3.1 (doy). B.1.1 V3.1 %7.065: SMI Returned ABORT Condition Code was modified to suppress a feign error returned by the SMI service which handles remote command execution. The error appears to be attributed to a Digital patch (ALPMANA02_070) which corrects an SMI timeout condition for commands which are remotely executed that do NOT produce output. You may need to obtain and apply this patch if your machine is are running OpenVMS V6.1 through V7.0 and you wish to use SYMBOL to do remote operations. Details of this patch and this problem are detailed in a DSN article titled: OpenVMS: ALPMANA02_070 Alpha V6.1 - V7.0 SYSMAN/SMISERVER ECO Summary B.2.1 V3.1 %7.062: Sub-Procedural Symbol Selection This release corrects a coding bug within the mechanism which preserves sub-procedural SYM blocks when local symbols are defined. An unsigned branch was incorrectly causing global symbols to be taken off the queue during a local symbol definition. The unsigned branch was corrected to use a signed branch. B.3.1 V3.1 %7.059: Sub-Procedural Definition Problem This release corrects a coding bug within the mechanism which preserves and restores sub-procedural SYM blocks when local symbols are defined at a procedural depth less than the current procedure depth value. The problem would manifest itself as permitting multiple definitions of the same symbol at a procedure level and/or mask others PROGRAM MAINTENANCE (BUG FIXES) Page B-2 SYMBOL V3.1 (beta field test) 24 May 1997 at a sub-procedural level. B.4.1 V3.1 %7.043: Current Procedure Depth Definition This release changed the functionality of the /DEPTH qualifier slightly to allow SYMBOL to define a local symbol at the current procedure depth without having to specify the level (which required knowing the current procedure depth). (See SYMBOL/HELP .. Qualifiers .. /DEPTH for further information.) B.4.2 V3.1 %7.043: Modified Handling of Quoted Strings This release modified the handling of the command SYMBOL/SET ABC "xyz". In prior releases, this command would set symbol ABC to a quoted value of lowercase xyz. This release changed the behavior. Symbol ABC will now simply equate to lowercase xyz. If the old behavior is desired, a set of double quotes should be used. Example: SYMBOL/SET ABC """xyz""" B.5.1 V3.1 %7.039: Dispatcher Computation This release fixed a bug which was discovered when using SYMBOL to set or delete a symbol when the operating system was OpenVMS Alpha V6.2. Under OpenVMS V6.2 the /SET and /DELETE would not function and images running in the target process would be terminated. This problem was caused by an assumption in the dispatcher location computation. When a /SET or /DELETE was issued, the routine being called was NOT the DCL dispatcher. B.6.1 V3.1 %6.294: Target Image Termination This release fixed a bug which could potentially terminate an image in the target process with an unhandled exception. This was due to SYMBOL incorrectly assuming that register (R11) maintained the address of the process's work space when the supervisor mode AST invoked the internal DCL dispatcher routine. The supervisor mode routine now deposits this value into register R11 before invoking the dispatcher. This problem was only evident if the target process is running an image -- SYMBOL performed correctly when the process was at the DCL level. APPENDIX C PROGRAMMING CHANGES C.1 SYMBOL V3.1 (beta field test) This section contains information related to the internal programming changes adopted for and during the beta field test release of V4.0 of TMESIS SYMBOL which was released as version V3.1(ß). C.1.1 V3.1 %6.350: General Sanitization A number of changes were made to "sanitize" the code and make it less architecturally dependent at compilation time. This was accomplished with several new macros which the author developed and has included in each module as a "standard" preamble. Many of the macros are concerned with the 32/64 bit nature of the newer releases of OpenVMS. Strangely enough, SYMBOL is not thawted by any current 32/64 bit issues. Future releases of OpenVMS may change this but, for now, SYMBOL can be built and executed on all current versions of OpenVMS VAX and Alpha. SYMBOL has not been changed because of any OpenVMS Alpha changes since its initial Alpha port in January of 1994. The inclusion of the "Direct Cross-Process Copying" mechanism is dependant on the target architecture because of architectural differences in the page table structures of the VAX and Alpha. However, thoeretically, the mechanics of the "Direct Cross-Process Copying" routine are similar. The other changes made to SYMBOL were for the addition of the new /DEPTH qualifier and the changes to correct the overlooked R11 issue. Neither of these changes have any architectural dependancies. In this release, the author has included some new techniques for Alpha and VAX functionality differences. The following section will detail these items. 1. Macros to simplify conditionalization of the source. These macros were devised to eliminate the use of block conditional sections in the code especially, in cases where a single statement was the object of the block conditionalization. PROGRAMMING CHANGES Page C-2 SYMBOL V3.1 (beta field test) 24 May 1997 These macros include the following: .ON_AXP required only for OpenVMS Alpha .ON_VAX required only for OpenVMS VAX .IF_32 required only for 32 bit OpenVMS .IF_64 required only for 64 bit OpenVMS $PUSHR64 push full 64 bit context of register list $POPR64 pop full 64 bit context of register list The $PUSHR64 and $POPR64 macros were developed to augment the DEC supplied macros: $PUSH64 and $POP64. Unlike the VAX PUSHR and POPR instructions, the register order is important when using these two macros. 2. Invocation of architectural specific routines without conditionalization of the source. This technique was devised to avoid the conditionalization of the source code when routine names changed across implementations but there is no significant change to the routine's interface. Case: EXE$xxx_TO_yyy routines were renamed EXE$CVT_xxx_TO_yyy but their interface is essentially the same. To accomplish this, the .WEAK directive is employed to declare both forms/names of the routine. This author first demonstrated this technique at a DECUS National Symposium two years prior to this package release. Here is an example employed in the module: SYMDELSETB {...} .WEAK EXE$EPID_TO_PCB,EXE$CVT_EPID_TO_PCB {...} 20$: PUSHL # JSB @(SP)+ TSTL R0 BEQL 30$ 3. Reference to architectural specific global symbols without conditionalization of the source. This technique was devised to avoid the conditionalization of the source code when global symbols change across implementations but there is no significant change to the routine's interface. Case: The "base image" mutex address changed from a EXE$GL_BASIMGMTX to EXE$GQ_BASIMGMTX and it must be passed to an appropriate quadword mutex locking routine. The locking routines have the same syntax as the original OpenVMS VAX counterpart but are suffixed with the string "_QUAD". To use this technique, the author expanded upon the technique described above, augmenting the technique described PROGRAMMING CHANGES Page C-3 SYMBOL V3.1 (beta field test) 24 May 1997 in the aforementioned section above. Here is an example employed in the module: SYMFINDLEI {...} .WEAK EXE$GL_BASIMGMTX,EXE$GQ_BASIMGMTX {...} MOVL #,R0 MOVL G^CTL$GL_PCB,R4 .ON_VAX ;;; techn. #1 .ON_AXP ;;; techn. #1 APPENDIX D RELEASE NOTES AND PRODUCT FEATURES (ARCHIVED) D.1 Previous Release Information This section contains release and product information from past releases of TMESIS SYMBOL. D.1.1 V3.0 %4.091: Automatic dispatcher location This release of SYMBOL contained a minor modification to SYMBOL$AST_LEI. This modification permitted the LEI's initialization routine on OpenVMS AXP systems to automatically determine the offset to the DCL$CHANGE_MODE dispatcher's procedure descriptor. Thus, SYMBOL should now work on all currently known versions of the OpenVMS AXP operating system. D.2.1 V3.0 %4.062: OpenVMS Alpha Port and Rewrite SYMBOL is now supported on OpenVMS VAX and OpenVMS AXP platforms. 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:. The execlet is loaded into system space using the INSTALL_SYMBOL.COM proceedure. This change was necessary for the OpenVMS Alpha support. To make SYMBOL as compatible as possible on both platforms, the OpenVMS VAX version of SYMBOL also uses the LEI. This release of SYMBOL represented 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 RELEASE NOTES AND PRODUCT FEATURES (ARCHIVED) Page D-2 Previous Release Information 24 May 1997 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. D.2.2 V3.0 %4.062: VMScluster-wide Support SYMBOL can now be used to display, define and delete DCL symbols in any process on any active node in a VMScluster. The process must possess the TMPMBX privilege and access privileges to the remote node. (ie. login capability on the remote node.) D.2.3 V3.0 %4.062: Binary Symbol Support The command qualifier /BINARY provides the ability for defining binary (integer) symbols. All previous SYMBOL releases provided only string RELEASE NOTES AND PRODUCT FEATURES (ARCHIVED) Page D-3 Previous Release Information 24 May 1997 definition. D.2.4 V3.0 %4.062: Optional Qualification The /IDENTIFICATION qualifier is optional. If the qualifier is omitted or the PID is specified as zero (0), SYMBOL will default to the current process. D.2.5 V3.0 %4.062: Process Privilege Checking New process privilege checks. SYMBOL may now be installed with CMKRNL privilege so that all users can utilize the command. A user without GROUP and WORLD privilege can affect only their own processes. Users with GROUP can affect processes within their 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 target processes. D.2.6 V3.0 %4.062: 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. Errors reported by SYMBOL are now formatted to reflect SYMBOL in the error message. (eg. %SYMBOL-F-NOGROUP, operation requires GROUP privilege) D.2.7 V3.0 %4.062: Symbol Name Checks The symbol name is now checked by SYMBOL to insure that is conforms to the accepted rules for formulating symbol names. D.2.8 V3.0 %4.062: Symbol Existance Checks 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. RELEASE NOTES AND PRODUCT FEATURES (ARCHIVED) Page D-4 Previous Release Information 24 May 1997 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. D.2.9 V3.0% 4.062:Symbol Command Verb 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. D.3.1 V2.0 %4.012: Supervisor AST Data Moved SYMBOL now places the SUPERVISOR mode code into the per-process user "core-common" area of the process P1 space. The OpenVMS source 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 ADDR | 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.) APPENDIX E ACKNOWLEDGEMENTS E.1 Special Recognition SYMBOL was originally written in a response to brief discussion on the now defunct MACRO32 mailing list and usenet newsgroup VMSnet.Internals. The first release of SYMBOL in the Fall of 1993 was for OpenVMS VAX only and only provided the capabilities to define and delete symbols. After the initial release, several individuals offered suggestions or requests for enhancements and new features and/or provided assistance for making SYMBOL the product it is today. Some of these individuals, groups, etc. deserve the following special mention. o Eric M. LaFranchi. Eric suggested that a display capability, in addition to SYMBOL's original set and delete funtionality, should be added. Eric's series of articles (co-authored with Kathleen D. Morse of Digital Equipment Corp.) on OpenVMS Alpha migration were an integral part of Eric's insistance that I get SYMBOL ported to Alpha. o Hunter Goatley, friend and ex-colleague. Hunter's suggestions led to the command interface which SYMBOL currently employs. Hunter also made the first Alpha port a reality. Hunter provided me with the Alpha in the Fall of 1993 which I used for SYMBOL's Alpha port and development of the execlet approach for placing SYMBOL's various routines into system space. o Jon Pinkley. I can't begin to account for all of the suggestions Jon has provided for SYMBOL. Jon's many suggestions for enhanced functionality in SYMBOL have been invaluable to this project. I am extremely grateful for his many ideas. I hope you will be too. Much of the current release of SYMBOL (Ref: V3.1 %6.350) exists because of Jon's suggestions for the procedure level symbol control. Jon also alerted me to the nasty little R11 bug -- fixed ACKNOWLEDGEMENTS Page E-2 Special Recognition 24 May 1997 in the %6.294 release. Jon's thorough testing in the pre-beta phase helped to correct many of the issues detailed in the above sections. o Jess C. Goodman. Jess suggested some modifications for the treatment of abbreviated symbols with SYMBOL/SHOW and SYMBOL/DELETE functions. SYMBOL now behaves more like DCL's "$ SHOW SYMBOL" and "$ DELETE/SYMBOL" when dealing with abbreviated symbol definitions. o Glenn C. Everhart (OpenVMS Engineering). For helping me with many issues concerning the changes to OpenVMS V7.0 and by helping me to navigate through OpenVMS engineering to get several of my questions answered; particularly, the LCKPAG issue described below. Also, for stress testing SYMBOL's new Direct Cross-Process Copying mechanism. o David F. Wall (OpenVMS Engineering). For his elegant and concise answer to my questions on the behavior of the privatized OpenVMS V7.0 process page tables when the process's pages are locked via a LCKPAG system service. His answer helped assure me that my new "cross-process" copy technique was sound. o Digital Equipment Corp. Thanks for the OpenVMS operating system. o Digital Equipment Corp. Thanks for my OpenVMS Source Listings. APPENDIX F SAMPLE SYMBOL INSTALLATION F.1 VMSINSTAL of SYMBOL V4.0 This appendix contains a log of an installation of TMESIS SYMBOL V4.0. $ VMSINSTAL :== SPAWN @SYS$UPDATE:VMSINSTAL $ VMSINSTAL OpenVMS VAX Software Product Installation Procedure V7.1 It is 27-MAR-1997 at 20:17. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? * Where will the distribution volumes be mounted: SYS$SYSDEVICE:[KITS] Enter the products to be processed from the first distribution volume set. * Products: SYMBOL The following products will be processed: SYMBOL V4.0 Beginning installation of SYMBOL V4.0 at 20:18 %VMSINSTAL-I-RESTORE, Restoring product save set A ... TMESIS SYMBOL version V4.0 release %7.143 Installation Copyright © 1993, 1994, 1996, 1997 Brian Schenkenberger and TMESIS ALL RIGHTS RESERVED. * OpenVMS VAX version at time of installation is V7.1 %VMSINSTAL-I-RESTORE, Restoring product save set B ... * Kit saveset B supports OpenVMS VAX versions 6.0 through 7.1 * Do you want to purge files replaced by this installation [YES]? SAMPLE SYMBOL INSTALLATION Page F-2 VMSINSTAL of SYMBOL V4.0 24 May 1997 Enter device and directory where TMESIS SYMBOL V4.0 should be installed. * Default [SYS$SYSDEVICE:[SYMBOL]]: %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$SYSDEVICE:[SYMBOL]. %CREATE-I-EXISTS, SYS$SYSDEVICE:[SYMBOL] already exists * No further questions will be asked during this installation. ******************************************************************* ** Add the following to your system's site specific startup file ** ** to define the SYMBOL logical names, install support shareable ** ** images and load the SYMBOL support loadable executive image. ** ******************************************************************* $ @SYS$SYSDEVICE:[SYMBOL]INSTALL_SYMBOL.COM ******************************************************************* ** For further information regarding SYMBOL and its usage, refer ** ** to the information file in the directory created for SYMBOL's ** ** product executables, help library and command definition file.** ******************************************************************* %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of SYMBOL V4.0 completed at 20:19 Enter the products to be processed from the next distribution volume set. * Products: EXIT VMSINSTAL procedure done at 20:19 $ LOGOUT SYSTEM logged out at 27-MAR-1997 20:19:26.42 APPENDIX G FEEDBACK AND CONTACT G.1 Contacting the Author SYMBOL has seen a great benefit from the feedback provided by the user community. If you have any suggestions, comments, problems, or issues concerning SYMBOL, please contact the author with the following e-mail address: VAXman@TMESIS.COM Thank you.