SET (Change Environment Processing)

The SET function allows you to change environment processing of options.
datacom
The SET function allows you to change environment processing of options.
One common ability is to use ON-ERROR to establish how you want DBUTLTY to support error handling of functions within a specific execution, and for other special needs.
Two error handling issues of concern exist and each are enhanced with this function. The first is that if a function fails for any reason, each remaining function in the step is syntax edited and ignored. The second is that at the end of the last function, DBUTLTY ends with an abend 4 in z/OS or CANCEL in z/VSE and never a return code other than zero. These actions remain the default and cannot be globally changed.
The STOP and CONTINUE options indicate the execution option for future functions in the same utility step. The ABEND and RC
n
options indicate the actions taken to terminate the utility step back to the operating system. The STOP/CONTINUE options are completely independent from the ABEND/RC
n
options.
The SET function does not open any
Datacom/DB
tables.
A SET function can generate an error condition only for a syntax error. If syntax is correct, it always executes except if the EDIT function was previously specified.
The different types of SET options are used to do the following:
  • Control the style of error handling and remove an error condition.
  • Assist in the debugging of a specific error condition that has occurred during a DBUTLTY execution.
  • Override options for a specific DBUTLTY execution without changing the option for other DBUTLTY executions.
  • Allow the testing of some interesting conditions. This use is intended to speed Broadcom
    Broadcom
    product internal testing, but some users have asked for the ability as well, so that they can locally do QA on cases about which they have a concern.
No SET option communicates with MUF. All are local to this DBUTLTY execution.
Some SET options are NEVER allowed to occur when done as part of the DBIN1PR additional SYSIN processing. These are the following:
  • DUMPPGM=
Some SET option can ONLY occur when done as part of the DBIN1PR additional SYSIN processing. Remember that DBIN1PR SET statements are required to have SET in columns 1-3 with one blank then the value. These are the following:
  • CONSOLE_SECONDS=
  • LINE=
Some SET options can occur at either input stream but must occur before functions other than SET, because they must occur before DBUTLTY configures itself for execution. These are the following:
  • DATALN
  • DATANO
  • DXXNO
  • IXXLN
  • IXXNO
SET options not the listed just given work through either input stream. They can be changed during execution to change the method of execution for the functions that follow them, remaining in place until or unless a later SET option changes the setting or condition.
The SET function at either input stream supports stacking of options. This reduces console messages. They must be separated by a semicolon (;) as in this example: SET OPTION1=DATANO=999;DATALN=4096;DXXNO=999;IXXLN=4096. DBUTLTY supports no form of continuation of an individual keyword value.
The SET function having a value starting with an asterisk (*) is accepted and printed but then ignored.
The following console-like options are not specifically SET options. They are allowed to be used as a SET option through the SYSIN but not through DBIN1PR.
  • DIAGOPTION n,y,x where ‘n’ is 0-23, ‘y’ is 0-255, and ‘x’ is ON/OFF/YES/NO
  • DYNAMIC_EXTEND_MSGS OLD/TRK/CYL
  • RCERROR x,y,nnnnn where ‘x’ is YES/NO/ON/OFF/FAIL, ‘y’ is YES/NO/ON/OFF/FAIL, and ‘nnnnn’ is a return code external/internal
  • X_DEBUG x,n,y where ‘x’ is CBS/CL1/CDC/CXX/DSM/IO/OP1/PXX/LXX/RXX/UTM/COM/XX1/SQL1/XES/DST/XCF/CCI, ‘n’ is a hexadecimal 2-byte value of bits to turn on or off, and ‘y’ is YES/NO/ON/OFF
  • X_OPEN_CLOSE_MSGS x where ‘x’ is YES/NO/ON/OFF
  • X_TRACE_DSM n where ‘n’ is a number 0-32767
