A ------------------------------------------------------------------------ | README file for AID V03.4 | | Edition July 2011 | ------------------------------------------------------------------------ AID V03.2 supports Unicode for the first time. It requires a BS2000/OSD version with Unicode capability; currently, this would be BS2000/OSD-BC V6.0B or higher in conjunction with openNet Server V3.2 or OSD/XC V2.2 or higher. This README file contains notes and supplementary information relating to the following topics: - Debugging COBOL programs under POSIX - Changes and extensions to AID V2.1B relating to debugging in BS2000. The SINIX-based AID-FE graphical user interface is no longer part of AID version 3. - Supporting write stops in data spaces in AID V3.4A20 - A new type %E for inverting the endianness of a data item in AID V3.4A20 This involves the following manuals: AID V3.2A: Core Manual, Edition November 2006 (Order No. U2853-J-Z125-5-76) Debugging COBOL Programs, Edition November 2006 (Order No. U2855-J-Z125-6-76) AID V2.3B: Debugging of C/C++ Programs, Edition April 1999 (Order No. U6148-J-Z125-5-76) AID V2.2: Debugging under POSIX, Edition December 1996 (Order No. U25054-J-Z125-1-7600) AID V2.1A: Debugging on Machine Code Level, Edition March 1995 (Order No. U2854-J-Z125-7-7600) AID V2.0B: Ready Reference, Edition May 1993 (Order No. U20746-J-Z125-1-7600) AID V2.0A: Debugging PL/I Programs, Edition March 1992 (Order No. U3484-J-Z125-3-7600) Debugging ASSEMBH Programs, Edition December 1991 (Order No. U6199-J-Z125-2-7600) Debugging of FORTRAN Programs, Edition September 1991(Order No. U4298-J-Z125-3-7600) A Page 1 Contents -------- 1 Information on debugging COBOL Programs under POSIX..............2 2 Extensions to version 2.1B ......................................3 2.1 Index range specifications for arrays............................3 2.2 %AID.............................................................4 2.3 %CONTROLn........................................................4 2.4 %STOP............................................................5 2.5 %TRACE...........................................................5 2.6 Hints concerning basic qualification.............................6 3 AID V3.4A20 extension to support write stops in ESA data spaces..7 3.1 %ON..............................................................7 3.2 Messages.........................................................8 4 A new type %E for inverting the endianness of a data item in AID V3.4A20......................................................9 4.1 Storage types for inverting the endianness of data item..........9 4.2 Adding %E to the lists of storage types.........................11 AID commands....................................................15 All the specifications in this brief description are based on the contents of the above user manuals and are assigned to the relevant sections of these manuals. In contrast to the metasyntax in the manuals, operands in the following sections are expressed as plain text enclosed in quotation marks ('...'). A Page 2 1 Information on debugging COBOL programs under POSIX Extension to the chapter "Prerequisites for debugging" in the "Debugging under POSIX" supplement AID enables you to debug a COBOL Program compiled in the POSIX environment using the POSIX COBOL command in exactly the same way as described for C/C++ Programs in the "Debugging under POSIX" supplement. You c a n n o t use the %TRACE 1 command specified in the section "Commands at the start of a debugging session" of the manual "Debugging COBOL Programs" to position the program to the first executable statement of the main program after loading it in the POSIX environment. The following command sequence must be used instead %INSERT 'prog-id'; %RESUME For 'prog-id', enter the name of the main program. A Page 3 2 Extensions to version 2.1B 2.1 Index range specification for arrays Extension in the "Addressing" chapter of the manuals titled "Debugging C/C++ Programs", "Debugging COBOL Programs", "Debugging FORTRAN Programs" and "Debugging PL/I Programs" and in the "Operands" chapter of the Ready Reference. The term array is used below as a common expression for vector (C/C++), table (COBOL), data field (Fortran) and matrix (PL/I). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - array (index{,...}) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - While debugging C/C++ programs, you can state the index in brackets, as is usual in the programming language, i.e.: array [index] {...} index In addition to specifying individual elements of an array with indexing, you can now also specify a range of a dimension: index1 : index2 This designates the range between 'index1' and 'index2'. The following applies for 'index1' and 'index2': Both must lie within the index limits, and 'index1' must be less than or equal to 'index2'. * This designates the entire index range of the dimension. In the case of single dimensional arrays, this is equivalent to using the array name without indexing. You can only use range specification in the %DISPLAY command. Array names with range specifications must not be used in address calculations. Modifications of type or length are not permitted. Examples: - %D array (*,3) In a two dimensional array, all elements belonging to the first dimension and whose second dimension index is 3 are output. - %D array (1 : 3,*,5 : 15) The following elements are output from a three dimensional array: The index of the first dimension is 1, 2 or 3, The index of the second dimension ranges from the lower index limit to the upper index limit The index of the third dimension ranges from 5 to 15. A Page 4 2.2 %AID Extension in the "AID Commands" chapter of the language-specific manuals, the manual for debugging at machine code level and the Ready Reference. ------- | LOW | ------- ALL Entry of all BLS names is case sensitive. In addition, upper and lower case entries in character literals and in program, data and instruction names are retained, as when %AID LOW=ON is specified. The following BLS names are used by AID: Context names of the CTX qualification Load unit names of the L qualification Link module names of the O qualification CSECT names of the C qualification COMMON names of the COM qualification Names of compilation units (program units in Fortran) of the S qualification ON/OFF Same meaning as previously. If %AID LOW is entered without an operand value, the default value ON still applies. Before %AID LOW={ON/OFF/ALL} is entered for the first time in a debugging session, the default setting %AID LOW=OFF applies as previously. All other operands and operand values of %AID remain unchanged. 2.3 %CONTROLn Extension in the "AID Commands" chapter of the language-specific manuals, the manual for debugging at machine code level, and the Ready Reference. As in the case for %INSERT and %ON, the <%STOP> subcommand is used by default for %CONTROL if another subcommand is not entered explicitly. This results in the following syntax: -------------------------------------------------------------------- Command Operand -------------------------------------------------------------------- %C[ONTROL]n [criterion][,...] [IN control range] [] -------------------------------------------------------------------- A Page 5 2.4 %STOP Extension in the "AID Commands" chapter of the language-specific manuals, the manual for debugging at machine code level and the Ready Reference. If you set a dump file as a basic qualification with %BASE and then enter a %STOP command, AID outputs a STOP message containing localization information for the address at which the program was interrupted when the dump file was written. As previously, a %STOP in a subcommand always refers to the loaded program. 2.5 %TRACE Extension in the "Sequence Control" section of the Core Manual and the "AID Commands" chapter of the language-specific manuals, the manual for debugging at machine code level and the Ready Reference. The %TRACE command has been extended by a new operand with which you can control whether the program should stop (default value) or continue to run without logging, after %TRACE terminates. -------------------------------------------------------------------- Command Operand -------------------------------------------------------------------- %T[RACE] [num] [continue] [criterion][,...] [IN trace range] -------------------------------------------------------------------- The previous operands 'number' (abbreviated to 'num' in the syntax to save space), 'criterion' and 'trace range' remain unchanged. ------------ | continue | ------------ specifies whether AID should stop or continue the program after %TRACE terminates. 'continue' applies until a different operand value for it is entered in a new %TRACE or until the program terminates. continue OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - {S | R} ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - S The program is stopped. AID outputs a STOP message containing ~ localization information about the interrupt point. The default value is S. R The program continues without outputting a message. A Page 6 Examples: - %TRACE 5 R %INSTR 5 program commands are executed and logged. After this, the program continues without logging. - %C1 %CALL IN S=TESTPROG <%TRACE 1 R> All subroutine calls by the TESTPROG module are logged. The program continues after each respective CALL instruction is executed and logged. 2.6 Hints concerning basic qualification (chapter 7.1.1 in user manual) AID does not support basic qualifications (E=...) inside an operand, only at the beginning. Thus, basic qualification must be specified before functions like addressing %@(...) or length functions %L(), %L=(), ... A Page 7 3 AID extension to support write stops in ESA data spaces 3.1 %ON Change to the "AID commands" chapter command %ON of the manual titled "Debugging on Machine Code Level"(page 72): D E L E T E L I N E S: ~~~~~~~~~~~~~~~~~~~~~~ Only the memory objects in the program area can be monitored when degubbing ESA programs. Extension to the "AID commands" chapter command %ON of the manual titled "Debugging on Machine Code Level" (page 73): For BS2000/OSD V9.0, application programs on ESA (Enterprise System Architecture) computers can support write stops in address spaces for data, the data spaces. They can be uniquely addressed via the SPID (space identification) or via one or more ALETs (access list entry tokens). AID expands the user interface to support dedicated address spaces, e.g. /%ON %WRITE(ALET=X'xxxxxxxx'.V'xxx') "given DS only" /%ON %WRITE(SPID=X'xxxxxxxxxxxxxxxx'.V'xxx') "given DS only" Note: Write stops in address spaces are only supported on S/390 machines, but neither SPARC nor x86-64 HSI. A Page 8 ------------------------------------------------------------------- Command Operand ------------------------------------------------------------------- %ON %WRITE ([ALET/SPID-qua] { V'f...f'|{ compl-memref}) ------------------------------------------------------------------- The possible qualifications that can be entered for ' ALET/SPID-qua ' are shown in the following syntax: ALET/SPID-qua OPERAND - - - - - - - - - - - - - - - - - - - - - - - {ALET={X'f...f' | %nAR | %nG} | SPID=X'f...f'} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Note: /%ON %WRITE(ALET=X'00000000'.V'123') /%ON %WRITE(SPID=X'0000000300000057'.V'123') The ALET value NULL corresponds always to the PS. If the TCB field etcbSPID happens to contain x'0000000300000057', then also the SPID specification denotes the PS (otherwise it denotes a DS, existing or not). Thus, if PS is effectively specified by ALET or SPID, the HSI does of course not matter. 3.2 Messages Extension to the "Messages" chapter of the manual titled "Core Manual"(page 166): AID0478 WRITE STOP IN DATA SPACE ONLY SUPPORTED ON S SERIES MODELS Extension to the "Messages" chapter of the manual titled "Core Manual"(page 169): AID0495 ALET/SPID QUAL. FOR %ON %WRITE NOT SUPPORTED BEFORE .0 BS2000/OSD V9. A Page 9 4 A new type %E for inverting the endianness of a data item 4.1 Storage types for inverting the endianness of data item Extension to the "Keywords" chapter of the manual titled "Core Manual"(page 110): 10.1.1 Storage types for inverting the endianness of data item (additional section) Type modification %E is used to invert endianness of a memory content. It works with: %n General registers %nG AID general registers %MR All 16 general registers in tabular form %nQ Floating-point register, n = 0,4 %nD|E Floating-point register, n = 0,2,4,6 %FR All 4 floating-point registers with double precision edited in tabular form %PC Program counter %PCB Process control block %nAR Access register field Data from loaded program %TCB %CLASS6 Length must be below 1024 %CLASS5 Length must be below 1024 %CLASS34 Length must be below 1024 %CLASS2 Length must be below 1024 %CLASS31 Length must be below 1024 V'xxxxxxxx' virtual adress %E type modification can be used with commads %MOVE, %SET, %DISPLAY. After applying a type modification %E to an operand, the operand has hexadecimal storage type (%X),i.e. output type Dump. Examples: 1. %E inverts the memory content of the register /%DISPLAY %4 %4 = 01001444 With %E: /%DISPLAY %4%E %4 = 44140001 2. %E inverts the memory content of address V'00000066' /%DISPLAY V'00000066' V'00000066' = SEND2 + #'00000066' 00000066 (00000066) 11223344 With %E: /%DISPLAY V'00000066'%E V'00000066' = SEND2 + #'00000066' 00000066 (00000066) 44332211 A Page 10 You can use %E with length modification: %ELn, but the length cannot exceed 1024.Keyword %CLASSx%E must be used with length modification and length must be below 1024. Examples: 1. /%DISPLAY %5 %5 = 12345678 /%MOVE %5%E INTO %10 /%DISPLAY %10 %10 = 78563412 2. /%DISPLAY %5 %5 = 12345678 /%SET %5%EL2 INTO %10 %10 = 34120000 A Page 11 4.2 Adding %E to the lists of storage types Following extensions imply adding %E to the lists of storage types. Extension to the "Addressing in AID" chapter of the manual titled "Core Manual"(page 87): %type[L-mod] ~~~~~~~~~~~~ Keyword for storage types with optional length specification: %X, %C, %E, %P, %D, %F, %A and %UTF16 (see chapter "Keywords" on page 109). Extension to the "Glossary" chapter of the manual titled "Core Manual"(page 198): storage type ~~~~~~~~~~~~ This is the data type that was either defined in the source program or selected via type modification. AID knows the storage types %X, %C, %E, %P, %D, %F, %A. See %SET and chapter "Addressing in AID" on page 65 and chapter "Keywords" on page 109. Extension to the "Machine-code-specific addressing" chapter of the manual titled "Debugging on Machine Code Level"(page 13): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A, %S, %SX) Extension to the "AID commands" chapter of the manual titled "Debugging on Machine Code Level"(page 41): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A, %S, %SX) Extension to the "AID commands" chapter of the manual titled "Debugging on Machine Code Level"(page 67): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A, %S, %SX) Extension to the "AID commands" chapter of the manual titled "Debugging on Machine Code Level"(page 92): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A, %S, %SX) A Page 12 Extension to the "Glossary" chapter of the manual titled "Debugging on Machine Code Level"(page 126): storage type ~~~~~~~~~~~~ This is either the data type defined in the source program or the one selected by way of type modification. AID recognizes the general storage types %X, %C, %E, %P, %D, %F and %A and the special storage types %SX and %S for the interpretation of machine instructions (see %SET and chapter 7 in the AID Core Manual). Extension to the "AID commands" chapter of the manual titled "Debugging of ASSEMBH Programs"(page 37): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A) Extension to the "AID commands" chapter of the manual titled "Debugging of ASSEMBH Programs"(page 59): compl-memref ~~~~~~~~~~~~ - type modification %E Extension to the "AID commands" chapter of the manual titled "Debugging of ASSEMBH Programs"(page 86): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %D, %P, %F, %A) Extension to the "Glossary" chapter of the manual titled "Debugging of ASSEMBH Programs"(page 119): storage type ~~~~~~~~~~~~ This is either the data type defined in the source program or the one selected by way of type modification. AID knows the storage types %X, %C, %E, %P, %D, %F and %A (see AID Core Manual, chapters 6 and 9). Extension to the "AID commands" chapter of the manual titled "Debugging of C/C++ Programs"(page 152): compl-memref ~~~~~~~~~~~~ - type modification (%X, %C, %E, %D, %F, %A) A Page 13 Extension to the "AID commands" chapter of the manual titled "Debugging of C/C++ Programs"(page 197): compl-memref ~~~~~~~~~~~~ - type modification (%A, %E, %S, %SX) Extension to the "AID commands" chapter of the manual titled "Debugging of C/C++ Programs"(page 248): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %D, %F, %A, %S, %SX) Extension to the "Glossary" chapter of the manual titled "Debugging of C/C++ Programs"(page 330): storage type ~~~~~~~~~~~~ This is either the data type defined in the source program or the one selected by way of type modification. AID recognizes the general storage types %X, %C, %E, %P, %D, %F and %A and the special storage types %SX and %S for the interpretation of machine instructions (see %SET and the chapters on "Adressing in AID" and "Keywords" in the AID Core Manual). Extension to the "AID commands" chapter of the manual titled "Debugging of COBOL Programs"(page 55): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A, %S, %SX, %UTF16) Extension to the "AID commands" chapter of the manual titled "Debugging of COBOL Programs"(page 87): compl-memref ~~~~~~~~~~~~ - type modification (%A, %E, %S, %SX) Extension to the "AID commands" chapter of the manual titled "Debugging of COBOL Programs"(page 123): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %D, %P, %F, %A, %S, %SX, %UTF16) A Page 14 Extension to the "Glossary" chapter of the manual titled "Debugging of COBOL Programs"(page 170): storage type ~~~~~~~~~~~~ This is either the data type defined in the source program or the one selected by way of type modification. AID knows the storage types %X, %C, %E, %P, %D, %F, %A, %UTF16, %S and %SX (see %SET and AID Core Manual [1]). Extension to the "AID commands" chapter of the manual titled "Debugging of FORTRAN Programs"(page 39): compl-memref ~~~~~~~~~~~~ - type modification (%T(dataname), %X, %C, %E, %P, %D, %F, %A) Extension to the "AID commands" chapter of the manual titled "Debugging of FORTRAN Programs"(page 67): compl-memref ~~~~~~~~~~~~ - type modification %E Extension to the "AID commands" chapter of the manual titled "Debugging of FORTRAN Programs"(page 94): compl-memref ~~~~~~~~~~~~ type modification (%T(dataname), %X, %C, %E, %D, %P, %F, %A) Extension to the "Glossary" chapter of the manual titled "Debugging of FORTRAN Programs"(page 128): storage type ~~~~~~~~~~~~ This is either the data type defined in the source program or the one selected by way of type modification. AID knows the storage types %X, %C, %E, %P, %D, %F and %A (see AID Core Manual, chapters 6 and 9). A Page 15 ------------------------------------------------------------------------ | Command or | Information | | subcommand | | ------------------------------------------------------------------------ |%AID |Displays the currently valid settings for the %AID, | | |%AINT and %BASE commands, and the currently loaded | | |version of AID. | ------------------------------------------------------------------------ |%ALIAS |Lists all defined alias names with their associated | | |original names. | ------------------------------------------------------------------------ |%BASE |Displays the currently valid settings for %BASE, | | |%AINT and %SYMLIB, the TSN, TID, the version of the | | |operating system and the host type. | ------------------------------------------------------------------------ |%C0NTROL |Displays the input string for each defined %CONTROL | | |command. | ------------------------------------------------------------------------ |%DISASSEMBLE |Displays the current values for 'number' und 'start', | | |and the 'start' address in the form V'...' . | ------------------------------------------------------------------------ |%FIND |Displays the entered command, and possibly the | | |virtual address of the last hit. | ------------------------------------------------------------------------ |%INSERT [test- |If 'test-point' is not specified, all active test | |point] |points are displayed. Otherwise AID displays the | | |command in which 'test-point' was defined. | ------------------------------------------------------------------------ |%ON |Displays the input string for each active %ON command.| ------------------------------------------------------------------------ |%OUT |Displays the current 'medium-and-quantity' values for | | |the commands that can be controlled by %OUT. | ------------------------------------------------------------------------ |%OUTFILE |Lists all implicitly or explicitly defined output | | |files together with their link names. | ------------------------------------------------------------------------ |%QUALIFY |Displays the last %QUALIFY command. | ------------------------------------------------------------------------ |%SYMLIB |Displays the defined libraries together with the | | |appropriate base qualification and the TSN. | ------------------------------------------------------------------------ |%TRACE |Displays the initial values of the %TRACE parameters. | | |AID uses the default values for operands that were | | |not explicitly entered. The module in which the | | |%TRACE is running is entered. The program considers | | |whether the last %TRACE command was symbolic or at | | |machine code level. AID indicates in subsequent | | |lines how many commands or statements were processed | | |with the current %TRACE command and what the input | | |string of the last %TRACE command looked like. | ------------------------------------------------------------------------ |%.* |Displays the names of all active subcommands | | |together with the type of the AID command in which | | |they were defined. | ------------------------------------------------------------------------ |%.submcdname |Displays the command in which 'subcmdname' was | | |defined. | ------------------------------------------------------------------------