EQUATE subcommand — create a symbol

The EQUATE subcommand allows you to:
  • Create a symbol in the symbol table and to associate an address and storage attributes with the symbol
  • Change the attributes of a symbol that is already defined in the symbol table
  • Create storage map entries
  • Set X, the current address, to a specific address

The symbol is in a symbol table that is part of a source description. The source description is in the dump directory allocated with ddname IPCSDDIR and is your current dump directory. The current dump directory is your user dump directory or, for users with write access authority, might be the sysplex dump directory.

On the EQUATE subcommand, specify the name of the symbol followed by any address and other storage attributes that you want associated with the symbol. If the specified symbol already exists in the symbol table, the new address and storage attributes overlay the previous address and storage attributes.

Note: Because the EQUATE subcommand can be used either to create a new symbol or redefine an existing symbol, it can be used to create a symbol for a system control block that has failed the validity check during IPCS processing.
See the z/OS MVS IPCS User's Guide for information about maintaining symbol tables and storage map entries and about creating and validating your own symbol definitions.
  • Related subcommands
    • DROPSYM
    • LISTSYM
    • RENUM
    • STACK
  • Syntax 
      { EQUATE }    [ symbol | X ]    [ data-descr | X ]
  { EQU    }
  { EQ     }    [ DROP | NODROP ]

    -------- SETDEF-Defined Parameter --------------------------
    Note: You can override the following SETDEF parameter.
    See
    SETDEF subcommand — set defaults.

                    [ TEST | NOTEST ]
  • Parameters
    symbol or X
    Specifies the symbol being defined. The symbol name is 1 through 31 alphanumeric characters; the first character must be a letter or one of the following characters: 
    $  (X'5B')
#  (X'7B')
@  (X'7C')

    If you omit this parameter, the default is X, which is the most recently accessed address.

    data-descr or X
    Specifies the address and attributes to be associated with the symbol being defined through the data description parameter. The data description parameter consists of five parts:
    • An address (required when data-descr is explicitly specified on the subcommand)
    • Address processing parameters (optional)
    • An attribute parameter (optional)
    • Array parameters (optional)
    • A remark parameter (optional)
    Data description parameter explains the use and syntax of the data description parameter.

    If you omit this parameter, the default is X, which is the most recently accessed address.

    DROP or NODROP
    Specifies how the DROPSYM subcommand can delete the symbol.

    DROP specifies that the symbol can be deleted from the symbol table by the DROPSYM subcommand without using the PURGE parameter.

    NODROP specifies that the symbol not be deleted from the symbol table by the DROPSYM subcommand. This can be overridden by the PURGE parameter on the DROPSYM subcommand.

  • Return Codes

    See Standard subcommand return codes for a description of the return codes produced by the EQUATE subcommand.

  • Example 1: Define a symbol for a TCB that caused a dump.
    • Action 
      equate failingtcb 51368. length(360) +
  x remark('tcb that caused the dump')
    • Result

      This subcommand defines FAILINGTCB at address X'51368'. It is identified as a TCB, and its size is 360 bytes (decimal). If the TCB is displayed or printed, it is in hexadecimal format. Because the NODROP parameter is not specified, this name can be deleted from the symbol table.

  • Example 2: Define a symbol table entry at the current address.
    • Action 
      equate jstcb
    • Result

      This subcommand creates a symbol table entry for JSTCB. By default, the address and attributes associated with JSTCB are those associated with X, which is the current address.

  • Example 3: Set X to a specific address.
    • Action 
      equate x 522836
    • Result

      This sets X to address X'522836'.

  • Example 4: Define a symbol, then change its attributes.
    • Action 
      equate buffer1 55280. length(80) asid(3) drop
equate buffer1 buffer1 nodrop cpu(2)
    • Result

      The first EQUATE creates the symbol BUFFER1 and gives it certain attributes. The second EQUATE changes the DROP attribute to NODROP and specifies a central processor in the CPU parameter. You can change the attributes of any symbol in the symbol table whether you created it or whether IPCS subcommands created it for you.

  • Example 5:
    • Action 
      setdef length(x'0F00')
equate nick 10000. structure(nick) length(x'1000'
      NICK is not a recognized structure by IPCS.
    • Result

      EQUATE creates a storage map entry at x'10000' but is unable to locate a formatter for NICK. The entry is created with the SETDEF length of X'0F00'. A symbol table entry is then created for symbol nick at X'10000' using the defined length parameter x'1000'.

Parent topic: IPCS subcommands