DESCRIBE command

The DESCRIBE command displays the file allocations or attributes of references, compile units, known load modules, the run-time environment, and CICS® channels and containers.

Read syntax diagramSkip visual syntax diagramDESCRIBE CURSORALLOCATIONSUSERALLSYSTEMLINKLISTLPALISTAPFLISTCATALOGPARMLIBPROCLIBATTRIBUTESreference'reference'(,reference'reference')*CHANNEL*channel_nameSOAPCUSPROGRAMScu_spec(,cu_spec)*ENVIRONMENTLOADMODS*load_spec(,load_spec) ;
CURSOR (Full-Screen Mode only)
Provides a cursor-controlled method for describing variables, structures, and arrays. If you have assigned DESCRIBE to a PF key, you can display the attributes of a selected variable by positioning the cursor at that variable and pressing the assigned PF key.
ALLOCATIONS
Lists the current file allocations.
USER
Indicates that files allocated in the user's address space are to be described.
ALL
Indicates that both USER and SYSTEM allocations are to be described.
SYSTEM
Indicates that all of the following allocations are to be described.
LINKLIST
Indicates that the current LINKLIB, JOBLIB, STEPLIB, and TASKLIB allocations are to be described.
LPALIST
Indicates that the current LPA list is to be described.
APFLIST
Indicates that the current list of APF authorized data sets is to be described.
CATALOG
Indicates that the current list of active catalogs is to be described.
PARMLIB
Indicates that the current PARMLIB concatenation is to be described.
PROCLIB
Indicates that the current PROCLIB concatenation is to be described.
ATTRIBUTES
Displays the attributes of a specified variable or, in C and C++, an expression. The attributes are ordinarily those that appeared in the declaration of a variable or are assumed because of the defaulting rules. DESCRIBE ATTRIBUTES works only for variables accessible to the current programming language. All variables in the currently qualified block are described if no operand is specified.
reference
A valid z/OS® Debugger reference in the current programming language. Note the following points:

In C and C++, this can be a valid expression. For a C and C++ expression, the type is the only attribute displayed. For a C and C++ structure or class, DESCRIBE ATTRIBUTES displays only the attributes of the structure or class. To display the attributes of a data object within a structure or data member in a class, use DESCRIBE ATTRIBUTES for the specific data object or member.

In COBOL, this can be any user-defined name appearing in the DATA DIVISION. Names can be subscripted or substringed per their definitions (that is, if they are defined as alphanumeric data or as arrays).

In PL/I, if the variable is in a structure, it can have inherited dimensions from a higher level parent. The inherited dimensions appear as if they have been part of the declaration of the variable.

In optimized COBOL programs, if reference refers to a variable that was discarded by the optimizer, the address information is replaced with a message.

'reference'
A valid z/OS Debugger LangX COBOL reference. This form must be used for LangX COBOL. It can contain a simple variable or a variable with IN or OF qualifications.
*
Describes all variables in the compile unit. The * is not supported for assembler, disassembly, PL/I, or LangX COBOL programs.
CHANNEL
Describes CICS channels and containers, including containers that hold Web services state data. You can specify one of the following suboptions:
channel_name
Describe all containers in the channel channel_name.
*
Describe all the containers in all the channels in the current scope.
SOAP
Describe all SOAP containers. SOAP is a synonym for DFHNODE.
If you do not specify a suboption, z/OS Debugger lists all of the containers in the current channel.
CUS
Describes the attributes of compile units, including such things as the compiler options and list of internal blocks. The information returned is dependent on the HLL that the compile unit was compiled under. CUS is equivalent to PROGRAMS.
cu_spec
The name of the compile unit whose attributes you want to list.
*
Describes all compile units.
PROGRAMS
Is equivalent to CUS.
ENVIRONMENT
The information returned includes a list of the currently opened files. Names of files that have been opened but are currently closed are excluded from the list. COBOL, LangX COBOL, assembler, and disassembly do not provide any information for DESCRIBE ENVIRONMENT.
LOADMODS
This command displays information about load modules known to z/OS Debugger and the known or potential CUs in these load modules.

If no operand is specified, the currently active load module is assumed.

*
Displays a list of all load modules known to z/OS Debugger along with the address, length, entry point, and the dataset from which the module was loaded.
load_spec
Display information about the specified load module or load modules and all known and potential CUs in these load modules. This CU information consists of CSECT name, address, length, and programming language.

