.nfl accept .nfl bold .fl space .lm 0 .rm 78 !Copyright © 1993, 1994 by Brian Schenkenberger and TMESIS Consulting .rm 72 .br .b 1 SYMBOL .lm 1 .br SYMBOL provides the capability to define, display and delete DCL symbols in the context of any process in a VAXcluster. SYMBOL can be used by any user in the VMScluster to define, display, or delete symbols in their own symbol table or in the symbol table of any process in the VMScluster. Privileges are require to affect any process which the user does not own or have rights to access. .b 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. .b Format .b .lm 3 SYMBOL#/qualifiers##parameters .lm 0 .rm 70 .br 2 Parameters .lm 1 .br The SYMBOL command performs entirely different functions based upon the qualifiers used with the verb. The command may require none, one, or two parameters to be specified, depending on the /QUALIFIER(S) specified with the command verb. .lm 0 .rm 68 .br 3 symbol-name .lm 1 .br Specifies a string of 1 to 255 characters for the symbol name. The name can contain any alphanumeric characters from the DEC Multinational Character Set, the underscore (_), and the dollar sign ($). However, the name must begin only with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. .b The symbol-name parameter must be specified when creating and removing symbols in the context of the target process. .lm 0 .rm 68 .br 3 equivalence-string .lm 1 .br This parameter can consist of any character string, a numerical constant, a lexical function, or a combination of these entities. The components of the expression are assigned to the symbol. Any literal character strings inside the expression must be enclosed in double-quotation marks ("" ""). .b The result of expression evaluation will be a character string. .b DCL uses a buffer that is 1024 bytes long to hold an assignment statement and to evaluate the expression. The length of the symbol name, the expression, and the expression's calculations cannot exceed 1024 bytes. .b The equivalence-name parameter must be specified when creating a symbol in the context of the target process. It is not used when removing or displaying symbol definitions. .lm 0 .rm 68 .br 3 numerical-value .lm 1 .br This parameter can consist of any numerical constant. The integer value is assigned to the symbol. The value, by default, is expressed in decimal. Hexadecimal values must be prefixed with %X. Octal values must be prefixed with %O. .b The numerical-value name parameter must be specified when creating a binary symbol in the context of the target process. It is not used when removing or displaying symbol definitions. .lm 0 .rm 68 .br 3 match-pattern .lm 1 .br Specifies a string of 1 to 255 characters which will be used as display criteria when displaying the contents of a symbol table. The pattern can contain any alphanumeric characters from the DEC Multinational Character Set, the underscore (_), the dollar sign ($) and any standard VMS wildcard characters (* and %). Symbols which are displayed will match the pattern specified. .b The optional match-pattern parameter can be specified when displaying the symbols of the target process. If a match pattern is omitted, all the symbols are displayed. .lm 0 .rm 70 .br 2 Qualifiers .lm 1 .br The SYMBOL command performs entirely different functions based on the qualifiers used with the verb. The command must specify the process Id using the /IDENTIFICATION qualifier. All of the other qualifiers are either optional or, are used to select the specific function of the SYMBOL command. .lm 0 .rm 68 .br 3 /BINARY .lm 1 .br /BINARY .b Specifies that you are using the SYMBOL command to create an integer symbol definition in the context of the target process. This qualifiers can only be used with and must be specified after the /SET qualifier. .b The default action of the SYMBOL command is to create a string symbol. .lm 0 .rm 68 .br 3 /DELETE .lm 1 .br /DELETE .b Specifies that you are using the SYMBOL command to remove a symbol definition in the context of the target process specified with the required /IDENTIFICATION qualifier. .b This qualifier is a positional qualifier. It must appear in the command before other qualifiers such as: /IDENTIFICATION and /LOCAL. .lm 0 .rm 68 .br 3 /GLOBAL .lm 1 .br /GLOBAL .b Specifies that you are using the SYMBOL command to create or remove a global symbol definition in the context of the target process or, to display the global symbols of the target process. If a symbol is a global symbol then, you may omit this qualifier. .b This is the default action of the SYMBOL command. .lm 0 .rm 68 .br 3 /IDENTIFICATION .lm 1 .br /IDENTIFICATION=pid .b Specifies the system-assigned process identification (PID) code. When a process is created a unique PID is assigned to the process. Use the PID of the target in question to specify the process. .b This qualifier is an optional qualifier. If it is omitted ot the PID is specified as zero (0), the current process id is used. You can omit any leading zeros in specifying the PID code. .lm 0 .rm 68 .br 3 /LOCAL .lm 1 .br /LOCAL .b Specifies that you are using the SYMBOL command to create or remove a local symbol definition in the context of the target process or, to display the local symbols of the target process. If a symbol is a local symbol then, you must specify this qualifier. .lm 0 .rm 68 .br 3 /SET .lm 1 .br /SET .b Specifies that you are using the SYMBOL command to create a symbol definition in the context of the target process specified with the required /IDENTIFICATION qualifier. .b This qualifier is a positional qualifier. It must appear in the command before other qualifiers such as: /IDENTIFICATION, /LOCAL and /BINARY. .lm 0 .rm 68 .br 3 /SHOW .lm 1 .br /SHOW .b Specifies that you are using the SYMBOL command to display symbol definitions of the target process specified with the required /IDENTIFICATION qualifier. This is the default action of the SYMBOL command and may be omitted from the command line. .b This qualifier is a positional qualifier. It must appear in the command before other qualifiers such as: /IDENTIFICATION and /LOCAL. .lm 0 .rm 70 .br 2 Examples .lm 1 .b .lm 1 1. $ SYMBOL/SHOW/ID=4F *MOD* .b The SYMBOL command in this example will display the symbols in the process specified by the ID=4F which match the match pattern of *MOD*. .b 3 2. $ SYMBOL/SET/IDENT=309 LO*GOUT LOGOUT/FULL .b The SYMBOL command in this example is defining the abbreviated global symbol LO*GOUT to be LOGOUT/FULL for the process with pid=309. .b 3 3. $ SYMBOL/DELETE/GLOBAL/ID=40401A94 GREP .b The SYMBOL command in this example deletes the global symbol GREP which should never have been defined in the context of the remote VMS process with the pid=40401A94. .b 3 4. $ SYMBOL/SET/LOCAL/ID=4F TIME WRITE SYS$OUTPUT "''F$TIME()'" .b The SYMBOL command in this example is defining the local symbol TIME to be WRITE SYS$OUTPUT "''F$TIME()'" for the process with pid=4F. The SYMBOL command associates all text from the end of the symbol-name parameter string through the end of the command line with the equivalence-name parameter string. Therefore, there is no need to enclose the string in quotation marks ("#"). If quotation marks are used, they will be assigned to the symbol along with the rest of the equivalence-name string. .b 3 5. $ SYMBOL/SET/BINARY DOSIQ 0 .b The SYMBOL command in this example is defining integer symbol DOSIQ to be 0. In this case, the /IDENTIFICATION qualifier was omitted; therefore, the symbol will be defined in the current process. .lm 0 .rm 70 .br 2 Return_Errors .lm 1 .br The following lists common system errors which may be returned when using the SYMBOL command. The cause for the error and any possible recovery procedures and/or corrective actions are described in each error message sub-topic. .lm 0 .rm 68 .br 3 ABSYMD .lm 1 .br .nofill %DCL-W-ABSYMD,#abbreviated#symbol#definition#conflict#- ###############rename symbol .fill .b The SYMBOL/SET command specified a symbol name which is not unique and is in conflict with an existing abbreviated symbol definition. .b Change the name of the symbol and/or check the symbol spelling. .lm 0 .rm 68 .br 3 BADACTRL .lm 1 .br %SYMBOL-E-BADACTRL,#remote#access#control#info#invalid .b The SYMBOL command specified the process id of a process on a remote node in the cluster and the issue of the command is not authorized on the target node. .b Check that specified PID represents an active process on an authorized node. .lm 0 .rm 68 .br 3 BADPARAM .lm 1 .br %SYMBOL-F-BADPARAM,#bad#parameter#value .b The symbol name specified with the SYMBOL command does not conform with the accepted format for formulating symbol names. The symbol name may contain one or more of the following unacceptable ASCII characters. .b .literal (null) ! " # ( ) + , - . / ; < > ? @ [ ] ^ .end literal .b Correct the symbol to conform with the conventions. .lm 0 .rm 68 .br 3 EXPSYN .lm 1 .br .nofill %SYMBOL-W-EXPSYN,#invalid#expression#syntax#- ##################check#operators#and#operands .fill .b The SYMBOL/SET/BINARY command specified an expression syntax which can not be evaluated or the expression contained an undefined local symbol. .b Use a valid numeric expression, correct the spelling of any symbols used in the expression statement or define any undefined symbols used in the expression with a numeric value in the local process. .lm 0 .rm 68 .br 3 INPCONERR .lm 1 .br %SYMBOL-F-INPCONERR,#input#conversion#error .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier is not a valid hexadecimal value. .b Check that valid hexadecimal digits have been specified for the PID. .lm 0 .rm 68 .br 3 INSFMEM .lm 1 .br %SYMBOL-F-INSFMEM,#insufficient#dynamic#memory .b There is insufficient free nonpaged memory available to complete the operation. The most probable cause for this error is insufficient contiguous nonpaged memory available to hold the target process's symbol table. The command SHOW MEMORY/POOL/FULL can be used to verify this condition. .b If there is insufficient contiguous nonpaged memory, increase the sysgen parameters NPAGEDYN and NPAGEVIR to accomodate, at a minimum, the maximum size of a process's symbol table which is 256000 (512*500) bytes. .lm 0 .rm 68 .br 3 IVCHAR .lm 1 .br .nofill %SYMBOL-W-IVCHAR,#invalid#numeric#value#- ##################check#for#invalid#digits .fill .b The SYMBOL/SET/BINARY command specified an illegal character in the numeric value. .b Check that valid digits have been specified for the radix operand specifier being used. .lm 0 .rm 68 .br 3 IVQUAL .lm 1 .br .nofill %SYMBOL-W-IVQUAL,#unrecognized#qualifier#- ##################check#validity,#spelling,#and#placement .fill .b An illegal qualifier was specified with the SYMBOL command or the spelling of the qualifier is incorrect. .b Check the usage and correct the spelling of any qualifiers used. .lm 0 .rm 68 .br 3 IVSYMB .lm 1 .br .nofill %SYMBOL-W-IVSYMB,#invalid#symbol#name#- ##################start#name#with#an#alphabetic#character .fill .b The symbol name specified with the SYMBOL command does not comform with the accepted format for formulating symbol names. Symbols must start with an alphabetic character, an underscore (_), or the dollar ($). .b Correct the symbol to conform with the conventions. .lm 0 .rm 68 .br 3 NOCLI .lm 1 .br %SYMBOL-F-NOCLI,#no#CLI#present#to#perform#function .b The target process does not have the DCL CLI mapped or it is an image running in a detached process which has no symbol table. .lm 0 .rm 68 .br 3 NOGROUP .lm 1 .br %SYMBOL-F-NOGROUP,#operation#requires#GROUP#privilege .b The current process attempted to use SYMBOL and specified the PID of a process in the same group without having the GROUP privilege. .lm 0 .rm 68 .br 3 NONEXPR .lm 1 .br %SYMBOL-W-NONEXPR,#nonexistent#process .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier does not represent a valid active process on the system. .b Check that specified PID represents an active process. .lm 0 .rm 68 .br 3 NONXPAG .lm 1 .br %SYSTEM-E-NONXPAG,#non-existent#page .b The SYMBOL command was issued but the supporting loadable executive image, SYS$LOADABLE_IMAGES:SYMBOL$AST_LEI.EXE, has not been loaded. .b Load SYS$LOADABLE_IMAGES:SYMBOL$AST_LEI.EXE using SYMLOADER.EXE. .lm 0 .rm 68 .br 3 NOSERVER .lm 1 .br %SYMBOL-E-NOSERVER,#SMI#Server#not#running#in#target#node .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier specified a process on a remote member of the VAXcluster which is not currently running the SMISERVER process. .b Check that the SMISERVER is running and, if necessary, restart it. .lm 0 .rm 68 .br 3 NOSUCHNODE .lm 1 .br %SYMBOL-F-NOSUCHNODE,#remote#node#is#unknown .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier does not represent a process on a valid active member of the VAXcluster. .b Check that specified PID represents an active process. .lm 0 .rm 68 .br .!3 NOTIMP .!.!.lm 1 .!.br .!%SYMBOL-F-NOTIMP,#not#implemented .!.b .!The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier .!does not represent a valid active process on an OpenVMS VAX system. .!SYMBOL currently supports only VAX systems in the cluster. Support for OpenVMS .!AXP systems is forthcoming. .!.b .!Check that specified PID represents an active process a VAX system. .!.lm 0 .!.rm 68 .!.br 3 NOTMPMBX .lm 1 .br %SYMBOL-F-NOTMPMBX,#operation#requires#TMPMBX#privilege .b The current process attempted to use SYMBOL and specified the PID of a process on a remote node without having the TMPMBX privilege. .lm 0 .rm 68 .br 3 NOWORLD .lm 1 .br %SYMBOL-F-NOWORLD,#operation#requires#WORLD#privilege .b The current process attempted to use SYMBOL and specified the PID of a process outside its group without having the WORLD privilege. .lm 0 .rm 68 .br 3 SUSPENDED .lm 1 .br %SYMBOL-F-SUSPENDED,#process#is#suspended .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier specified a process which is suspended. .lm 0 .rm 68 .br 3 TIMEOUT .lm 1 .br %SYMBOL-E-TIMEOUT,#remote#operation#has#timed#out .b The process id (PID) specified with the SYMBOL/IDENTIFICATION qualifier specified a process on a remote member of the VAXcluster and the request to that remote node timed out. .lm 0 .rm 68 .br 3 UNDSYM .lm 1 .br .nofill %DCL-W-UNDSYM,#undefined#symbol#-#check#validity#and#spelling .fill .b The SYMBOL/DELETE command specified a symbol name which does not exists. .b Change the name of the symbol and/or check the symbol spelling. .lm 0 .rm 70 .br 2 Version .lm 1 .br SYMBOL#version#v3%4.091 .br Copyright#©#1993,#1994#by#Brian#Schenkenberger#and#TMESIS#Consulting