Utilities for accessing the MQSeries or JMS exchange zones

A number of utilities are provided with the package to help you to fine-tune a session.

The table below shows what these utilities allow you to do:

Action UNIX/Windows Command MVS Command

Empty (or purge) queues

Rdjcleanmqs/rdjcleanjm

RDJCLNS

Generate a message to stop the session

Rdjstopmqs/ rdjcleanjms

RDJSTO

Transfer data from a file to a queue

Rdjputmqs/ rdjcleanjms]

RDJPUT

Transfer data from a queue to a file

Rdjgetmqs/ rdjcleanjms]

RDJGET

The installation procedure defines the default values of the parameter settings for each utility provided.

Note   You must adapt the parameters in these procedures to your environment.

Empty queues: rdjcleanmqs, rdjcleanjms

Purpose

To empty the queues, either on input or output.

These queues have the same names as the queues created when you installed the product.

Parameters

The following table shows the names of the queues created during the installation process. You can change the queue names, or add or delete names, to suit your implementation environment.

Data Contained in the Queue <br />(Keyword + Description)

UNIX/

Windows

Queue

Name

MVS Queue Name Queue Name

IEvent(Sender):
The Input-Event to be transformed

RDJ.IEVENT

RDJ.IEVENT

RDJ.IEVENT

OSegt (0):
Generated Output-Events associated with Processing-Context-Out 0

RDJ.OSEGT.0

RDJ.OSEGT0

RDJ.OSEGT.0

OSegt (1):
Generated Output-Events associated with Processing-Context-Out 1

RDJ.OSEGT.1

RDJ.OSEGT1

RDJ.OSEGT.1

OSegt (2):
Generated Output-Events associated with Processing-Context-Out 2

RDJ.OSEGT.2

RDJ.OSEGT2

RDJ.OSEGT.2

OSegt (3):
Generated Output-Events associated with Processing-Context-Out 3

RDJ.OSEGT.3

RDJ.OSEGT3

RDJ.OSEGT.3

OSegt (4):
Generated Output-Events associated with Processing-Context-Out 4

RDJ.OSEGT.4

RDJ.OSEGT4

RDJ.OSEGT.4

OSegt (5):
Generated Output-Events associated with Processing-Context-Out 5

RDJ.OSEGT.5

RDJ.OSEGT5

RDJ.OSEGT.5

OSegt (6):
Generated Output-Events associated with Processing-Context-Out 6

RDJ.OSEGT.6

RDJ.OSEGT6

RDJ.OSEGT.6

OSegt (7):
Generated Output-Events associated with Processing-Context-Out 7

RDJ.OSEGT.7

RDJ.OSEGT7

RDJ.OSEGT.7

OSegt (8):
Generated Output-Events associated with Processing-Context-Out 8

RDJ.OSEGT.8

RDJ.OSEGT8

RDJ.OSEGT.8

OSegt (9):
Generated Output-Events associated with Processing-Context-Out 9

RDJ.OSEGT.9

RDJ.OSEGT9

RDJ.OSEGT.9

OSegt (A):
Generated Output-Events associated with Processing-Context-Out A

RDJ.OSEGT.A

RDJ.OSEGTA

RDJ.OSEGT.A

OSegt (B):
Generated Output-Events associated with Processing-Context-Out B

RDJ.OSEGT.B

RDJ.OSEGTB

RDJ.OSEGT.B

OSegt (C):
Generated Output-Events associated with Processing-Context-Out C

RDJ.OSEGT.C

RDJ.OSEGTC

RDJ.OSEGT.C

OSegt (D):
Generated Output-Events associated with Processing-Context-Out D

RDJ.OSEGT.D

RDJ.OSEGTD

RDJ.OSEGT.D

OSegt (E):
Generated Output-Events associated with Processing-Context-Out E

RDJ.OSEGT.E

RDJ.OSEGTE

RDJ.OSEGT.E

OSegt (F):
Generated Output-Events associated with Processing-Context-Out F

RDJ.OSEGT.F

RDJ.OSEGTF

