COMM ALTER (Modify Error Table)

The COMM ALTER option modifies the error table which controls what traces ddb performs and what messages it generates.
datacom150
The COMM ALTER option modifies the error table which controls what traces 
CA Datacom®/DB
 performs and what messages it generates.
The following topics are discussed on this page:
 
 
When to Use
This option should only be used to analyze processing problems at the direction of CA Support.
How to Use
The MUF must be active when you execute this command. Execute the COMM function with one of the following command formats:
 
Modify Error Table, RCERROR=
 
►►─ COMM OPTION=ALTER,RCERROR=
eeiii
─┬────────────────────────┬───────────────► └─ ,BUFFERS= ─┬─ NO ◄ ─┬─┘ └─ YES ──┘ ►─┬────────────────────────┬─┬──────────────────────┬────────────────────────►◄ └─ ,MASTERL= ─┬─ NO ◄ ─┬─┘ └─ ,IGN68= ─┬─ NO ◄ ─┬─┘ └─ YES ──┘ └─ YES ──┘
 
Modify Error Table, DUMPS=
 
►►─ COMM OPTION=ALTER ─ ,DUMPS=
type
──────────────────────────────────────────► ►─┬─────────────────────────────────────────────────────────────┬────────────► └─ ,TRACE= ─┬─
func
,PARM=
ppbbbbbb
─┬──────────────────────┬─┬─┘ │ │ ┌──────────────────┐ │ │ │ └─▼─ ,PARM=
ppbbbbbb
─┴─┘ │ ├─ NONE ────────────────────────────────────────┤ └─
class-name
──────────────────────────────────┘ ►─┬────────────────────┬─┬────────────────────┬──────────────────────────────► └─ ,JOBNAME=
jobname
─┘ └─ ,TERMID=
terminal
─┘ ►─┬─────────────────────────┬─┬──────────────────────┬───────────────────────►◄ └─ ,ACCESSOR=
accessor-id
─┘ └─ ,IGN68= ─┬─ NO ◄ ─┬─┘ └─ YES ──┘
 
Modify Error Table, TRACE=
 
►►─ COMM OPTION=ALTER ────────────────────────────────────────────────────────► ►─ ,TRACE= ─┬─
func
,PARM=
ppbbbbbb
─┬──────────────────────┬─┬────────────────► │ │ ┌──────────────────┐ │ │ │ └─▼─ ,PARM=
ppbbbbbb
─┴─┘ │ ├─ NONE ────────────────────────────────────────┤ └─
class-name
──────────────────────────────────┘ ►─┬────────────────────┬─┬────────────────────┬──────────────────────────────► └─ ,JOBNAME=
jobname
─┘ └─ ,TERMID=
terminal
─┘ ►─┬─────────────────────────┬─┬──────────────────────┬───────────────────────►◄ └─ ,ACCESSOR=
accessor-id
─┘ └─ ,IGN68= ─┬─ NO ◄ ─┬─┘ └─ YES ──┘
 
Command
 
  •  
    COMM
    Invokes the function to pass communication to the MUF.
 
Required Keywords
 
  •  
    OPTION=ALTER
    Requests a change in the type of dump produced for a specific error or under specific conditions.
 
