Qualifying variables

Qualification is a method you can use to specify to what procedure or load module a particular variable belongs. You do this by prefacing the variable with the block, compile unit, and load module (or as many of these labels as are necessary), separating each label with a colon (or double colon following the load module specification) and a greater-than sign (:>), as follows: 
load_name::>cu_name:>block_name:>object
This procedure, known as explicit qualification, lets z/OS® Debugger know precisely where the variable is.

If required, load_name is the load module name. It is required only when the program consists of multiple load modules and when you want to change the qualification to other than the current load module. load_name can be the z/OS Debugger variable %LOAD.

If required, cu_name is the compile unit name. The cu_name is required only when you want to change the qualification to other than the currently qualified compile unit. cu_name can be the z/OS Debugger variable %CU.

If required, block_name is the program block name. The block_name is required only when you want to change the qualification to other than the currently qualified block. block_name can be the z/OS Debugger variable %BLOCK.

For PL/I only:
  • In PL/I, the primary entry name of the external procedure is the same as the compile unit name. When qualifying to the external procedure, the procedure name of the top procedure in a compile unit fully qualifies the block. Specifying both the compile unit and block name results in an error. For example: 
    LM::>PROC1:>variable
    is valid. 
    LM::>PROC1:>PROC1:>variable
    is not valid.
For C++ only:
  • You must specify the full function qualification including formal parameters where they exist. For example:
    1. For function (or block) ICCD2263() declared as void ICCD2263(void) within CU "USERID.SOURCE.LISTING(ICCD226)" the correct block specification for C++ would include the parenthesis () as follows: 
      qualify block %load::>"USERID.SOURCE.LISTING(ICCD226)":>ICCD2263()
    2. For CU ICCD0320() declared as int ICCD0320(signed long int SVAR1, signed long int SVAR2) the correct qualification for AT ENTRY is: 
      AT ENTRY "USERID.SOURCE.LISTING(ICCD0320)":>ICCD0320(long,long)

      Use the z/OS Debugger command DESCRIBE CUS to give you the correct BLOCK or CU qualification needed.

      Use the LIST NAMES command to show all polymorphic functions of a given name. For the example above, LIST NAMES "ICCD0320*" would list all polymorphic functions called ICCD0320.

You do not have to preface variables in the currently executing compile unit. These are already known to z/OS Debugger; in other words, they are implicitly qualified.

In order for attempts at qualifying a variable to work, each block must have a name. Blocks that have not received a name are named by z/OS Debugger, using the form: %BLOCKnnn, where nnn is a number that relates to the position of the block in the program. To find out the name of z/OS Debugger for the current block, use the DESCRIBE PROGRAMS command.

Refer to the following topics for more information related to the material discussed in this topic.