RDJ.OSEGT.F

OSegt (G):
Generated Output-Events associated with Processing-Context-Out G

RDJ.OSEGT.G

RDJ.OSEGTG

RDJ.OSEGT.G

OSegt (H):
Generated Output-Events associated with Processing-Context-Out H

RDJ.OSEGT.H

RDJ.OSEGTH

RDJ.OSEGT.H

OSegt (I):
Generated Output-Events associated with Processing-Context-Out I

RDJ.OSEGT.I

RDJ.OSEGTI

RDJ.OSEGT.I

OSegt (J):
Generated Output-Events associated with Processing-Context-Out J

RDJ.OSEGT.J

RDJ.OSEGTJ

RDJ.OSEGT.J

OSegt (Default):
Generated Output-Events associated with a Processing-Context-Out for which there is no exchange zone

RDJ.OSEGT.DEFAULT

RDJ.OSEGTZ

RDJ.OSEGT.DEFAULT

IEvent_Redirected (I): Redirected Input-Events associated with Processing-Context-Out I

RDJ.IEVENT.REDIRECTED.I

RDJ.IEVRDI

RDJ.IEVENT.REDIRECTED.I

IEvent_Redirected (J): Redirected Input-Events associated with Processing-Context-Out J

RDJ.IEVENT.REDIRECTED.J

RDJ.IEVRDJ

RDJ.IEVENT.REDIRECTED.J

IEvent_Modified:
Input-Events modified by the session

RDJ.IEVENT.MODIFIED

RDJ.IEVMOD

RDJ.IEVENT.MODIFIED

IEvent_Anomaly:
Input-Event that causes a transformation anomaly

RDJ.IEVENT.ANOMALY

RDJ.IEVANO

RDJ.IEVENT.ANOMALY

IEvent_Rejected:
Input-Events rejected during transformation

RDJ.IEVENT.REJECTED

RDJ.IEVREJ

RDJ.IEVENT.REJECTED

Trace_IEvent:
Extracted Input-Event traces

RDJ.TRACE.AUDIT

RDJ.TRACES

RDJ.TRACE.AUDIT

Trace_OSegt:
Extracted Output-Event traces

RDJ.TRACE.AUDIT

RDJ.TRACES

RDJ.TRACE.AUDIT

Detail_Anomaly_Rejection_IEvent: Report on transformation anomaly details

RDJ.DETAIL.ANOMALY

RDJ.DETANO

RDJ.DETAIL.ANOMALY

Detail_Redirection_IEvent: Report on redirection details

RDJ.DETAIL.

REDIRECTION

RDJ.DETRED

RDJ.DETAIL.REDIRECTION

Detail_Transformation:  Report on transformation results details

RDJ.DETAIL.

TRANSFORMATION

RDJ.DETTRA

RDJ.DETAIL.
TRANSFORMATION

Counter_Transformation: Transformation counters report

RDJ.TRANSFORMATION.
COUNTER

RDJ.CNTTRA

RDJ.TRANSFORMATION.
COUNTER

MQS (FILE_GROUP_INCOMPLETE): Groups of Input-Events that were incomplete when read

RDJ.INCOMPLETED.GROUP

RDJ.GRPANO

RDJ.INCOMPLETED.GROUP

MQS (FILE_MSG_UNREADABLE): Unreadable or suspect messages

RDJ.UNREADABLE.

MESSAGE

RDJ.UNREAD

RDJ.UNREADABLE.MESSAGE

Syntax

The procedure calls program rdjcleanmqs,rdjcleanjms / RDJCLN, which has the following run-time syntax:

  • UNIX Syntax with MQseries:$EXE/rdjcleanmqs, Local_Manager Queue
  • UNIX Syntax with JMS:$EXE/rdjcleanjms Local_Manager Queue
  • MVS Syntax:
  • //RDJCLEAN EXEC PGM=RDJCLEAN,//PARM=' Local_Manager Queue '

You must supply the parameters in the order shown:

  • Local_Manager:Name of the local queue manager (MQSeries) or QCF (JMS)
  • Queue: Name of the queue to empty