Usage notes

  • For Enterprise COBOL for z/OS Version 5, the output of DESCRIBE ATTRUBUTES for RENAMES data items shows PIC X instead of AN-GR.
  • For Enterprise COBOL for z/OS Version 5, If two or more level 01 or 77 data items have the same name, DESCRIBE ATTRIBUTES with no operand displays an error message when you attempt to show the attributes of those data items.
  • For Enterprise COBOL for z/OS Version 5, the output of DESCRIBE ATTRIBUTES for a level 88 variable does not show an address.
  • If you use the DESCRIBE ATTRIBUTES command without specifying any data item, it shows the attributes of all data items defined in the currently qualified block. The output of this command is changed for Enterprise COBOL for z/OS Version 5 in the following ways:
    • For records, the output shows only the high-level attributes of the record, such as length and address. The output does not show the attributes of each subordinate group or data item defined within the record. This reduces the amount of the output produced. For Enterprise COBOL for z/OS Version 4, it also shows the attributes of all subordinate data items within each record or group, that is, the entire data hierarchy. To see this level of detail in Enterprise COBOL for z/OS Version 5, you can specify a particular data item on the DESCRIBE ATTRIBUTES command. If the data item is a record or group, it shows the attributes of all subordinate data items within that record or group.
    • For data items that are not records, which are scalar data items, the type of the data item is no longer displayed on a separate line in the output as it was in Enterprise COBOL for z/OS Version 4, but instead it is shown after the data item name on the line that includes "ATTRIBUTES for". This further reduces the number of lines of the output produced, and makes the output for scalar data items more consistent with the output for records.
  • You can use the DESCRIBE CUS, DESCRIBE CHANNEL, and DESCRIBE LOADMODS commands in remote debug mode.
  • The DESCRIBE ALLOCATIONS command is not available under CICS.
  • Cursor pointing can be used by typing the DESCRIBE CURSOR command on the command line and moving the cursor to a variable in the Source window before pressing Enter, or by moving the cursor and pressing a PF key with the DESCRIBE CURSOR command assigned to it.
  • When using the DESCRIBE CURSOR command for a variable that is located by the cursor position, the variable's name cannot be split across different lines of the source listing.
  • In C, C++, and COBOL, expressions containing parentheses () must be enclosed in another set of parentheses when used with the DESCRIBE ATTRIBUTES command. For example, DESCRIBE ATTRIBUTES ((x + y) ⁄ z);.
  • For COBOL, if DESCRIBE ATTRIBUTES * is specified and your compile unit is large, you might receive an out of storage error message.
  • For PL/I, DESCRIBE ATTRIBUTES returns only the top-level names for structures. DESCRIBE ATTRIBUTES * is not supported for PL/I. To get more detail, specify the structure name as the reference.
  • For Enterprise COBOL for z/OS Version 5, the PIC definition and other attributes of a variable are displayed as declared in the program.
  • For Enterprise COBOL for z/OS Version 5, the result of issuing DESCRIBE ATTRIBUTES for a z/OS Debugger variable that represents a register does not include an address. For example, DESCRIBE ATTRIBUTES %GPR15.
  • For Enterprise COBOL for z/OS Version 5, the output of DESCRIBE ATTRIBUTES for a record or a group variable is displayed with the levels as declared in the program.
  • LangX COBOL PIC attributes might not match the original PIC specification in the following situations:
    • A COMP-3 variable always has an odd number of digits in its PIC value.
    • All non-numerical strings have a PIC value of X's.
  • If the DATA option of the PLAYBACK ENABLE command is in effect for the current compile unit, the DESCRIBE ATTRIBUTES and DESCRIBE CURSOR commands can be used while you replay recorded statements by using the PLAYBACK commands.
  • The DESCRIBE ENVIRONMENT command cannot be used while you replay recorded statements by using the PLAYBACK commands.
  • The DESCRIBE LOADMODS command does not display information about load modules or compile units provided by operating system, subsystem, or runtime software (for example: MVS, CICS, Db2®, IMS, and Language Environment®) because z/OS Debugger ignores these modules.
  • The DESCRIBE LOADMODS command cannot display the DSNAME of load modules loaded by LPA, LLA, AOS loader, or an unknown provider because the DSNAME for these providers is not available.
  • CU information displayed by DESCRIBE LOADMODS includes information about the following types of CUs:
    • Known CUs (CUs that appear in LIST NAMES CUS output)
    • Hidden disassembly CUs (If SET DISASSEMBLY OFF is in effect these are the names of the CUs that would be created if you SET DISASSEMBLY ON)
    • Hidden COBOL CUs (COBOL CUs that have not yet been entered)
    • A CU name shown as a load module name followed by ">" indicates the entry point CU for a load module that is the target of an AT LOAD command.
  • You can use the DESCRIBE CHANNEL command only if your application program runs on CICS Transaction Server Version 3.1 or later.
  • For PL/I, COBOL, LangX COBOL, assembler, and disassembly, if a channel name is mixed case, you must enclose it in quotation marks (") or apostrophes ('). If you do not enclose it in quotation marks or apostrophes, z/OS Debugger converts it to all upper case.
  • For C and C++, all channels names are case sensitive. The following table compares how the same command must be typed differently, depending on the programming language you are debugging:
    Table 1. Comparison of the same command used in different programming languages
    If the container name is... If the programming language is PL/I, COBOL, LangX COBOL, assembler or disassembly, type in... If the programming language is C or C++, type in...
    chname DESCRIBE CHANNEL 'chname' DESCRIBE CHANNEL chname
    conNAME DESCRIBE CHANNEL 'conNAME' DESCRIBE CHANNEL conNAME

Examples

  • Describe the attributes of argc, argv, boolean, i, ld, and structure. 
    DESCRIBE ATTRIBUTES (argc, argv, boolean, i, ld, structure);
  • Describe the current environment. 
    DESCRIBE ENVIRONMENT;
  • Display information describing program myprog. 
    DESCRIBE PROGRAMS myprog;

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