Skip to content
CA Datacom Core - 15.0
Documentation powered by DocOps

COMM ALTER (Modify Error Table)

Last update March 13, 2019

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

    Note: 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.

    Note: 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.

Note: 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.

Was this helpful?

Please log in to post comments.