If an anomaly occurs during execution, the system stores a message reporting the anomaly in $TMP/rdjcleanmqs.msg.

Stop the session: rdjstopmqs,rdjstopjms / RDJSTO

Purpose

This procedure stops an Rule Engine MQSeries or JMS session, if the stop mode is set to Immediate. It builds a stop message and writes it to the Input-Event queue that is to be processed by the session.

This message has the highest priority, consequently the system:

  • Processes it before any of the queued Input-Event messages
  • Stops the session as soon as it completes a work unit (that is, either a commit at the end of an Input-Event or commit or rollback at the end of a group of Input-Events)

When you start a session, the system automatically purges the Input-Event queue of any stop messages before it reads in the Input-Events.

Parameters

The Input-Event queue to be processed has the name that was used at installation time. RDJ.IEVENT.

You must modify the values in the procedure to fit your own implementation.

Syntax

The procedure calls program rdjstopmqs,rdjstopjms/RDJSTO, which has the following run-time syntax.

  • UNIX Syntax with MQSeries:
  • $EXE/rdjstopmqs Local_Manager Queue
  • UNIX Syntax with JMS:
  • $EXE/rdjstopjms Local_Manager Queue
  • MVS Syntax:
  • //RDJSTOP EXEC PGM=RDJSTOP,//PARM=' Local_Manager Queue '

You must supply the parameters in the order shown:

Order N° Parameter Use

1

Local_Manager

Name of the local queue manager

2

Queue

The name of the Input-Event queue that is to be processed
The stop message is stored in this queue

If an anomaly occurs during execution, the system stores a message reporting the anomaly in $TMP/rdjstopmqs.msg (for MQSeries) or $TMP/rdjstopjms.msg (for JMS).

Transferring data from a file to a queue: rdjputmqs,rdjputjms /RDJPUT

Purpose

This procedure takes data from a file and creates an Input-Event queue with it in the format expected by the package.

Parameters

The Input-Event queue to be processed has the name that was given at installation time. RDJ.IEVENT

The file of Input-Events has the name that was given at installation time: IEvent.seq (UNIX/Windows) or DD:IEVENT (MVS).

You must modify the values in the procedure to fit your own implementation.

Syntax

The procedure calls the program rdjputmqs,rdjputjms/RDJPUT, which has the following run-time syntax.

  • UNIX Syntax with MQseries: $EXE/rdjputmqs Local_Manager Queue File IEvent_Keys Group_Key Root_MsgId Message_Length Message_Format [Remote_Manager]
  • UNIX Syntax with JMS: $EXE/rdjputjms Local_Manager Queue File IEvent_Keys Group_Key Root_MsgId Message_Length Message_Format [Remote_Manager]
  • MVS Syntax: //RDJPUT  EXEC PGM=RDJPUTC,//PARM='Local_Manager Queue File IEvent_Keys Group_Key -//Root_MsgId Message_Length Message_Format [Remote_Manager]'

You must supply the parameters in the order shown below:

Order N° Parameter Use

1

Local_Manager

Name of the local queue manager

2

Queue

Name of the Processing-Context-Out queue

3

File

Name of the Input-Event file that is to be transferred

4

IEvent_Keys

The set of fields that identify an instance of an Input-Event

  • Each field is defined by its length and position in the file record. The sets of values (that is, a position and a length) are separated from each other by ampersands (&)
  • Each position value must be in the range 1 - 4000.
    Each length value must be in the range 1 - 256
  • A break in the sequence of the values of these fields marks the start of a new Input-Event in the file
  • To indicate a mono-segment Input-Event, set the parameter to MONO

5

Group_Key

Specifies the group key

  • If you activated the Group Management option, define in this parameter the position and length of the group code in the file records
  • This key indicates where the break between groups in the file is to be found
  • The system uses the value of this field to build the CorrelId in the messages sent. The maximum length is 24 characters
  • If you did not activate the Group Management option, set this field to N. In this case, the CorrelId is not set.

