Marc's Place

1 Symbol_Assign
  Defines a symbolic name for a character string or integer value.

  Format:

    symbol-name =[=] expression

  symbol-name[bit-position,size] =[=] replacement-expression


2 Parameters

 symbol-name

  Defines a 1- through 255-character alphanumeric string name for  the
  symbol.   The  symbol  name  must begin with an alphabetic character
  (uppercase and lowercase characters are equivalent), an  underscore,
  or  a  dollar sign.  After the first character, the name can contain
  any alphanumeric characters from  the  DEC  multinational  character
  set, underscores, or dollar signs.

  If you specify a single equal sign (=) in the assignment  statement,
  the  symbol name is placed in the local symbol table for the current
  command level.

  If you specify double equal signs (==) in the assignment  statement,
  the symbol name is placed in the global symbol table.

 expression

  Specifies  the  value  on  the  right-hand  side  of  an  assignment
  statement.   An  expression can consist of a character string value,
  an  integer  value,  a  symbol  name,  a  lexical  function,  or   a
  combination  of these entities.  The components of an expression are
  evaluated, and the result is assigned to a symbol.

  All literal character strings must be enclosed in  quotation  marks.
  If  you  specify  an  expression  containing  a  symbol, the command
  interpreter uses the symbol's value in evaluating the expression.

  The result of expression evaluation is either a character string  or
  an  integer  value.   The data type of a symbol is determined by the
  data type of the expression.   If  the  expression  evaluates  to  a
  string,  the  symbol  is assigned a string value.  If the expression
  evaluates to an integer, the symbol is assigned an integer value.

  For a summary of operators used in expressions, details  on  how  to
  specify  expressions,  and details on how expressions are evaluated,
  see the Open VMS Users Manual.

  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.

 [bit-position,size]

  Specifies that a binary overlay is to be  inserted  in  the  current
  32-bit  value  of  a symbol-name.  This type of assignment statement
  evaluates the current value of  the  symbol-name  and  replaces  the
  specified    number    of    bits    with    the   result   of   the
  replacement-expression.

  The bit-position is the location relative to  bit  0  at  which  the
  overlay  is  to  occur.  If the symbol that you are overlaying is an
  integer, then the bit position must be less than 32.  Also, the  sum
  of the bit position and the size must be less than or equal to 32.

  If the symbol you are overlaying is a string, then the bit  position
  must be less than 6152.  Because each character is represented using
  8 bits, you can begin an overlay at any character through the 768th.
  (The  768th  character  starts in bit position 6144.) The sum of the
  bit position and the size must be less than or equal to 6152.

  The size is the number of bits to be overlaid.   If  you  specify  a
  size that is greater than 32, then DCL reduces the size to 32.

  The square brackets are required notation;  no  spaces  are  allowed
  between  the  symbol  name and the left bracket.  Specify values for
  bit-position and size as integer expressions.

 replacement-expression

  Specifies the value that is used  to  overlay  the  symbol  you  are
  modifying.    Specify   the  replacement-expression  as  an  integer
  expression.

  If   the   symbol   you   are   modifying   is   an   integer,   the
  replacement-expression  defines  a  bit pattern which is overlaid on
  the value assigned to the symbol.  If the symbol you  are  modifying
  is  a  character  string,  the  result of the replacement-expression
  defines a bit pattern which is overlaid on the specified bits of the
  character string.  If the symbol you are modifying is undefined, the
  result of the replacement-expression is overlaid on a null string.


