The DIF started task - syncsort_cobol_migration_manager - syncsort_clone_center - syncsort_space_recovery_system - syncsort_scc_monitor - syncsort_simulate_2000 - syncsort_allocation_control_center - Latest

DIF execution JCL

DIF JCL

statement definitions

This section of the user manual describes the execution JCL used by the Dynamic Install Facility (DIF). If not already installed, the execution JCL can be copied from the DIF member of the product’s install library, and placed in a system procedure library - SYS1.PROCLIB, or an equivalent library. The following table shows the job control statements necessary for using DIF.

STATEMENT USE

PROC Procedure statement for the started task.

EXEC Specifies the program name for the Dynamic Install Facility: PGM=DIF

STEPLIB DD This is a required file. Defines one or more input partitioned

data set(s). These DD statements are allocated to the load libraries required for executing DIF and the products. Note: All the libraries allocated to STEPLIB must be authorized.

PARMLIB DD This is a required file. Defines a partitioned data set used for

parameter processing by DIF and the products. During DIF initialization, DIF reads control statements from the following members in the following order:

• the DIFINIT member
• a member name created by concatenating the four character system identifier (SYSID) with “nn”. For example, if DIF is starting on system A, DIF would process commands from SYSA00.
• the member STARTnn

The “nn” characters default to “00”, but can be overridden by the START parameter field in the DIF execution JCL. The member(s) are usually used to issue START and ENABLE commands for the products.

The DIFINIT member is processed very early in during DIF initialization. This member can be used to modify OPSYS flags or pass parameter information to DIF with the INITOPT command. DIFINIT should not be used to activate products.

RULECKPT DD (OPTIONAL) After the rule compiler successfully converts a

rule member, the rule conversion process examines the DIF started task for the RULECKPT DD statement. If the checkpoint file is available, rule conversion writes the converted rule member to the checkpoint data set: DTS.DIFR71.RULECKPT.

The checkpoint data set is a PDS, and the checkpoint process adds the rule name to the directory. By overlaying the existing checkpoint members whenever possible, space abends during the checkpoint process should be very rare.

LPALIB DD

Required. Defines an input partitioned data set, usually SYS1.LPALIB. When DIF is performing the product installation, DIF will determine the location of the operating system modules being frontended: LPALIB or MLPALIB. If the module resides in LPALIB, DIF will read the load module text records from the LPALIB DD statement to obtain information required to frontend modules in LPA. Therefore, the library allocated to this DD statement must contain the running versions of the load modules being frontended.

If SYS1.PARMLIB(LPALSTnn) is used to concatenate one or more libraries to SYS1.LPALIB, these libraries should be concatenated on the LPALIB DD statement.

MLPALIB DD

Optional. Defines an input partitioned data set. When DIF is performing the product installation, DIF will determine the location of the operating system modules being frontended: LPALIB or MLPALIB. If the module resides in MLPALIB, DIF will read the load module text records from the MLPALIB DD statement to obtain information required to frontend modules in MLPA. Therefore, the library allocated to this DD statement must contain the running versions of the load modules being frontended.

SYSPRINT DD

Required. Defines a sequential output data set used for listing actions taken by DIF during dynamic install processing. As delivered, this file will use SYSOUT class A. If a nonexistent sysout class is specified, the system will purge the SYSPRINT file after DIF terminates.

The DCB information follows: DCB=(LRECL=80,RECFM=FB).

SYSABEND DD (OPTIONAL) Defines an output data set used for listing the output obtained if an abend occurs.

SYSEXEC DD (OPTIONAL) This DD statement should be allocated to one

or more REXX Exec libraries. The DIF TSO command can execute Execs from the SYSEXEC file.

SYSPROC DD (OPTIONAL) This DD statement should be allocated to one

or more Clist libraries. The DIF TSO command can execute Clists from the SYSPROC file, as well as TSO command processors.

SYSTSPRT DD (OPTIONAL) This DD statement should be allocated to a

temporary data set. For performance considerations, this file should use UNIT=VIO. This file is used by the DIF TSO command.

SYSTSIN DD (OPTIONAL) This DD statement should be allocated to

DUMMY. This file is opened by the TMP when DIF processes a TSO command.

Figure 6-1. The DIF Control Statements

Sample DIF PROCLIB Member

The following procedure is an example of the Dynamic Install Facility (DIF) JCL that would be found in SYS1.PROCLIB, or a related library. Once in a production environment, a START DIF command should be added to SYS1.PARMLIB(COMMNDnn) to automatically start DIF during system initialization. The PARMLIB DD statement can be used to automatically start the products during DIF initialization.