6

Root_MsgId

The root of the MsgId. Maximum 5 characters
The MsgId of the message is built by concatenating this root with the date and time at which the message is sent
(Example: SESSN19971201175608)

7

Message_Length

The maximum length (in KB) of the messages to be sent
Must be in the range 1 - 4096KB

8

Message_Format

The format of the message. Values can be STRING or NONE

9

Remote_Manager

The name of the remote manager if the Processing-Context-Out queue is remote.
This is an optional parameter

If an anomaly occurs during execution, the system stores a message reporting the anomaly in $TMP/rdjputmqs.msg (for MQSeries) or $TMP/rdjputjms.msg (for JMS).

Examples:

  • In UNIX with MQSeries: $EXE/rdjputmqs  HPX4  RDJ.IEVENT  IEvent.seq  "1,6&12,7"  "25,20"  VAC01  16  string
  • In UNIX with JMS: $EXE/rdjputjms HPX4 RDJ.IEVENT IEvent.seq "1,6&12,7" "25,20" VAC01 16 string
  • In MVS: //RDJPUT  EXEC PGM=RDJPUTC,//  PARM='MQME RDJ.IEVENT DD:IEVENT "1,6&12,7" "25,20" VAC01 16 STRING '//*//CRE     DD DSN=&ENVRDJ.CRE,DISP=SHR//SYSOUT  DD SYSOUT=*//SYSPRINT DD SYSOUT=*
Note   You must sort the Input-Event file (using the keys that define an Input-Event and an Input-Event group). You must perform the sort externally, before you start the procedure.

The system uses a single unit of work is used for processing the file.

For a big file, you may reach the limit for the number of messages in a unit of work. In this case the unit of work is backed out and canceled.
There are two ways to avoid this. Either:

  • Increase the value of Message_Length so as to decrease the number of messages
  • Chop the file into several smaller files

The system generates a return code when it completes the execution. You can test the return code via JCL or a shell program. The return code reports the level of the most serious error found during execution.

The table below shows the possible values, which are the identical for all systems:

Type of Error Encountered Associated Return Code

No transformation errors

0 (zero)

File empty or MQSeries warning or JMS warning

4

System error

16

If the return code is anything other than 0, the systems sends a message to the standard output on UNIX or to SYSPRINT on MVS.

Transferring data from a queue to a File: rdjgetmqs,rdjgetjms/RDJGET

Purpose

To create files from data held in a queue. Each file contains a transformation product in the defined format.

Parameters

Mode_Open_File

The Mode_Open_File parameter specifies the mode in which data is to be written to the procedure output file:

  • C = Create mode
  • A = Append mode 

The queues names were created during the installation process. The resulting files are created in the results directory.

The table below shows the names of the queues and the files the system creates. You can change these file names in the procedure, or add or delete names, to suit your implementation environment.

Data Contained in the Queue
(Keyword + Description)
UNIX /Windows Queue Name MVS
Queue Name
UNIX/Windows
Data File Created/ Context File

OSegt (0):
Generated Output-Events associated with output 0

RDJ.OSEGT.0

RDJ.OSEGT0

OSegt0.seq

OSegt0.ctx

OSegt (1):
Generated Output-Events associated with output 1

RDJ.OSEGT.1

RDJ.OSEGT1

OSegt1.seq

Osegt1.ctx

OSegt (2):
Generated Output-Events associated with output 2

RDJ.OSEGT.2

RDJ.OSEGT2

Osegt2.seq

Osegt2.ctx

OSegt (3):
Generated Output-Events associated with output 3

RDJ.OSEGT.3

RDJ.OSEGT3

Osegt3.seq

Osegt3.ctx

OSegt (4):
Generated Output-Events associated with output 4

RDJ.OSEGT.4

RDJ.OSEGT4

Osegt4.seq

Osegt4.ctx

OSegt (5):
Generated Output-Events associated with output 5

RDJ.OSEGT.5

RDJ.OSEGT5

Osegt5.seq

Osegt5.ctx

OSegt (6):
Generated Output-Events associated with output 6

RDJ.OSEGT.6

RDJ.OSEGT6

Osegt6.seq

Osegt6.ctx

OSegt (7):
Generated Output-Events associated with output 7

RDJ.OSEGT.7

RDJ.OSEGT7

Osegt7.seq

Osegt7.ctx

OSegt (8):
Generated Output-Events associated with output 8

RDJ.OSEGT.8

RDJ.OSEGT8

Osegt8.seq

Osegt8.ctx

OSegt (9):
Generated Output-Events associated with output 9

RDJ.OSEGT.9

RDJ.OSEGT9

Osegt9.seq

Osegt9.ctx

OSegt (A):
Generated Output-Events associated with output A

RDJ.OSEGT.A

RDJ.OSEGTA

OsegtA.seq

OsegtA.ctx

Osegt (B):
Generated Output-Events associated with output B

RDJ.OSEGT.B

RDJ.OSEGTB

OsegtB.seq

OsegtB.ctx

OSegt (C):
Generated Output-Events associated with output C

RDJ.OSEGT.C

RDJ.OSEGTC

OsegtC.seq

OsegtC.ctx

OSegt (D):
Generated Output-Events associated with output D

RDJ.OSEGT.D

RDJ.OSEGTD

OsegtD.seq

OsegtD.ctx

OSegt (E):
Generated Output-Events associated with output E

RDJ.OSEGT.E

RDJ.OSEGTE

OsegtE.seq

OsegtE.ctx

Osegt (F):
Generated Output-Events associated with output F.

RDJ.OSEGT.F

RDJ.OSEGTF

OsegtF.seq

OsegtF.ctx

OSegt (G):
Generated Output-Events associated with output G.

RDJ.OSEGT.G

RDJ.OSEGTG

OsegtG.seq

OsegtG.ctx

OSegt (H):
Generated Output-Events associated with output H.

RDJ.OSEGT.H

RDJ.OSEGTH

OsegtH.seq

OsegtH.ctx

OSegt (I):
Generated Output-Events associated with output I.

RDJ.OSEGT.I

RDJ.OSEGTI

OsegtI.seq

OsegtI.ctx

OSegt (J):
Generated Output-Events associated with output J.

RDJ.OSEGT.J

RDJ.OSEGTJ

OsegtJ.seq

OsegtJ.ctx

OSegt (Default):
Generated Output-Events associated with an output for which there is no exchange zone.

RDJ.OSEGT.DEFAULT

RDJ.OSEGTZ

Osegtdef.seq

OSegtdef.ctx

IEvent_Modified:
Input-Events modified by the session.

RDJ.IEVENT.MODIFIED

RDJ.IEVMOD

ap.Modified_IEvent

modifIE.ctx

IEvent_Anomaly:
Input-Event that causes a transformation anomaly.

RDJ.IEVENT.ANOMALY

RDJ.IEVANO

ap.Anomaly_IEvent

AnoIE.ctx

IEvent_Rejected:
Input-Events rejected during transformation.

RDJ.IEVENT.REJECTED

RDJ.IEVREJ

ap.Rejected_IEvent

RejectIE.ctx

Trace_IEvent:
Extracted Input-Event traces.

RDJ.TRACE.AUDIT

RDJ.TRACES

ap.Trace

trace.ctx

Trace_OSegt:
Extracted Output-Event traces.

RDJ.TRACE.AUDIT

RDJ.TRACES

ap.Trace

trace.ctx

IEvent_Redirected (I): Redirected Input-Events associated with output I.

RDJ.IEVENT.REDIRECTED.I

RDJ.IEVRDI

RedirIEI.seq

RedirIEI.ctx

IEvent_Redirected (J): Redirected Input-Events associated with output J.

RDJ.IEVENT.REDIRECTED.J

RDJ.IEVRDJ

RedirIEJ.seq

RedirIEJ.ctx

Detail_Anomaly_Rejection_
IEvent: Report on details of transformation anomalies.

RDJ.DETAIL.ANOMALY

RDJ.DETANO

ap.Detail_Anomaly_Reject_IEvent

detano.ctx

Detail_Redirection_IEvent: Report on details of redirections.

RDJ.DETAIL.REDIRECTION

RDJ.DETRED

ap.Detail_Redirected_IEvent

DetRedir.ctx

Detail_Transformation:  Report on details of results of transformation.

RDJ.DETAIL.TRANSFORMATION

RDJ.DETTRA

ap.Detail_Transformation

DetTrans.ctx

Counter_Transformation: Report on transformation counters.

RDJ.TRANSFORMATION.
COUNTER

RDJ.CNTTRA

ap.Transformation_Counter

Counttra.ctx

MQS (FILE_GROUP_INCOMPLETE) Groups of Input-Events that were incomplete when read.

RDJ.INCOMPLETED.GROUP

RDJ.GRPANO

IncompletedGroup

IncompletedGroup.ctx

Account_Log

RDJ.LOG.ACCOUNT

RDJ.LOGACC

Ap.LogAccount

LogAccount.ctx

The SIC validation procedure uses the files of the Context message for Windows and UNIX platforms only.

Syntax

The procedure calls program rdjgetmqs,rdjgetjms / RDJGET, which has the following run-time syntax:

  • UNIX Syntax with MQSeries: $EXE/rdjgetmqs Local_Manager Queue Conversion Mode_Open_File Product_File [Message_Context_File]
  • UNIX Syntax with JMS: $EXE/rdjgetjms Local_Manager Queue Conversion Mode_Open_File Product_File [Message_Context_File]
  • MVS Syntax: //RDJCLEAN EXEC PGM=RDJGETC,//        PARM=' Local_Manager Queue Conversion Mode_Open_File -//        Product_File [Message_Context_File]'

You must supply the parameters in the order shown below:

Order N° Parameter Use

1

Local_Manager

Name of the local queue manager

2

Queue

Name of the queue to be transferred

3

Conversion

Request for automatic conversion of the messages

  • C: The data in the messages is converted
  • N:The data in the messages is transferred
    without conversion

4

Mode_Open_File

The mode in which the output (results) file is to be opened

  • C:The file is opened in Create mode
  • A: The file is opened in Append mode

5

Product_File

Name of the results file (For example, Output-Events, Redirected Input-Events, Print data)

6

Message_Context_File

(optional parameter)Name of the file containing information about the context and technical header of each message
(For example, CorrelId, MsgId, Product number)

If an anomaly occurs during execution, the system stores a message reporting the anomaly in $TMP/rdjgetmqs.msg (for MQSeries) or $TMP/rdjgetjms.msg(for JMS).

Examples

  • Under UNIX with MQSeries: $EXE/rdjgetmqs  HPX4  RDJ.ME.1  C  A  OSegt1.prod  OSegt1.ctx
  • Under UNIX with JMS: $EXE/rdjgetjms HPX4 RDJ.ME.1 C A OSegt1.prod OSegt1.ctx
  • Under MVS: //RDJGET1 EXEC PGM=RDJGETC,//  PARM='MQME  RDJ.ME.1  N  C  DD:OSEGT1PROD'//*//OSEGT1PROD DD DSN=&ENVRDJ.OSEGT1.PROD,DISP=(NEW,CATLG),//         SPACE=(CYL,(2,3),RLSE),//         UNIT=SYSDA, VOL=SER=8SOP04,//         DCB=(RECFM=VB,LRECL=4004)//SYSOUT  DD SYSOUT=*//SYSPRINT DD SYSOUT=*
Note   A return code is generated on completion of execution. You can test it using JCL or a shell program. The return code reports the level of the most serious error found during execution.
The table below shows the possible values, which are the identical for all systems:
Type of Error Encountered Associated Return Code

No transformation errors

0 (zero)

File empty or MQSeries warning or JMS warning

4

System error

16

If the return code is anything other than 0, a message is sent to the standard output in UNIX or to SYSPRINT under MVS.

Related Links