The DEFCONN statement defines a connection between the ddname used by other statements in the rules language and a:
- MQSeries message queue
- the system logger
- syslog daemon
- direct writes to an HFS file
The DEFCONN statements are typically executed via the EXEC CONNECT parameter to forward records to a message queue or log stream. For more information, examine “EXEC” in the Product Installation Guide.
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 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 records to the requested destination.
However, if DEFCONN rule statements are specified in the product rules and not executed as commands by EXEC CONNECT, the records bypass the cross memory move to DIF and get moved directly to an MQSeries message queue or HFS file. For MQSeries connections, this method of adding records to the queue is not recommended since the rules have to Open/Write/Close a queue for each record.. Note: The DIF interface to the syslog daemon cannot use direct writes to the syslog server, but must use the DIF log buffer to schedule writes.
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. The facility can also be used to move information 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.
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.
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. 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).
SYSLOG DAEMON - DIF has an interface to syslog servers using the BSD syslog daemon protocol. The syslog protocol was originally developed on the University of California Berkeley Software Distribution (BSD) TCP/IP system implementations. Over time, the syslog protocol has been ported to many other operating systems as well as being embedded into many network devices. Syslog servers are now the event log collectors used for many hardware and software products. For more information, examine WritingMessages and Records to a Syslog Daemon.
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.
TCP/IP - 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” on page 6-15 in the Product Installation Guide.
Note: DEFCONN has an alias of DEFAPPC for compatibility with previous releases.
DEFCONN ddname
FILTERRULE ( rulename ) HFS( hfspath/filename ) LOGGER( streamname )
MQSERIES( qname MQMNGR( mngrname ) ) NEWDDNAME( ddname )
SYSLOGD( PRIORITY( num )
TCPIP( ipaddr )
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 are 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 DEFCONN MQSERIES parameter.
Default: None
Format: Any valid DDname.
FILTERRULE ( rulename )
Function: This is an optional parameter. The FILTERRULE keyword can
be used to determine whether the current statement is honored by the rule processor. If the rule member requested by FILTERRULE sets the symbolic field RULE_SKIP = YES, then the current rule statement will be skipped. For more information, examine “FilterRules for Rule Statements” on page
Default: None
Format: Specify the name of a rule member found in the SCC rule library:
DTS.R71.RULELIB.
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 Addres 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”on page 4-9.
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 qnames required
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. Note: This parameter also allows a single DIF to be used for testing log record consolidation.
Default: None
Format: Any valid DDname.
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 aSyslog Daemon” on page 4-14.
The PRIORITY value (num) is a combination of Facility and Severity codes calculated into numeric value. For more information about syslog servers and the priory value, use the following link and read section "4.1.1 PRI Part":
http://community.roxen.com/developers/idocs/rfc/ rfc3164.html
Default: None
Format: Any numeric value between 0 and 191.
TCPIP( ipaddr port_num )
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 BSD syslog daemon. The second positional parameter defines the port number.
The SYSLOGD parameter and CONVERT option should be specified along with this parameter. For more information, examine “WritingMessages and Records to a Syslog Daemon” on page 4-14.
Default: None
Format: Any valid IP address (n.n.n.n format), or valid DNS name,
followed by a port number.
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 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 work station, you can specify CON-VERT 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.
NOPROPAGATE would normally be specified for messages placed on MQSeries message queues that are being read by an application other than DIF. If you wish to propagate the destination header to installation developed applications, contact customer support and request a copy of the SRH macro for the header layout.
Default: None
Format: CONVERT, LOG and/or NOPROPAGATE