A list of the load modules required for the dynamic installation of a product can be obtained from the control statements used to link-edit modules into an authorized library. Examine the LINKDIF of the product’s installation library.

          *********************************************************************
          *                                                                   *
          * DYNAMIC INSTALL FACILITY (DIF)                       *
          *                                                                   *
          *********************************************************************
          //DIF     PROC P=
          //DIF     EXEC PGM=DIF,DYNAMNBR=20,TIME=1440,REGION=4M,
          //             PARM='CMDCHAR=#,TSO=NO,&P'         
          //STEPLIB DD DISP=SHR,DSN=DTS.R71.LOADLIB
          //PARMLIB DD DISP=SHR,DSN=DTS.R71.PARMLIB
          //         DD DISP=SHR,DSN=DTS.R71.RULELIB
          //RULECKPT DD DISP=SHR,DSN=DTS.R71.RULECKPT
          //RTMDB   DD DUMMY
          //LPALIB  DD DISP=SHR,DSN=SYS1.LPALIB
          //*MLPALIB DD DISP=SHR,DSN=mlpa.library
          //SYSPRINT DD SYSOUT=A
          //SYSABEND DD SYSOUT=A
          //*SYSEXEC DD DISP=SHR,DSN=rexx.library
          //*SYSPROC DD DISP=SHR,DSN=clist.library
          //*SYSTSPRT DD UNIT=VIO,SPACE=(CYL,1)
          //*SYSTSIN DD DUMMY
        

DIF - PARM Information

When DIF is started, the initialization process will read the parameter information from the PARM field on the EXEC statement. Since the PARM field is limited to 100 characters of parameter information, the INITOPT commands in the DIFINIT member can also be used to pass parameter information to DIF. The following parameters can be used to pass installation dependent information to the Dynamic Install Facility.

CMDCHAR