2 Examples

  1.   $ LIST == "DIRECTORY"
       $ TIME == "SHOW TIME"
       $ QP == "SHOW QUEUE/DEVICE"
       $ SS == "SHOW SYMBOL"

  The file  SYNONYM.COM  contains  the  assignment  statements  shown;
  these  are user-defined synonyms for commands.  Execute this command
  procedure as follows:

       $ @SYNONYM

  After the command procedure creates the global  symbol  definitions,
  you   can  use  these  synonyms  (LIST,  TIME,  QP,and  SS)  at  the
  interactive command level.  Note that the  assignments  are  global;
  otherwise,  the  symbol names would have been deleted after the file
  SYNONYM.COM completed execution.

  2.   $ COUNT = 0
       $ LOOP:  
       $      COUNT = COUNT + 1
               .
               .
               .

       $      IF COUNT .LT.5 THEN GOTO LOOP

  The symbol COUNT is initially assigned a numeric value of 0;  a loop
  is  established  to  increment the value of COUNT by 1 each time the
  loop is entered.  Note that when the symbol name  COUNT  appears  on
  the  right-hand  side  of  an  arithmetic  assignment statement, the
  command interpreter automatically substitutes its current value.

  The IF command tests the value of COUNT;  if it is less than 5,  the
  procedure  branches to the label LOOP and the statements between the
  label LOOP through the IF command  are  executed  again.   When  the
  value  of the symbol count reaches 5, the loop is not executed again
  and the command following the IF command is executed.

  3.   $ A = 25
       $ CODE = 4 + F$INTEGER("6") - A
       $ SHOW SYMBOL CODE
         CODE = -15   HEX = FFFFFFF1   Octal = 1777761

  This  example  contains  two  assignment  statements.    The   first
  statement  assigns  the  value  25  to  the  symbol  A.   The second
  assignment statement evaluates an expression containing  an  integer
  (4),  a  lexical  function  (F$INTEGER("6")), and the symbol A.  The
  result of the expression, -15, is assigned to the symbol CODE.


2 String_Assign

  Defines a symbolic name for a character string value.

  Format:

    symbol-name :=[=] string

  symbol-name[offset,size] :=[=] replacement-string


3 Parameters

 symbol-name

  Defines a 1- through 255-character string name for the symbol.   The
  symbol  name  must begin with an alphabetic character (uppercase and
  lowercase characters are equivalent), an  underscore,  or  a  dollar
  sign.    After  the  first  character,  the  name  can  contain  any
  alphanumeric characters from the DEC  Multinational  Character  Set,
  underscores, or dollar signs.

  If you specify a single equal sign (:=) in the assignment statement,
  the  symbol name is placed in the local symbol table for the current
  command level.

  If you specify double equal signs (:==) in the assignment statement,
  the symbol name is placed in the global symbol table.

 string

  Specifies a character string value to be equated to the symbol.  The
  string can contain any alphanumeric or special characters.  DCL uses
  a buffer that is  1024  bytes  long  to  hold  a  string  assignment
  statement, Therefore, the length of the symbol name, the string, and
  any  symbol  substitution  within  the  string  cannot  exceed  1024
  characters.

  With the := string assignment statement, you do not need to  enclose
  a   string   literal   in   quotation   marks.   String  values  are
  automatically  converted  to  uppercase.   Also,  any  leading   and
  trailing  spaces  and tabs are removed, and multiple spaces and tabs
  between characters are compressed to a single space.

  Note that, in general, it is easier to use the assignment  statement
  (=)  to create symbols with string values.  The assignment statement
  does not automatically capitalize and remove  extra  spaces.   Also,
  the assignment  statement  allows  you  to perform string operations
  in expressions.

  If you want to prohibit uppercase  conversion  and  retain  required
  space and tab characters in a string, you must place quotation marks
  around the string.  To use quotation marks in a string, enclose  the
  entire  string  in quotation marks and use a double set of quotation
  marks within the string.  For example:

       $ TEST := "this     is a ""test"" string"
       $ SHOW SYMBOL TEST
         TEST = "this     is a "test" string"

  In this example, the spaces, lowercase letters, and quotation  marks
  are preserved in the symbol definition.

  You can continue a symbol assignment on more than one line by  using
  the hyphen as a continuation character.  For example:

       $ LONG_STRING := THIS_IS_A_VERY_LONG-
       _$ _SYMBOL_STRING

  To assign a null string to a  symbol  using  the  string  assignment
  statement, do not specify a string.  For example:

       $ NULL := 

  Specify the string as a string literal, or as a  symbol  or  lexical
  function which evaluates to a string literal.  If you use symbols or
  lexical functions, place apostrophes around them to  request  symbol
  substitution.  

  You can also use the string assignment statement to define a foreign
  command.   See the OpenVMS Users Manual for more  information  on
  symbol substitution and foreign commands.

 [offset,size]

  Specifies that a portion of a symbol value is to be overlaid with  a
  replacement  string.   This  form of the string assignment statement
  evaluates the value assigned to a symbol-name and then replaces  the
  portion  of  the  value  (defined  by  the offset and size) with the
  replacement string.  The square brackets are required notation,  and
  no spaces are allowed between the symbol name and the left bracket.

  The  offset  specifies  the  character  position  relative  to   the
  beginning  of the symbol-name's string value at which replacement is
  to begin.  Offset values start at 0.

  If the offset is greater than the offset of the  last  character  in
  the string you are modifying, spaces are inserted between the end of
  the string and the offset where the  replacement  string  is  added.
  The maximum offset value you can specify is 768.

  The size specifies the number of characters to replace.  Size values
  start at 1.

  Specify the offset and size as  integer  expressions. See the  
  OpenVMS Users Manual for more information on integer expressions. 
  The value of the size plus  the offset must not exceed 769.

 replacement-string

  Specifies the string that is used to  overlay  the  string  you  are
  modifying.   If  the  replacement-string  is  shorter  than the size
  argument, the replacement string is blank-filled on the right  until
  it  equals  the specified size.  Then the replacement string is used
  to  overlay  the  string  assigned  to  the  symbol-name.   If   the
  replacement  string  is  longer  than  the  size  argument, then the
  replacement string is truncated on the right to the specified size.

  You can specify the replacement-string as a string literal, or as  a
  symbol  or lexical function which evaluates to a string literal.  If
  you use symbols or lexical functions, place apostrophes around  them
  to  request  symbol  substitution.   See the Open VMS Users Manual
  for more information  on  symbol substitution.

3 Examples

  1.   $ TIME := SHOW TIME
       $ TIME
         15-APR-1987 11:55:44

  The symbol TIME is equated to the command string SHOW TIME.  Because
  the  symbol  name appears as the first word in a command string, the
  command interpreter automatically substitutes  it  with  its  string
  value and executes the command SHOW TIME.

  2.   $ STAT := $DBA1:[CRAMER]STAT
       $ STAT

  This example shows how to define STAT as  a  foreign  command.   The
  symbol  STAT  is  equated to a string that begins with a dollar sign
  followed by a file specification.  The command  interpreter  assumes
  that the file specification is that of an executable image, that is,
  a file with a file type of EXE.   Thus,  the  symbol  STAT  in  this
  example becomes a synonym for the command:

       $ RUN DBA1:[CRAMER]STAT.EXE

  When you subsequently type STAT, the  command  interpreter  executes
  the image.

  3.   $ A = "this is a big     space."
       $ SHOW SYMBOL A
         A = "this is a big     space."
       $ B := 'A'
       $ SHOW SYMBOL B
         B = "THIS IS A BIG SPACE."

  This example compares  the  assignment  and  the  string  assignment
  statements.  The symbol A is defined using the assignment statement,
  so lowercase letters and multiple spaces are retained.  The symbol B
  is  defined  using  the  string assignment statement.  Note that the
  apostrophes are required;  otherwise, the symbol name B  would  have
  been  equated  to  the  literal  string A.  However, when symbol A's
  value is  assigned  to  symbol  B,  the  letters  are  converted  to
  uppercase and multiple spaces are compressed.
Software development, photography, jokes, ....

Sites by me

Hosting Favorites

Blogroll

Marc's Place

1 Symbol_Assign