Optional Keywords
 
  •  
    ,BUFFERS=
    (Use only when RCERROR= is specified.)
     Specifies if a dump of all native 
    CA Datacom®/DB
     buffers is to be produced.
    •  
      Valid Entries:
      NO or YES
    •  
      Default Value:
      NO
  •  
    ,DUMPS=
    (Do not use when RCERROR= is specified.)
     Specifies type of dump to be produced.
    •  
      ARRAY
      Dump of the SQLDA, row, and input statement for each logical unit of work (LUW) in the task array
    •  
      CSTACK
      Dump of the C program stack
    •  
      CURSOR
      Dump of the cursor list and cursor pointed to by the logical unit of work (LUW)
    •  
      DSFUSR
      Dump of the DSFUSR array
    •  
      GLOBALA
      Dump of the global area
    •  
      GLOBALL
      Dump of the global plan list and plans and the logical unit of work (LUW), User Requirements Table list and the User Requirements Tables pointed to by each attach
    •  
      GLOBALX
      Dump of the X_COMM space
    •  
      LUW
      Dump of the logical unit of work (LUW)
    •  
      PLAN
      Dump of plan list and plans pointed to by the logical unit of work (LUW)
    •  
      QCB
      Dump of the QCB area pointed to by the logical unit of work (LUW)
    •  
      SQLFLOW
      A trace showing the current program name and the program name which called the current program
    •  
      STMT
      Dump of statement list, short statement, statement source and the QCB area
    •  
      TASK
      Dump of the task, the SQLDA, row and the input statement
    •  
      URT
      Dump of the User Requirements Table list and User Requirements Tables pointed to by the logical unit of work (LUW)
    •  
      Default Value:
      (No default)
  •  
    IGN68=
    Specify IGN68=YES to ignore a return code 68. IGN68= is allowed for every ACCESS and COMM function. By ignoring return code 68, you can set up and run JCL that incorporates a stack of DBUTLTY functions without requiring that the MUF be enabled. IGN68= would therefore be useful, for example, if you wanted to load a database without first enabling the MUF, perhaps to allow restart to properly occur. Following is an example showing a stack of DBUTLTY functions that use IGN68=.
    ACCESS STATUS=UTLTY,DBID=997,USERS=WAIT,IGN68=YES COMM OPTION=CLOSE,DBID=997,IGN68=YES INIT AREA=IXX,DBID=997 INIT AREA=A01,DBID=997 LOAD AREA=A01,DBID=997,FORMAT=NONE,KBYTES=9999,SORT=1 ACCESS STATUS=WRITE,DBID=997,IGN68=YES
     If the CXX is externally secured, the INIT and LOAD functions do not execute without the MUF being available, and IGN68=YES is therefore not recommended.
    A function or functions specified with IGN68=YES generates message DB13001E to note that the function did not occur. Because no error was recognized, however, other functions in the stack continue to execute, and the DBUTLTY step ends without a recognizable error. Message DB13001E signals that the MUF was not enabled.
    The DBSYSID macro parameter DELAY68= can be used to specify the number of minutes that the MUF connection can wait if the MUF is not currently available. But if IGN68=YES is specified, DELAY68= is ignored and the function continues. If the delay is desired, however, either do not specify IGN68=, in which case it defaults to NO, or specify IGN68=NO.
    •  
      Valid Entries:
      NO or YES
    •  
      Default Value:
      NO
  •  
    JOBNAME=
    (Use only when DUMPS= or TRACE= is specified.)
     Specifies the job name being traced.
    •  
      Valid Entries:
      1- to 8-character job name
    •  
      Default Value:
      All jobs
  •  
    ,MASTERL=
    (Use only when RCERROR= is specified.)
     Specifies if a Master List dump is to be produced.
    •  
      Valid Entries:
      NO or YES
    •  
      Default Value:
      NO
  •  
    ,RCERROR=
    eeiii
     
    (Do not use when DUMPS= or TRACE= is specified.)
     Specifies the return code to modify, RCERROR=
    eeiii
    , where 
    ee
     is the two-character external return code and 
    iii
     is the three-character internal return code. With the RCERROR MUF startup option, you can specify values for 
    ee
     and 
    iii.
     
    For details, see Administrating.
  •  
    ,TERMID=
    (Use only when DUMPS= or TRACE= is specified.)
     Specifies the terminal ID of the terminal which is issuing the SQL request.
    You can include this parameter once per COMM request.
    •  
      Valid Entries:
      4- to 8-character terminal ID
    •  
      Default Value:
      All terminals
  •  
    ,ACCESSOR=
    (Use only when DUMPS= or TRACE= is specified.)
     Specifies the security signon name.
    You can include this parameter once per COMM request.
    •  
      Valid Entries:
      1- to 8-character accessor ID
    •  
      Default Value:
      All accessors
  •  
    ,TRACE=
    (Do not use when RCERROR= is specified.)
     Specifies what is to be traced to assist in the resolution of problems involving SQL processing. TRACE= can be used only once in a request. You can use the TRACE= parameter with or without the DUMPS= parameter.
    Because of the large amount of output which can be generated by a trace, we recommend that you limit the trace by also specifying either JOBNAME= or TERMID=.
    •  
       
      func
      ,PARM=
      ppbbbbbb
       
      Specifies the name of the SQL processor function for which the parameters are to be dumped, followed by one or more PARM= keywords, each with a value in the form ppbbbbbb:
      The 
      pp
       is 01 to 99 and specifies the position in the parameter list of the parameter to be dumped.
      The 
      bbbbbb
       is 000000 or 000001 through 999999. 000000 dumps the parameter value. 000001 through 999999 dumps 
      bbbbbb
       bytes of the area to which the parameter points.
      CA Support provides you the function and parameter value to code.
    •  
      Default Value:
      NONE. Turns off all trace requests.
  • ,TRACE=
    •  
       
      class-name
       
      Specify an SQL trace class by replacing 
      class-name
       with one of the following:
      TRACECONSTR
       - Constraint
      TRACECRS
       - Row-level activity within SQL and a summary level Compound Boolean Selection Diagnostic Report. See Reporting on the Compound Boolean Selection Facility. This report is only generated once per statement execution, so for an inner join table that generates a Compound Boolean Selection SELFR request for each outer row, the Compound Boolean Selection Diagnostic Report is only generated for the first request. The remaining reports are usually identical. To generate a detailed Compound Boolean Selection Diagnostic Report, also turn on TRACEDETAIL.
      TRACEDD
       - 
      CA Datacom® Datadictionary™
       transactions issued to process SQL requests
      TRACEDETAIL
       - Causes more information to be traced for some other trace classes. See the note that follows the explanation about the MSG option. Also see the note marked with one asterisk (*).
      TRACEERR
       - Calls to MUF
      TRACEEXPR
       - Expression and data type
      TRACEGLOBAL
       - Summary report showing SQL subsystem state, issued when run unit ends
      TRACEMEMORY
       - Dynamic memory activity
      TRACEMSG
       - Turns on the SQL PLAN option MSG=SS (summary messages) and Compound Boolean Selection Diagnostic Report. (See Reporting on the Compound Boolean Selection Facility.)
      TRACEPARSE
       - SQL parser
      TRACEPLAN
       - PLAN locking
      PROCTRIGPLS
       - Diagnostic information related to procedures and triggers. PROCTRIGPLS does 
      not
       have a prefix of TRACE.
      TRACERAAT
       - Record-at-a-time calls issued to process SQL requests.
    •  
      Default Value:
      (No default)
      With TRACEDETAIL:
      TRACEEXPR
       - Shows a BEFORE execution image of expression nodes in addition to the AFTER execution image.
      TRACEMSG
       - Turns on SQL PLAN option MSG=DD. This generates per-execution messages written to both SYSADM. SYSMSG table and the Statistics and Diagnostics Area (PXX). Also, the summary level Compound Boolean Selection Diagnostic Report is generated.
      TRACECRS
       - Generates a detailed Compound Boolean Selection Diagnostic Report showing each index and row accessed and some information that is for internal use only. TRACECRS can generate a very large report. Turn it on only as necessary.
      TRACEDD
       - Column and statement definitions read from DDD (Data Definition Directory).
      TRACEPARSE
       - Dumps expression nodes as they are generated, in addition to the summary dump at the end of parsing.
      TRACECONSTR
       - Debugging information for confirmation, creating and enforcing foreign keys and domain constraints, memory usage, and date arithmetic.
      To turn on the SQL PLAN option MSG=DD (detail messages), issue a second COMM ALTER option, specifying TRACE=TRACEDETAIL. Turning on the MSG=DD option also turns on the Compound Boolean Selection diagnostic detail reporting showing each call to the index/read module. For example, to trace detail optimization messages and produce a Compound Boolean Selection Diagnostic Detail Report for a particular job, enter the following:
      COMM OPTION=ALTER,TRACE=TRACEMSG,JOBNAME=jobname COMM OPTION=ALTER,TRACE=TRACEDETAIL,JOBNAME=jobname
Example JCL
The following shows the command to issue an ALTER option.
 Use the following as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
//jobname See the previous note and
JCL Requirements
.
// EXEC PGM=DBUTLTY,REGION=2M //STEPLIB See the previous note and
JCL Requirements
.
//SYSIN DD * Command input COMM OPTION=ALTER,RCERROR=05034,MASTERL=YES,BUFFERS=YES /*
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
Sample Report COMM ALTER 
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 COMM OPTION=ALTER,RCERROR=05034,MASTERL=YES,BUFFERS=YES FUNCTION=COMM BUFFERS=YES MASTERL=YES OPTION=ALTER RCERROR=05034
This page of the report shows the following:
  • The command exactly as entered.
  • An analysis of keywords encountered and expected. Any errors found are flagged with a note in the left margin.
  • Any messages related to syntax processing.
DB13105I - COMM ALTER REQUEST ACCEPTED
This page of the report shows a message indicating that DBUTLTY successfully placed the request on the MUF communication queue.