When to Use SET
All of these options are considered to be useful rarely, for special purposes. Review the list to know what options are available and use when appropriate.
How to Use SET
The following SET OPTION1= values are available in general. Some, however, have special rules about their use.
►►─ SET ─ OPTION1= ─┬─ CONSOLE_SECONDS=n ──────┬────────────────────►◄ ├─ DATALN=nnnnn ───────────┤ ├─ DATANO=nnnn ────────────┤ ├─ DELAY_INSIDE=nnn ───────┤ ├─ DELAY_SECONDS=nn ───────┤ ├─ DELAY68 ────────────────┤ ├─ DELAY85 ────────────────┤ ├─ DUMPPGM=name ───────────┤ ├─ DXXNO=nnnn ─────────────┤ ├─ ECHO_FUNCTIONS ─────────┤ ├─ EOJ_REPORT ─────────────┤ ├─ EOJ_REPORT_X ───────────┤ ├─ IXXLN=nnnn ─────────────┤ ├─ IXXNO=nnnn ─────────────┤ ├─ MUF_NOT_ENABLED─────────┤ ├─ ON-ERROR-CONTINUE ──────┤ ├─ ON-ERROR-STOP ──────────┤ ├─ ON-ERROR-ABEND ─────────┤ ├─ ON-ERROR-RCn ───────────┤ ├─ ON-ERROR-REMOVE ────────┤ ├─ SID_CONNECT=a ──────────┤ ├─ SIDNAME=name ───────────┤ ├─ SNAPALL ────────────────┤ ├─ SNAPERR ────────────────┤ └─ WTO--x ─────────────────┘
Command
  • SET
    Invokes the SET function for the input stream following this command.