Function: The CMDCHAR parameter specifies the DIF subsystem character, which can also be used to enter DIF commands from the console. The pound (#) is the default character, but this operand can be used to select the desired subsystem character.

If CMDCHAR=NONE is specified, only the MODIFY form of the DIF commands will be processed.

Default: CMDCHAR=#

Format: Any valid subsystem command character, or NONE

COLD

Function: During initialization, DIF dynamically establishes the subsystem control blocks required for the DIF subsystem processing. By default, DIF will use any existing subsystem control blocks found during initialization.

If COLD=YES is specified, DIF will invalidate the old subsystem, and build a new set of control blocks. The SUBSYS parameter defines the name of the DIF subsystem.

Default: COLD=NO

Format: YES or NO

CONTACT

Function: To activate DIF mini-dump processing, add the following control cards to the DIFINIT member in the DIF parmlib data set.

DTS.R71.PARMLIB. The contact information allows four positional fields separated by commas or blanks. Each line can be up to 50 characters. This information will be added to the content of the minidump, and will ensure customer support can match dumps with the proper installation.

INITOPT CONTACT(line1,line2,line3,line4) INITOPT
          MINIDUMP(HLQ(DTS.MINIDUMP) STC)

CSRLOG

Function: The CSRLOG parameter can be used for DIF problem determination, and should only be used when requested by technical support. If CSRLOG=n is specified, the DIF common service routines write messages to the SYSPRINT DD statement in the DIF started task. Only messages with a log level less than or equal to the numeric value specified on the CSRLOG parameter are written to SYSPRINT.

Default: CSRLOG=None

Format: A numeric value between 0-20.

CUSTOMER

Function: The CUSTOMER parameter can be used to specify the account number assigned to your installation by Precisely. This account number is required for support calls and is very helpful for the support to locate the account information on support calls. This is especially helpful for customers running in hosted environments or service bureaus.

If the customer site is running in an On/Off Capacity On Demand environment, the OOCOD parameter activates DIF capacity on demand monitoring. Statistics will be maintained about the changes in CPU capacity, and can be displayed using the DIF CUSTOMER command.

If SENDCPU has been specified, the capacity on demand statistics are written to a log file (DIFSLOG) in the DIF started task and will also be automatically uploaded to a license server if allowed by the company network.

Default: CUSTOMER=None

Format: CUSTOMER(ID=DTSnnnn OOCOD SENDCPU)

DATE

Function: The DATE parameter can be used to specify the Gregorian date format used by DIF and products. The selected format denotes the location of each date component. In other words, when a user specifies a date, the YY component can be specified as a four-digit field and the MM and DD components can be single digits.

Default: MM/DD/YY

Format: MM/DD/YY, DD/MM/YY or YY/MM/DD

DIFTSO

Function: By default, the DIF commands can only be entered from an operator console or parmlib members. The DIFTSO parameter can be used to enable the DIFTSO command interface, and assign a TSO command name to the interface. The TSO command processor can then be used to enter DIF commands. The output from the commands are returned to the TSO user.

Default: None

Format: Any valid TSO command name. Please make the command name unique for your system.

DM

Function: This parameter can be used to deactivate the DIF Display Memory (DM) command.

Default: DM=YES

Format: YES or NO

DST

Function: During initialization, DIF allocates buffers for an internal table called the DST. This parameter should only be used when requested by technical support.

Default: DST=30

Format: Any numeric value

EXEC

Function: The CONNECT(member) keyword parameter can be used to execute the DEFCONN commands located in the specified member in DIF PARMLIB DD library. Since the DEFCONN commands and statements share the same syntax, for more information, see “DEFCONN” in the Rules Language Programming Guide.

The DEFCONN commands are used to route log records to MQSeries message queues or the system logger. This feature allows records to be routed to a single DIF. This “master” DIF is defined with the LOGSERVER parameter, and is used to consolidate log records and write them to a log file.

The DEFCONN commands can also be used to establish TCP/IP connections using the TCP or UDP protocols.“Send Messages and Records using TCP/IP” on page 4-25 in the Rules Language Programming Guide.

FORCE

Function: The FORCE parameter determines whether the Dynamic Install Facility (DIF) ZFORCE command can be issued. If used improperly, the ZFORCE command can corrupt system control blocks and load modules. If FORCE=NO is specified, the ZFORCE command will be deactivated.

Default: FORCE=YES

Format: YES or NO

JCL

Function: By default, DIF can determine whether the operating system supports the Scheduler JCL Facility (SJF). This facility is used to support the extended JCL parameters used by the operating system.

Default: None

Format: YES or NO

KEY

Function: The KEY parameter specifies the PSW key used by the Dynamic Install Facility (DIF).

Default: KEY=6

Format: Any valid PSW key (0-15)

LANG

Function: The LANG parameter specifies the default language used by the Dynamic Install Facility (DIF). If message tables are available for the requested language, the product will use the tables for message processing. If not available, the product uses the English versions of the message tables.

Default: LANG=ENGLISH

Format: Language name. Please contact technical support for the current list of available languages.

LICENSE

Function: During product initialization, DIF reads a PDS member to validate product license information. By default, the member LICENSE in the DIF PARMLIB DD statement contains the license information.

Default: LICENSE=LICENSE

Format: Any valid PDS member name

LOG

Function: The LOG parameter controls the function logging messages used by the Dynamic Install Facility (DIF). The logging messages are used for debugging, and should only be used when requested by technical support.

Default: LOG=NO

Format: YES, NO, or CSR

LOGBUF

Function: During initialization, DIF allocates a buffer for message logging. Whenever a message is to be logged to a DD statement in the DIF started task, a log buffer in the DIF address space is used to temporarily store the message until an I/O can be performed.

For operating systems that support dataspaces (IBM OS/390 and z/OS), a dataspace is created for the DIF address space and the log buffer is created in the dataspace. In these environments, the number of entries in the log buffer can safely be increased far beyond the default of 3000 entries.

Hitachi VOS3 systems - By default, when DIF obtains the message buffer on Hitachi VOS3 systems, the buffer is obtained from Extended CSA. In these environments, the default number of log entries is lowered to 100.

However, Hitachi VOS3 systems with a processor mode of operation set to either M/ASA mode or M/64 mode have optional Cross Memory Services support. If your VOS3 installation has enabled Cross Memory Support (CM=YES in the JAASYSnn member in SYS1.PARMLIB), please add the ENABLE OPSYS CM command to DTS.R71.PARMLIB(DIFINIT). After a DIF restart to activate Cross Memory Service support in DIF, message processing will use a buffer in the DIF address space and the default buffer size is set back to 3000 entries.

On the LOGBUF parameter, the first numeric field specifies the number of log entries, and the second numeric field specifies the maximum record length. The third field is the interval DIF uses between log scans in seconds.

Default: LOGBUF=(3000,500,3)

Format: The number of entries in the log buffer is limited to the available memory in the DIF address space. The length can be any numeric value between 250 and 1024.

LOGSERVER

Function: When multiple DIF address spaces are active in your sysplex, the LOGSERVER operand allows your installation to consolidate log records to a single data set. LOGSERVER should be specified on one DIF running in the sysplex to act as a log server.

The non-LOGSERVER DIF started tasks: To perform log consolidation, the other DIF started tasks must use DEFCONN statements to route log records to the system logger or an MQSeries message queue. The DEFCONN statements are typically executed via the EXEC CONNECT parameter to forward records to a message queue or log stream.

Normally, when a product rule issues a WRITEMSG or WRITEREC, the data is scheduled for log processing with a cross memory move to a buffer in the local DIF started task. DIF will pick up the queued log records from the buffer and use the DEFCONN commands obtained from the EXEC CONNECT parameter to forward the record to the requested queue.

The LOGSERVER DIF started task: The LOGSERVER parameter defines a DIF that is used to read the queues and consolidate the log records. Specify the LOGGER or MQSERIES subparameter to select the streamname or message queue used by the other DIF address spaces to pass records.

When the LOGSERVER DIF receives a record, a destination header that was prefixed to the record is removed, and the record is forwarded to the log file requested by the destination header. Therefore, only the LOGSERVER DIF requires the DD statements for the log files.

For more information, see “Using MQSeries to Consolidate Log Records” and “Using the System Logger to Consolidate Log Records” in the Rules Language Programming Guide.

Default: None

Format: LOGSERVER=(LOGGER(streamname) MQSERIES(qname))

MAXRULES

Function: During initialization, DIF allocates the rule control table. One entry is required for each rule member used by a product. Each product subrule also requires one entry in the table. The MAXRULES parameter can be used to specify the maximum number of rule and subrule members that can be processed by DIF.

Default: MAXRULES=100

Format: Any numeric value

MINIDUMP

Function: The mini-dump facility is active by default. However, it can be controlled by adding control cards to the DIFINIT member in the DIF parmlib data set: DTS.R71.PARMLIB.

        INITOPT CONTACT(line1,line2,line3,line4)
        INITOPT MINIDUMP(HLQ(SYS1.DTSDUMP) STC)
      

Use the HLQ keyword parameter to specify one or more qualifiers to prefix the minidump data set names. By default, the space values for minidumps are SPACE=(CYL,(1,1)) using the system default unitname for disk - UNIT(SYSALLDA).

When STC is specified on the MINIDUMP control card, the dump processing facility issues a S DIFFDMP,DUMP=minidump.dataset.name operator command after creating the dump. An installation can then use the DIFFDMP started procedure to notify support personnel about the problem and/or route the dump data set directly.

To use the STC feature, issue the following DIF console command, or add the command to the START00 member in the parmlib data set: DTS.R71.PARMLIB.

        F DIF,S DIFDUMP
      

Default: MINIDUMP(HLQ(SYS1.DTSDUMP) SPACE(1 1) UNIT(SYSALLDA))

Format: MINIDUMP (HLQ (hlq) SPACE( pri,sec) UNIT(unitname) STC)

OPERCMD

Function: If the OPERCMD(BUFFER(len)) is specified in the DIF startup parameters, command output can be captured using a subsystem console. The extended CSA storage is used to buffer the command output. This facility is typically used by SCC Explorer to allow a PC user to issue z/OS commands and get the output of the command back to the Explorer GUI.

Default: OPERCMD(BUFFER(0))

Format: OPERCMD(BUFFER(kilobytes))

OPSYS

Function: The OPSYS parameter can be used to specify the operating system environment that DIF will execute within. In a z/OS environment, OPSYS=CVT will use the FMID obtained from the CVT prefix. An internal DIF table can then be used to determine which operating system facilities are available. For more information about these facilities, examine the DIF OPSYS console command.

Default: OPSYS=CVT

Format: CVT, MSP20AE, MSPEX, VOS3ES, VOS3AS or VOS3FS

OPTION

Function: The OPTION parameter can be used to establish defaults for DIF service routines.

• CDR - When DIF collects information about volumes, the algorithm can obtain CDR information as well if the OPTION=CDR parameter has been specified.
  Note: This option is disabled by default due to the overhead associated with the calls to the z/OS routine IOSCDR. This parameter is required for the rules to access the CDR_* symbolic fields.
• ENFWTO - DIF has an Event Notification Facility (ENF) routine that is used by products to monitor devices coming or going offline. The interface triggers rules refresh commands when one or more devices come online. For debugging, the ENF exit originally issued a WTO message (DIF20610) for non-SMS volumes. However, under very rare conditions the WTO can cause a loop and stack up WTOs in a system. The WTO for message DIF20610 is now optional. To enable the debugging message, specify the ENFWTO keyword parameter.

Default: None

Format: OPTION=(CDR, ENFWTO)

PCMD

Default: PCMD=NONE

Format: NONE, SHUTDOWN or Z

RESPDEFT

Function: The DIF started task contains a subtask that collects performance data for online DASD devices. The RESPDEFT parameter can be used to control sampling and performance calculations.

This parameter has four numeric operands:

• The first positional operand defines the number of response time samples that will be kept for each online DASD device. At each sample interval, the response time for each device is calculated and saved. Once the maximum number of intervals specified by this parameter is reached, the data acquisition will begin overlaying existing entries in the response time tables. By default, 60 samples are kept for each device.
• The second positional operand defines the time to wait between response time sampling. This operand is specified in seconds and is used by the data acquisition task running in the DIF address space. By default, no sample interval is specified and the data collection subtask is not active. If 30 is specified, the DASD performance data is sampled every 30 seconds.
• The third positional operand defines the default DASD response time. During product initialization, the response time tables are initialized with the default DASD response time value. This value is also used by the sampling routines when the response time for an interval cannot be calculated (no EXCPs occurred during the interval). This operand is specified in milliseconds (MS), and defaults to 30 MS.
• The last positional operand defines a penalty factor used by the RESPTIME volume selection algorithm. When RESPTIME is evaluating a candidate device, and the device has already been selected for another DD statement in the task, RESPTIME will add the penalty to the response time for the device. The penalty will force RESPTIME to spread the allocation requests among the best performing devices. This operand is specified in milliseconds (MS) and defaults to 12 MS.

Default: RESPDEFT=(0,12,30,12)

Format: RESPDEFT=(num_samples,sample_time,dft_resptime,penalty_factor)

RULEREFR

Function: When a refresh is performed on a rules member, the original rule member is not freed until a DIF subtask determines that all active products are using the new rules. The RULEREFR parameter determines how often the subtask examines the refresh queue and the number of intervals required for the subtask to assume the rules are not being used and free the rules.

Default: RULEREFR=(60,30)

Format: RULEREFR=(maxcount, interval_time)

SERVER

Function: The SERVER parameter establishes a remote DIF command request queue using APPC, TCP/IP, or an MQSeries message queue. This queue allows workstations to issue DIF commands and receive the responses. Requestors can use an MQSeries message queue and/or TCP/IP.

For TCP/IP connections, the server can also be used by remote applications to request copies of messages and/or records being routed to specific log files. For example, the ABC/TI application used to monitor tape mount messages watches for messages being written to the ABCTM DD statement found in the DIF started task.

When TCPIP is specified on the SERVER parameter, enter the name of the TCP/IP started task running on the host (typically TCPIP) and a port number used for communication. Port numbers are installation dependent. Ask the network administrator for an available port.

For more information, examine the PORT control card found in the PROFILE DD statement allocated to the TCPIP procedure.

For example, this card can be placed in DTS.R71.PARMLIB(DIFINIT). The card specifies the TCPIP jobname running on z/OS (TCPIP), and the port number to be used by DIF (10 in the example).

        INITOPT SERVER(TCPIP(TCPIP 10))
      

DIF can also be configured to activate a Webserver Interface by specifying a second port number on the TCPIP parameter. This port is used by DIF to listen for HTTP requests. DIF would not normally be set up to use the default HTTP port of 80, but instead use an installation-defined port.

In the following example, the DIF Webserver Interface has been configured for port 12. The web interface can be used to issue DIF commands or used by an Excel spreadsheet or Crystal Reports to run Monitor to obtain real-time records in an XML format.

For more information about using the web service interface, please obtain the white paper on the DIF Webserver Interface from the Precisely website, or contact Customer support.

        INITOPT SERVER(TCPIP(TCPIP 10 12 WEB(tso-user)))
      

Default: None

Format: SERVER=(MQSERIES(qname) TCPIP(jobname portnum webport WEB(tso-user)))

SITEWARN

Function: If enabled, the SITEWARN parameter will cause message DIF00608-I *** prdname USES SITE LICENSE KEY *** to be issued to the DIF SYSPRINT dataset and the system console with descriptor code 2. prdname is the name of the product.

The message will be issued at startup and at each license validity/expiration check interval (the intervals are set by the TIMER(EXP(nnnnn)) parameter), or when a DIF CHECK prdname LICENSE command is issued.

Default: SITEWARN=NO

Format: SITEWARN=YES

START

Function: The PARMLIB DD statement normally defines a partitioned data set used for parameter processing by DIF and the products. During DIF initialization, DIF reads control statements from two members: a member name created by concatenating the four character SYSID with “nn”, and the member STARTnn.

The member(s) are usually used to issue START commands for the products. The “nn” characters default to “00”, but the START=nn parameter can be used to override suffix characters.

Default: START=00

Format: Any two characters

STPARM

Function: The PARMLIB DD statement normally defines a partitioned data set used for parameter processing by DIF and the products. During DIF initialization, DIF reads control statements from two members: a member name created by concatenating the four character SYSID with “nn”, and the member STARTnn. The member(s) are usually used to issue START commands for the products.

The STPARM parameter can be used to specify the name of an additional start processing member that will be processed after the SYSIDnn and the STARTnn members.

Default: None

Format: Any valid PDS member name

SUBSYS

Function: During initialization, DIF dynamically establishes the subsystem control blocks required for the DIF subsystem processing. The SUBSYS parameter defines the name of the DIF subsystem.

Default: SUBSYS=DT71

Format: Any valid four character subsystem name

SYSPARM

Function: The SYSPARM parameter on the DIF EXEC PARM field, or on an INITOPT statement in the DIFINIT member, can be used to set a local SYSPARM variable that can be used by rules or any input records being read by the DIF started task or subtasks.

Example usage:

• SYSPARM=MP3000
• SYSPARM=(MP3000 KEY(CMPNAME))

The value is saved by the DIF started task and can be accessed using the SYSPARM(INCLUDE(value)) or SYSPARM(EXCLUDE(value)) statements found in the input statements being read by DIF. These statements must start in column one.

Several sample SYSPARM statements follow. The last SYSPARM statement disables statement filtering.

SYSPARM(INCLUDE(MP3000)) 
 ...
SYSPARM(INC(MP3000) KEY(CMPNAME)) 
 ... 
SYSPARM(INC(SUNDAY) KEY(&DAY:CURDATE))
 ...
SYSPARM(EXC(SAT* SUN*) KEY(&DAY:CURDATE))
 ...
SYSPARM

Default: None

Format: SYSPARM=(value [KEY(key)])

TIMER

Function: The TIMER parameter can be used to override the wait intervals on DIF subtasks:

• the Event Notification Facility (ENF)
• the Device Performance subtask (DPT)
• the license expiration warning subtask (EXP)
• the TCP/IP listening command timeout value (TCPCMD)

The DIF Event Notification Facility subtask watches for devices coming online, and performs automatic rule refresh commands for products that have device pools in the rule definitions.

If enabled, the DPT subtask captures device performance information for the performance-based volume selection algorithm used by ACC and SRS.

The license expiration warning subtask (EXP) wakes every 24 hours to notify your organization about approaching license expiration dates. By default, warnings are issued when the license is within 30 days of expiring. The LICENSE parameter can be used to change the warning period.

The TCP/IP listening service in DIF is activated by a request from a client. If the conversation is interrupted before being terminated by the client, the TCPCMD value is used to close the conversation after the specified interval of no activity.

TIMER=( ENF(10)
DPT(60)
EXP(86400)
TCPCMD(180) 
LICENSE(30))

TSO:

Function: The TSO parameter determines whether TSO commands and Clists can

be executed as DIF subcommands on an operator console. The DIF TSO command will attach the TMP in the DIF address space, and execute the requested command. Warning, enabling this command may have the ability to bypass your security system. Note: This parameter also controls the use of the MVSFUNC command from non-GUI callers.

If you choose to disable the DIF TSO command, the SYSEXEC, SYSTSPRT, SYSTSIN, and SYSPROC DD statements can be removed from the DIF execution JCL.

Note: The TSO parameter is not related to the DIF TSO command interface that allows TSO users to issue DIF commands. To enable the TSO commands interface, examine the preceding DIFTSO parameter.

Default: TSO=NO

Format: YES or NO

Mini-dumps

If an SCC product abends, a product ESTAE routine formats a few output lines containing the PSW, registers, and the module back-chain calling list. Installations can also allow SCC products to take the normal system or SVC dumps. A third option is also available - installations can use the MINIDUMP facility to create small mini-dump data sets.

These mini-dumps are typically around 20K and contain customer contact information, the PSW and registers at abend, all internal product workareas, and relevant system control blocks.

Procedures can be activated to notify support personnel about the problem. Additionally, at the customer’s discretion, dumps can also be automatically emailed or FTP’d directly. Note: Unlike typical system or SVC dumps, debugging information is limited to the internal fields most likely to help quickly solve a problem.

How to Disable Mini-Dumps - The mini-dumps are enabled by default. If you wish to disable the creation of mini-dump data sets, add the following statement to the DIFINIT member in the DIF parmlib data set: DTS.R71.PARMLIB:

INITOPT MINIDUMP(HLQ(*))

Setup for mini- dumps

To activate DIF mini-dump processing, add the following control cards to the DIFINIT member in the DIF parmlib data set: DTS.R71.PARMLIB. After the next DIF restart, mini-dumps will be created for SCC product abends. Note: The contact information allows four positional fields separate by commas or blanks. This information will be added to the content of the minidump and will ensure the support can match dumps with the proper installation.

INITOPT CONTACT(joe_user, 919-123-4567,acme_corp, city_name) INITOPT MINIDUMP(HLQ(SYS1.DTSDUMP) STC)

Automatically transmitting mini- dumps to Precisele Syncsort

If STC was specified on the MINIDUMP control card, the dump processing facility will issue a “S DIFFDMP,DUMP=minidump.dataset.name” operator command after creating the dump. An installation can then use the DIFFDMP started procedure to notify support personnel about the problem and/or route the dump data set directly. To use the STC feature, issue the following DIF console command, or add the command to the START00 member in the parmlib data set: DTS.R71.PARMLIB.

F DIF,S DIFDUMP

A sample DIFFDMP dump procedure can be found in the samplib: DTS.R71.SLyyddd.SAMPLIB(DIFFDMP). Examine the sample procedure, and copy the member to a system procedure library (i.e. SYS1.PROCLIB or equivalent library). Note: The password for the FTP server found in the procedure is case sensitive, and must be specified in lowercase.

Where to write mini- dumps?

Since the abends typically occur in environments where data sets cannot be created, the dump information is normally routed through the DIF started task. DIF will create the mini-dumps using the HLQ obtained from the MINIDUMP statement using the following format:

hlq.Ssysid.Dyyddd.Thhmmss

Special DDnames for reproducible problems

If a problem is reproducible, a special DD statement ($DIFDUMP) can be activated for product debugging. For example, the following DIF console command can be used to activate the debugging environment for ACC:

F DIF,SET ACC DEBUG ON

After activating the debug environment, the $DIFDUMP DD can be added to a test job. The mini-dump processor can then be used to route the dump to one or more destinations using the LRECL field on the $DIFDUMP DD statement.

x’80’ copy dump to the mini-dump (I/O routed through the DIF address space) x’40’ copy dump to the mini-dump (I/O done from test job address space) x’20’ copy dump to the JOB log

x’10’ copy dump to WTO routcde 2

For example, the following DD can be added to a test job to route copies of the mini-dump through DIF to a data set, a copy to the JOB log, and a copy to WTO RC=2 (write to programmer). Note: x’80’ + x’20’ + x’10’ = x’B0’ = decimal 176

//$DIFDUMP DD DUMMY,DCB=LRECL=176

DEFCONN Command

The DEFCONN command(s) are usually executed by the EXEC CONNECT command located in the DIFINIT parmlib member. The commands are executed during DIF initialization.

A DEFCONN command defines a connection between a ddname used by the product rule language statements and a message destination. When product rules write a message or record to a ddname, the record is sent to the DIF log buffer. DIF message processing will reroute the message to a:

• TCP/IP Server
• SYSLOGD Daemon
• MQSeries message queue
• the system logger
• direct writes to an HFS file

NOTE: There is also a DEFCONN statement found in product rules that do not contain the TCPIP and SYSLOGD parameters. The DEFCONN rules statement is very rarely used - the DEFCONN commands covered in this section are the more common implementation. For more information about the statement in the rules, examine “DEFCONN” on page 5-12 in the Rules Language Programming Guide.

Overview - Message or record logging is activated when the DEFMSG LOG or DEFREC DDNAME parameters been specified in the product rules. By default, when a product rule issues a WRITEMSG or WRITEREC the data is scheduled for log processing with a cross memory move to a buffer in the DIF started task. DIF will pick up the queued log records from the buffer and use the routes defined by the DEFCONN commands obtained from the EXEC CONNECT parameter to forward the records to the requested destination. For more information, examine “ROUTING MESSAGES AND RECORDS” on page 4-1 in the Rules Language Programming Guide.

TCP/IP - The DIF TCP/IP interface is used to route messages and records from the DIF log buffer to an IP server. The DEFCONN card specifies the ipaddr or dsname of the server and the port number that the server is listening on.

Note: DIF also has an interface that allows applications to receive log records from a TCP/ IP connection. This connection is established with the SERVER parameter specified in the DIF PARM field, or more likely an INITOPT command in the DIFINIT startup member. For more information, examine “SERVER” section in the Product Installation Guide.

SYSLOGD Daemon - To write messages to a syslogd daemon, simply use the DIF TCP/ IP interface and add the SYSLOGD(PRIORITY (num) and ASCII parameters. The DIF interface will prepend the syslogd header containing the priority number and convert the message to ASCII.

MQSERIES - DIF has an interface to the IBM MQSeries commercial messaging facility. This facility allows products to establish communication links with other computers, and move information between the machines or between address spaces on your mainframe.

Messages and records written by the rules language can be placed in an MQSeries message queue using the DEFCONN rules statement. The DEFCONN statement can be used to map the logs specified on DEFREC and DEFMSG statements to an MQSeries message queue. Local and remote computers that have access to the message queue can retrieve messages.

Note: Only use the DEFCONN in the rules language when you have selected the data integrity model to guarantee message delivery. The performance model uses the DIF MQSeries interface (the DIF EXEC CONNECT startup parameter) to redirect messages to MQSeries message queues. For more information about selecting the model, examine “Performance vs. Data Integrity” on page 4-17.

SYSTEM LOGGER - DIF has an interface to the IBM System Logger. This facility allows products to write log records to the system logger. For more information, examine “The System Logger Interface” on page 4-10.

The DIFMFPRT program can be used to extract messages and/or records from the system logger streams. For more information, examine “The Message Facility Print Program - DIFMFPRT” on page 3-59. For information about the system logger, examine "Chapter 9. Planning for System Logger Applications" in IBM manual "OS/390 MVS Setting Up a Sysplex" (GC28-1779).

HFS FILES - The DEFCONN HFS statement can be used in the product rules language to allow direct writes to an HFS log file. Unlike most other forms of I/O, the HFS writes can be performed from environments where I/O is typically not allowed (i.e., while running under Allocation or EOV control). The HFS interface also allows multiple tasks to simultaneously append records to the log file. For more information, examine “HFS Log Files” on page 4-9.

DEFCONN

ddname
HFS(hfspath/filename)
LOGGER(streamname)
MQSERIES(qname MQMNGR(mngrname))
NEWDDNAME(ddname)
SYSLOGD(PRIORITY (num)
TCPIP(ipaddr port_num options)
options

ddname

Function: This is a required parameter. The DEFCONN statement maps the ddname used by other statements in the rules language to an MQSeries message queue or the system logger. When a WRITEMSG or WRITEREC statement makes a request, the associated DDname specified on the DEFMSG LOG or DEFREC DDNAME forwards the message to DIF for log processing.

The DEFCONN command is used by DIF to redirect the message to a message queue. If you want to copy a message to both the DDname and message queue, examine the LOG option on the DEFCONN MQSERIES parameter.

Default: None

Format: Any valid DDname.

ddname

Function: This is a required parameter. The DEFCONN statement maps the ddname used by other statements in the rules language to an MQSeries message queue or the system logger. When a WRITEMSG or WRITEREC statement makes a request, the associated DDname specified on the DEFMSG LOG or DEFREC DDNAME forwards the message to DIF for log processing.

The DEFCONN command is used by DIF to redirect the message to a message queue. If you want to copy a message to both the DDname and message queue, examine the LOG option on the DEFCONN MQSERIES parameter.

Default: None

Format: Any valid DDname.

HFS(hfspath/filename)

Function: This is an optional parameter. The DEFCONN HFS parameter can be used to allow direct writes to an HFS log file records are not passed through the DIF Address space. Unlike most other forms of I/O, the HFS writes can be performed from environments where I/O is typically not allowed (i.e., while running under Allocation or EOV control). The HFS interface also allows multiple tasks to simultaneously append records to the log file. For more information, examine “HFS Log Files” in the product documentation.

Default: None

Format: Specify the file name for the HFS log file. The name is case sensitive.

LOGGER(streamname)

Function: This is a required field. The LOGGER parameter on the DEFCONN statement routes the records written to the DD statement to the specified system logger stream name. Please contact the systems programming or operations staff to establish the streamname required by the system logger. For information about the system logger, examine "Chapter 9. Planning for System Logger Applications" in IBM manual "OS/390 MVS Setting Up a Sysplex" (GC28-1779).

Default: None

Format: Any valid stream name. The name can be up to 48 characters long.

MQSERIES(qname)

Function: This is a required field. The MQSERIES subparameter on the DEFCONN statement redirects the records written to the DD statement to a specific MQSeries queue name. Please contact the MQSeries system administrator to establish the required qnames.

Default: None

Format: Any valid MQSeries queue name. The name can be up to 48 characters long.

MQSERIES(...MQMNGR(mngrname))

Function: The MQSERIES MQMNGR subparameter on the DEFCONN statement redirects the records written to the DD statement to a specific MQSeries queue manager name.

This is not a required field. If not specified, MQSeries will use the default queue manager name specified during MQSeries installation.

Default: None

Format: Any valid MQSeries queue manager name. The name can be up to 48 characters long.

NEWDDNAME(ddname)

Function: This field can only be specified on the DEFCONN command when executed during DIF startup by the EXEC CONNECT startup parameter. This parameter is invalid when used in the rules language.

The NEWDDNAME parameter can be used to change the destination log name. When consolidating log messages, this allows the DEFCONN commands to be placed in all DIF started tasks—even the master DIF. The master DIF would then be the only DIF that has the new DDname specified.

Default: None

Format: Any valid DDname.

SYSLOG(PRIORITY(num))

Function: The SYSLOGD option is used in conjunction with the TCPIP parameter and CONVERT option to define an interface to a syslog daemon. For more information, examine “Writing Messages and Records to a Syslog Daemon” in the product documentation.

The PRIORITY value (num) is a combination of Facility and Severity codes calculated into a numeric value.

Default: None

Format: Any numeric value between 0 and 191.

TCPIP(ipaddr port_num options)

Function: The first positional parameter on the TCPIP keyword can be used to define the destination ipaddr or DNS name of a computer running a TCP/IP service. The second positional parameter defines the port number the service is listening on.

Additional subparameters can also be specified:

• CRLF - If the CRLF parameter is specified, the TCP/IP interface will append the carriage-return line-feed characters at the end of each record sent to the server.
• RESPONSE(ddname) - When using the TCP protocol, servers have a conversation during data transmission. If the RESPONSE(ddname) parameter has been specified, the responses from the server are written to the ddname. If the RESPONSE parameter has not been coded, all server responses are discarded.
• TCP - The TCP protocol is the default internet protocol used by the DIF TCP/IP interface. Normally, this parameter is not required.
• UDP - UDP is one of the basic internet protocols. UDP does not guarantee reliability or ordering in the way that TCP does. Datagrams may arrive out of order, appear duplicated, or go missing without notice. Avoiding the overhead of checking whether every packet actually arrived makes UDP faster and more efficient for applications that do not need guaranteed delivery. Time-sensitive applications often use UDP because dropped packets are preferable to delayed packets.

Default: None

Format: Any valid IP address (n.n.n.n format), or valid DNS name, followed by a port number and the remaining options.

options

Function: The options parameter on the DEFCONN statement determines whether the message is copied or forwarded, converted to ASCII, and/or propagates the message delivery header.

By default, the messages are routed only to the message queue/stream name, and not written to the log data sets. If LOG is specified, the log record will be routed to the message queue or logger stream, and the DD statement in the DIF started task will also receive a copy of the message.

If the message is being sent to a workstation, you can specify CONVERT or ASCII to translate the message to ASCII before placing the message on the queue.

By default, messages placed in a message queue or logger stream are prefixed with a destination header. When a DIF started task reads the message queue or stream, it then strips the header when writing to the log data set. If NOPROPAGATE is specified, the header is not prefixed to the message.

Default: None

Format: CONVERT/ASCII, LOG and/or NOPROPAGATE

The DIF website interface

The DIF started task can be configured to activate an HTTP server. Users can access the web interface with a browser to issue DIF commands. The interface can also be used by a Microsoft Excel spreadsheet, SAP Crystal Reports, or the open-source BIRT report application to obtain real-time records from Monitor in an XML format. Note: The command requests made to the web service require a valid TSO userid/password. Most programs will prompt for the userid/password if one is not given.

The DIF Webserver Interface is activated by specifying a second port number on the DIF SERVER TCPIP parameter. This port is used by DIF to listen for HTTP requests. DIF would not normally be set up to use the default HTTP port 80, but instead use an installation defined port. In the following example, the DIF Webserver Interface has been configured for port 12.

Note: This statement is typically located in DTS.R71.PARMLIB(DIFINIT):

INITOPT SERVER(TCPIP(TCPIP 10 12))

After a DIF restart, test the webserver interface using a browser to issue a DIF STATUS command. For example, the following request was made to a development system at 192.168.0.226 using port 12. The browser will prompt for a userid and password. Provide a TSO userid and password with the authority to issue the DIF STATUS command.

For more information about using the web service interface, please obtain the white paper on the DIF Webserver Interface from the Precisely website, or contact Customer support.

Useful tools and accessories

Useful Tools and Accessories (UTA) is a repository for FREE tools and utilities that are provided to our users. When you start the DIF started task, UTA is automatically started. To utilize the tools, UTA must be started. There are no rules and it can be stopped and started independently, just like the rest of the product suite.

UTA is available as an option on the ISPF Primary Options menu:

The available tools are then displayed: