Space banner This space provides the same content as before, but the organization of the home page has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Global Recording Request Parameters—WebSphere MQ

Global Recording request parameters are defined in XML. Start with one of the following:

Store the parameters in a sequential dataset or a PDS member in your personal library or write them directly in the JCL. Use a standard file editing tool such as ISPF Edit to write or modify the parameters.

Important

XML tags are case-sensitive. Make sure the ISPF Caps function is set to off when editing the parameters. Type CAPS OFF on the Command line and press Enter.

To work with a parameters file on the PC:

  • Use the IBM utility IEBGENER to copy the dataset into an HFS file.
  • FTP the file to the PC. To avoid EBCDIC to ASCII translation issues, transfer the file as 'text'.

Use an XML editor, such as Notepad, to edit the tags. Pay attention to syntax interpretation. The Global Recording batch interface cannot recognize tags that have been reformatted based on the viewer’s interpretation. For example, some editors format tags that have no values as follows <tag/>. Encase blank values in single quotes to avoid this particular interpretation issue. All tags must conform to the syntax rules described in Global Recording Request Parameter Syntax.

To avoid record truncation when transferring the parameters back to the mainframe, copy them into a fixed block dataset with a logical record length that supports the longest record.

This topic provides an illustration of sample DCIADAMQ (see the following figure) and defines all of the available MQ Global Recording request parameters. Parameter hierarchy is shown and defined within the parameter definitions.

SQQFSAMP Member DCIADAMQ

********************************* Top of Data **********************************
<MQS>
 <Request_ID>             C'MQSA-1'
 </Request_ID>


 <Archive_ID>             'ARCH-M1'
 </Archive_ID>


 <Archive_Desc>   'MQS Archive Request 1 via DCI'
 </Archive_Desc>


 <Capture_File>
  <Dataset>               'COMPWARE.ARCHIVE.MQS.#*'
  </Dataset>
  <First_Number>          '1'
  </First_Number>
  <Last_Number>           '9999999'
  </Last_Number>
  <!-- Valid 'Initial_Disposition' values are APPEND or OVERWRITE -->
  <Initial_Disposition>   'APPEND'
  </Initial_Disposition>
 </Capture_File>


 <Data_To_Keep>
  <Data_From_GETS>        'ALL'
  </Data_From_GETS>
  <Data_From_PUTS>        'ALL'
  </Data_From_PUTS>
 </Data_To_Keep>


 <MQS_Capture_Filters>
 
  <Filter Record="1">
   <!-- Valid 'Action' values are INCLUDE or EXCLUDE -->
   <Action>               'INCLUDE'
   </Action>
   <!-- Valid '_RO' values are EQ, NE, GT, LT, GE, or LE -->
   <Queue_Manager_RO>     'EQ'
   </Queue_Manager_RO>
   <Queue_Manager>        'DUMMY'
   </Queue_Manager>
   <Queue_Object_Name_RO> ''
   </Queue_Object_Name_RO>
   <Queue_Object_Name>    ''
   </Queue_Object_Name>
   <Jobname_RO>           ''
   </Jobname_RO>
   <Jobname>              ''
   </Jobname>
   <Comp_Code_RO>         ''
   </Comp_Code_RO>
   <Comp_Code>            ''
   </Comp_Code>
   <Reason_Code_RO>       ''
   </Reason_Code_RO>
   <Reason_Code>          ''
   </Reason_Code>
  </Filter>
 </MQS_Capture_Filters>
</MQS>

Protocol Parameter Tag

MQS

Identifies the type of Global Recording request to add. This is a parent tag to all other parameters described in this section. Begin and end the XML input stream with opening and closing MQS tags.

General Request Parameter Tags

Request ID

The ID of the Global Recording request. To assign a request ID, supply a six-byte hexadecimal or character value in single quotes. Place a format indicator in front of the value outside of the quotation marks. X indicates hexadecimal values and C indicates character values. For example:

  • <Request_ID> X'010203040506' </Request_ID>
  • <Request_ID> C'HSREQ1'</Request_ID>

The batch interface pads hexadecimal values that are less than six bytes with zeros and character values that are less than six bytes with spaces.

This tag is optional. If you do not supply a request ID, the system assigns one when the request is created.

Archive ID

The name of the Archive Request. This is the name by which the archive will be referred to in Session Monitor. You can specify up to eight characters for the archive name. The name can be alphanumeric but must start with a letter. This tag is required.

Archive Description

A description of the archive request. The description can be up to 53 bytes. This tag is optional.

Scheduled Capture Parameter Tags

Scheduled_Capture

Sets a start time and duration for the request. The request activates at the defined start time and date and remains active until the specified end time and date, unless the capture repository fills up.

Omit this entire block of tags if you want capture to begin immediately and remain active indefinitely.

The following parameters are Scheduled_Capture sub-parameters. Supply the applicable parameters between the opening and closing Scheduled_Capture tags.

Start_Date

The date the request is to be activated. Specify a two digit month, a two digit day, and a four digit year separated by forward slashes: 'MM/DD/YYYY'.

If you specify a start date with no time, the request activates at the beginning of the given day — that is, midnight (00:00:00).

Start_Time

The time the request is to be activated. Specify a two digit hour, a two digit minute, and a two digit second separated by colons: 'HH:MM:SS'.

If you specify a start time, a start date is required.

If you do not specify a start time or date, the request activates immediately.

End_Date

The month, day, and year to deactivate the request. Specify a two digit month, a two digit day, and a four digit year separated by forward slashes: 'MM/DD/YYYY'.

If you specify an end date with no time, the request deactivates at the end of the given day — that is, midnight (24:00:00).

End_Time

The time the request is to be deactivated. Specify a two digit hour, a two digit minute, and a two digit second separated by colons: 'HH:MM:SS'.

If you do not specify an end time or date, the request remains active until you STOP, FORCE or CANCEL it or until the repository is full.

If you specify an end time, an end date is required.

Capture File Parameter Tags

Capture_File

Defines the dataset to use for storing the captured data.

The following parameters are Capture_File sub-parameters. Supply the applicable parameters between the opening and closing Capture_File tags.

Dataset

For an archive request, the dataset must end with .#* preceded by a 35-character valid dataset name which will be the name of the registry dataset. There may be no wildcard characters in the registry dataset name portion of the value.

<registry-dataset>.#*

Important

Begin each segment of the dataset name with an alpha character (A-Z) or @#$, including segments with wildcard characters.

First_Number

This tag is required and must have a value of 1.

Last_Number

This tag is required and must have a value of 9999999.

Initial Disposition

Indicates whether to append or overwrite data contained in the specified dataset. Valid values are 'APPEND' or 'OVERWRITE'. This tag is unnecessary if the specified dataset does not exist. If the specified dataset does exist, and you do not provide an initial disposition value, Global Recording appends the new data to the existing data.

Important

The dataset is overwritten when Global Recording captures and processes activity that matches the request criteria. If no activity matches, the dataset is not overwritten.

Allocation

Allocation parameters for the capture file dataset. If you do not supply allocation parameters and the specified dataset does not exist, the batch interface allocates it with default values set by the installer. Generally, the default values are appropriate. However, you can override any or all of the default parameters by using the following Allocation sub-parameters.

Supply the applicable parameters between the opening and closing Allocation tags.

Management_Class

The management class to apply to the new dataset. Management classes are defined by the storage administrator at your site.

Storage_Class

The storage class to apply to the new dataset. Storage classes are defined by the storage administrator at your site.

Volume_Serial

The serial number of the volume on which the dataset is to be stored.

Device_Type

The type of device on which the dataset is to be stored. Can be a generic unit such as 'SYSDA'.

Data_Class

The data class to apply to the new dataset. Data classes are defined by the storage administrator at your site.

Space_Units

The type of units used to store the data. Valid values are: TRKS (Tracks), CYLS (Cylinders), BLKS (Blocks), BYTES, KB (kilobytes), or MB (megabytes). Space units combined with the primary and secondary quantities define the amount of space allocated for the dataset.

Primary_Quantity

The number of space units to allocate initially. Once Global Recording fills the primary quantity, it allocates the secondary quantity.

Secondary_Quantity

The number of space units to allocate after the primary quantity is full.

Block_Size

The maximum length, in bytes, of the blocks of data that the system reads in as it processes a dataset.

Recording Option Parameter Tags

Recording_Options

Defines recording request actions.

The following parameter is a Recording_Options sub-parameter. If you supply this tag, be sure to place it between the opening and closing Recording_Options tags.

Reuse_Capture_File

This tag is required and must have a value of NO.

Data To Keep Tags

Data_To_Keep

The following parameters are Data_to_Keep sub-parameters. Supply the applicable parameters between the opening and closing Data_to_Keep tags.

Data_From_GETS

This tag is not required, but must have a value of ALL, if specified.

Data_From_PUTS

This tag is not required, but must have a value of ALL, if specified.

MQS Capture Filter Tags

Filter Record="x"

Defines a filter for recording. Capture or ignore activity based on queue manager, queue/object name, jobname, completion code, or reason code.

Supply this tag with a filter number enclosed in double quotation marks. For example, <Filter Record="1">. To create multiple filters, copy this block of tags and increment the value of x for each filter.

The batch interface requires at least one filter, containing minimally the Queue_Manager sub-parameter. All other sub-parameters are optional. If you want to record all MQ activity on the system, create a filter and specify a wildcard on the Queue_Manager parameter. For example:

<Filter Record="1">
<Queue_Manager> ‘*’
</Queue_Manager>
</Filter>

Each sub-parameter, except Action, has a corresponding relational operator (RO) parameter. Use these parameters to indicate how events are evaluated for each filtering criterion. Valid values are:

  • 'EQ' for Equal to
  • 'NE' for Not Equal
  • 'LT' for Less Than
  • 'GT' for Greater Than
  • 'LE' for Less than or Equal to
  • 'GE' for Greater than or Equal to.

Specify the RO based on your MQ environment and your recording needs. For example, to capture all events handled by a specific queue manager, except the events from a specific queue, set the Queue_Manager_RO to EQ and the Queue_Object_name_RO to NE and supply the queue manager and queue names on the corresponding tags.

If you do not supply an RO value for a given parameter, Global Recording uses EQ.

The following parameters are Filter Record="x" sub-parameters. Nest the applicable sub-parameters between an opening <Filter Record="x"> tag and a closing </Filter> tag.

Action

The action that Global Recording is to take when an MQ event matches all of the filter’s criteria. Supply a value of 'INCLUDE' or 'EXCLUDE'.

Global Recording captures events that match all criteria on any of the “include” filters and none of the criteria on any of the “exclude” filters. If an event does not match any filter or if matches both an “include” and “exclude” filter, it is not captured.

It you omit the parameter, Global Recording assumes the filter is an “include” filter.

Queue_Manager_RO

The relational operator used to evaluate events based on the Queue_Manager value.

Queue_Manager

The name of the queue manager to capture or exclude from capture. This is a required parameter. Supply:

  • A specific queue manager.
  • A range of queue managers by supplying the beginning of the queue manager name followed by an asterisk (*).
  • All queue managers by supplying a single asterisk or omitting the tag altogether.

Queue_Object_Name_RO

The relational operator used to evaluate events based on the Queue_Object_name value.

Queue_Object_Name

The queue or object name to capture or exclude from capture. Specify:

  • A specific queue/object name.
  • A range of queues/objects by supplying the beginning of the queue/object name followed by an asterisk (*).
  • All queues/objects by supplying a single asterisk or omitting the tag altogether.

Jobname_RO

The relational operator used to evaluate events based on the Jobname value.

Jobname

The jobname to capture or exclude from capture. Specify:

  • A specific job name.
  • A range of job names by supplying the beginning of the job name followed by an asterisk (*).
  • All job names by supplying a single asterisk or omitting the tag altogether.

The jobname is defined by the application that creates the MQ message.

Comp_Code_RO

The relational operator used to evaluate events based on the Comp_Code value.

Comp_Code

The numeric completion code associated with the jobnames you need to capture or omit from capture. Valid values are 0 (successful completion), 1 (warning - partial completion), or 2 (call failed).

Reason_Code_RO

The relational operator used to evaluate events based on the Reason_Code value.

Reason_Code

The numeric reason code associated with the jobnames you need to capture or omit from capture. Numeric reason code 0 = no reason code. Other reason codes can be from 2001 to 2360 and are listed in IBM’s WebSphere MQ Application Programming Reference Guide.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*