Required Keywords
  • OPTION1=
    Specifies the options for the SET function, as follows:
  • CONSOLE_SECONDS=
    n
    Allows you to override the DBSYSID macro option CONSOLE_MINUTES to test the DBUTLTY automatic STATUS command. The n value can be 1-9. This is only an option through DBIN1PR.
  • DATALN=
    nnnnn
    The length of a data buffer as set in the DBMSTLST Master List assembly can be overridden, for any reason, by providing this option. The nnnnn must be replaced by a number in the range 4096-32767. This option is always accepted but only used if it occurs before the first function that opens the CXX.
  • DATANO=
    nnnn
    The number of data buffers as set in the DBMSTLST Master List assembly can be overridden, for any reason, by providing this option. The nnnn must be replaced by a number in the range 3-9999. Some DBUTLTY functions need minimal data buffers and some would benefit with a large number. This option is always accepted but only used if it occurs before the first function that opens the CXX.
  • DELAY_INSIDE=
    nnn
    This option speeds testing in QA systems. This option is used to test contentions between various functions and either each other or non-DBUTLTY opens. After the equal sign, specify a three-digit number from 000 through 999. The value is saved, and during selected functions a delay within the function's main-line processing a delay occurs to lengthen the execution of the function. Functions include the following:
    • BACKUP
    • EXTEND
    • EXTRACT
    • INIT
    • LOAD
    • REMOVE
    • RECOVERY
    • REORG
    • RETIX
    • SPILL
  • DELAY_SECONDS=
    nn
    This option speeds testing in QA systems. After the equal sign, specify a two-digit number from 00 through 99. Processing the statement causing the DBUTLTY program to delay the number of seconds specified. It is used to change timing test cases, usually involving multiple concurrent DBUTLTY Job executions in parallel.
  • DELAY68
    Allows you to override, in special cases, the DBSIDPR settings for the DBSYSID parameter DELAY68=. It can be set to 0 through 9 or 00 through 99.
  • DELAY85
    Allows you to override, in special cases, the DBSIDPR settings for the DBSYSID parameter DELAY85=. It can be set to 0 through 9 or 00 through 99.
  • DUMPPGM=
    name
    Allows you to specify the name of a program that DBUTLTY is to load into memory and format print it. This was built to assist support, ensuring content of modules relating to solutions. As an extension, if you want to allow either a DBSIDPR module name or an alternate name for a DBSYSID macro assembly, change to load and print in dump format when requested by Support.
  • DXXNO=
    nnnn
    The number of DXX buffers as set in the DBMSTLST Master List assembly can be overridden, for any reason, by providing this option. The
    nnnn
    must be replaced by a number in the range 3-9999. Some DBUTLTY functions need minimal data buffers and some would benefit with a large number. This option is always accepted but only used if it occurs before the first function that opens the CXX.
  • ECHO_FUNCTIONS
    This option causes the first statement of each function to be sent to the console to aid in debugging or tracking the function being executed. This option can be helpful in seeing which other console messages occurred by which functions. There is no equal sign and no additional values after the function name. It can be easier to see the function being executed in the log instead of going to the bottom of the print. The action once requested cannot be turned off. Following is an example:
    DB10098I - STARTING FUNCTION - REPORT AREA=CXX,DBID=0997,TYPE=B
  • EOJ_REPORT
    This option is intended to only be used in consultation with
    Broadcom Support
    . EOJ_REPORT requests that reports be generated at end of the current DBUTLTY execution, similar to the way in which MUF EOJ reports are generated. Information that is specific to the MUF is excluded from the report requested by EOJ_REPORT, for example Memory Resident Data Facility (MRDF) Summary Information reports and Task Control Block (TCB) Use Summary Information reports are excluded. The EOJ_REPORT option includes a PXX-like summary report. DBUTLTY functions use fast path processing and all statistical information normally present in the MUF may seem inconsistent. For example, a BACKUP shows I/O to the index and data areas but no requests to the tables. This result is not an error in DBUTLTY. The action once requested cannot be turned off.
  • EOJ_REPORT_X
    This option is intended to only be used in consultation with Support. While the EOJ_REPORT option requests that reports be generated at the end of the current DBUTLTY execution, the EOJ_REPORT_X option requests a report be generated at the end of the execution of most DBUTLTY functions. For information about what is produced, see the previously provided description of EOJ_REPORT. The action once requested cannot be turned off.
  • IXXLN=
    nnnn
    The length of an index buffer as set in the DBMSTLST Master List assembly can be overridden, for any reason, by providing this option. The
    nnnn
    must be replaced by a number in the range 4096-8182. This option is always accepted but only used if it occurs before the open of the CXX.
  • IXXNO=
    nnnn
    The number of IXX buffers as set in the DBMSTLST Master List assembly can be overridden, for any reason, by providing this option. The
    nnnn
    must be replaced by a number in the range 3-9999. Some DBUTLTY functions need minimal data buffers and some would benefit with a large number. This option is always accepted but only used if it occurs before the first function that opens the CXX.
  • MUF_NOT_ENABLED
    Functions that normally execute with MUF enabled but can execute with the MUF not enabled exist for special situations where a MUF cannot enable due to restart errors. Such restart errors have to be (or can be) corrected before MUF successfully enables. These functions can run in the same DBUTLTY step as a function that has to run with MUF not enabled, or they have to declare the intent to run this complete DBUTLTY step with MUF not enabled. To do this, the SET function with OPTION1=MUF_NOT_ENABLED is used. The use of this SET option is invalid if the DBUTLTY step has already connected to a MUF or opened the CXX locally. The function converts all following functions from being able to run with MUF not enabled to being required to run with MUF not enabled for this execution of DBUTLTY. This ability is not expected or recommended for use by functions that cannot complete quickly. These functions are explained in another section. This SET option removes any DELAY68 value set in determining if the MUF is enabled or not enabled. For functions that expect to execute with MUF, it is best that they are allowed to have the delay to wait for the MUF to enable.
  • ON-ERROR-CONTINUE
    If an error condition exists, future functions are edited and processed as though an error condition did not exist. Various system failures can occur that the operating system considers fatal and that prevent continued operation. For example, in z/OS one such error is a B37 abend. The error condition is not reset based on the successful completion of this or a future function.
  • ON-ERROR-STOP
    If an error condition exists, future functions (excluding SET and EDIT) are syntax edited but are not executed. This is the default at the start of each step. Use of this function sets this action for future functions.
  • ON-ERROR-ABEND
    Dictates the action taken after the last function is complete for the step. This is the default at the start of each step. If an error condition then exists, the step is terminated with an z/OS ABEND 4 or a z/VSE CANCELDictates action is taken after the last function is complete for the step. This is the default at the start of each step. If an error condition then exists, the step is terminated with an z/OS ABEND 4 or a z/VSE CANCEL
  • ON-ERROR-RCn
    Dictates the action taken after the last function is complete for the step. The number in the parameter (
    n
    ) can be 0, 4, 8, or 12. If an error condition then exists, the step is terminated with the return code of the number provided.
  • ON-ERROR-REMOVE
    Removes an error condition. From this point following, functions are edited and executed and, unless errors occur in them, the step terminates with a return code 0.
  • SID_CONNECT=a
    This option exists to speed testing in QA systems. After the equal sign you can specify a letter L (for LOCAL), X (for XCF), or C (for CCI). This is similar to what exists in the DBSYSID Macro used to generate a DBSIDPR module, keyword CONNECT_ALLOW_PRIORITY=. This testing option is not edited (checked) for valid letters. It is always accepted but will only have affect if done before the first function that attempts to connect to MUF.
  • SIDNAME=name
    When a DBSIDPR is used by DBUTLTY that has a TARGET_MUF_LIST= with multiple entries, most functions work exactly like a user program would, and DBUTLTY finds the MUF locally or remotely and executes against it. Some functions target the MUF and do not have to run on the right LPAR for success. For example, if two MUFs are enabled and a DBUTLTY EOJ is executed, it ends the MUF that is local to the LPAR on which DBUTLTY executes unless it contains neither MUF, in which case it EOJs either of the MUFs, based upon the first MUF found. One solution is to route all DBUTLTY functions that need a specific MUF to the proper LPAR. Another solution is to force the DBUTLTY function to the desired MUF. This is done with a SET function with the keyword OPTION1=SIDNAME=name, naming the member in a library with DBSYSID macro assembly results that has specific MUF names instead of the standard DBSIDPR. Some functions need to execute at each executing MUF in a MUFplex such as ACCESS. For those cases, it is necessary to use a specific single MUF and execute ACCESS against it if enabled and then looping through all the candidate MUFplex MUFs that are enabled.
  • SNAPALL
    This diagnostic tool is available, when requested by Support, to help find a problem. Its purpose is to snap the address space after a utility function that is processed by a subordinate program completes, with or without an error condition. For example, this might be necessary if a process of a utility functions, deeming itself successful and without error, completes but has not actually completed successfully after all. This option cannot be turned off.
  • SNAPERR
    This diagnostic tool is available, when requested by Support, to help find a problem. Its purpose is to snap the address space after a utility function, processed by a subordinate program, completes with an error condition. The reason this might be necessary is that some error conditions are expected to be obvious and no dump is taken, because a dump should not be necessary to correct the condition. If the error turns out not to be obvious, however, the SNAPERR can be used to help Support with the additional information needed to find a solution. This option cannot be turned off.
  • WTO--x
    Specify WTO--x as shown, with WTO followed by two dashes, followed by a set of characters (replacing the x variable) that you want written to the console with a WTO in the DBUTLTY address space.
    The set of characters specified by x have a length restriction imposed by the number of characters that fit on one input statement. Given that the SET OPTION1=WTO-- is 17 characters long and starts in column 1 (with the S in SET), and given that the last column in which the last possible character could occur is column 71, subtracting 17 from 71 gives a maximum of 54 user-characters (for the
    x
    ), if blanks are not required (see following explanations) and 52 user-characters if blanks are required (due to two places being required for two single quote characters, as described in the next paragraphs).
    If the set of characters that comprise the
    x
    have blank spaces embedded in them, they must be surrounded by single quotes. Otherwise, OPTION1= terminates on the first blank. If single quotes are used, however, those single quote marks are not printed. For example, BEGIN DATABASE 22 would be specified as follows:
    SET OPTION1='WTO--BEGIN DATABASE 22'
    An example of the result of the SET function just shown would be that it generates the message:
         DB10099I - USER WTO--BEGIN DATABASE 22.
    If the set of characters that comprises the
    x
    do not have blank spaces embedded in them, the single quotes are not needed. For example, BEGIN_DATABASE_22 would be specified as follows:
    SET OPTION1=WTO--BEGIN_DATABASE_22
    If using a value for a keyword that starts with a quote, the end is the next quote. It is not possible to provide a value that has both a blank and a quote.
Example JCL (SET)
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
.
// EXEC PGM=DBUTLTY,REGION=2M //STEPLIB
See the previous note
.
//SYSIN DD * Command Input SET OPTION1=ON-ERROR-STOP SET OPTION1=ON-ERROR-CONTINUE
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 SET OPTION1=ON-ERROR-STOP FUNCTION=SET OPTION1=ON-ERROR-STOP
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.
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 SET OPTION1=ON-ERROR-CONTINUE FUNCTION=SET OPTION1=ON-ERROR-CONTINUE
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.