Browse a Script (MQ)

Browse scripted activity for tasks such as debugging an application, validating new functionality, and verifying database changes. Use a standard text browsing tool such as ISPF Browse to review the contents of a script.

This section defines all of the available Performance Test for WebSphere MQ script tags. Each definition includes a syntax diagram that shows all of the parameters of the given script tag. Some of the script tags contain groups of parameters, or fields, referred to as structure data types. As such, this section begins with an explanation of the structure data types. The script tag syntax diagrams show the associated data types. Cross-reference the syntax diagrams with the information discussed in Structure Data Type Fields.

Additionally, a few parameters are common to most of the script tags. To minimize repetition, they are defined before the script tags as well.

Structure data type fields

Structure data types are groups of parameters or fields that contain information relevant to a specific MQ object or function. For example, the MQ Get Message Options (MQGMO) structure data type includes a series of fields relevant to the MQGET performed by your application.

IBM has established default values for each of these fields. To minimize the length of the scripts, Performance Test for WebSphere MQ presents only the fields that deviate from the default values unless you select the Include default MQAPI Script Tag parameters option while creating scripts. This option is located on the WebSphere MQ Create Scripts - Create Options Screen (1 of 2).

Each of the structure data type fields requires a specific type of value, for example, some require character strings, while others require numeric values. Although this information is relevant to script editing, it is presented in this section for easy reference. Field value formats include:

• String of characters (already translated by WebSphere MQ)
• Keyword as defined by IBM
• Multiple keywords as defined by IBM
• Whole number
• Hexadecimal string.

If the value spans multiple lines, the REXX concatenation operator, ||, appears immediately before the comma on all lines except the last.

The following table shows all of the fields associated with each structure data type, along with the format of the field value. It also lists the Performance Test for WebSphere MQ script tags that present the given data type. Refer to the IBM WebSphere MQ documentation for field definitions.

Structure data type fields, field value formats, and associated script tags

Parameters common to most script tags

Most of the Performance Test for WebSphere MQ script tags include any or all of the following parameters:

Connection_ID=number

Relates scripted events to a connection to a queue manager. Each MQ_CONNECT tag must have a unique CONNECTION_ID. This number is roughly equivalent to the WebSphere MQ hConn (connection handle).

Object_ID=number

Relates scripted events to an open MQ queue. Each MQ_OPEN and MQ_PUT1 tag must have a unique Object_ID. The parameter is present on all script tags except MQ_CONNECT, MQ_DISCONNECT, MQ_COMMIT, and MQ_BACKOUT. This number is roughly equivalent to the WebSphere MQ hObj (object handle).

CompCode=number

The numeric completion code returned by Performance Test for WebSphere MQ.

Reason=number

The numeric reason code returned by Performance Test for WebSphere MQ.

event_seq_num

Performance Test for WebSphere MQ assigns a sequential value to the events in the script. This number appears outside of the closing script tag bracket ‘>’.

This value is not necessary to play back a script. It simply provides context for script editing.

<CONTENT> tag for inline data

CONTENT tags present the message data associated with the recorded MQPUT, MQPUT1, and MQGET calls. One or more CONTENT tags appears immediately after an MQ_PUT, MQ_PUT1, or MQ_GET tag. If the length of the application data is greater than the logical record length (LRECL) of the script data set, the detail data is presented on a series of consecutive CONTENT tags.

When detail data is merged into the script, known as inline data, the CONTENT tag has no attributes and is immediately followed, on the same line, by a 12-byte header and then the application's data bytes, known as detail data. In the following example, “....00000007” is the CONTENT tag header and the detail data begin immediately after “7”.

The 12-byte header describes the CONTENT tag:

• The first two bytes indicate the length of the data following the CONTENT tag. This value includes the 12-byte header and has a maximum value of X'7FF8' (32760).

  Important

  If you are editing the script, make sure this number accurately reflects the actual number of bytes in the data set record plus twelve for the header. If the data record is longer than this value, playback ignores the extra bytes. If the data record is shorter than this value, playback pads it with EBCDIC blanks (X'40').

• The third byte indicates the format of the CONTENT tag data. Its value is a combination of all applicable formats from the following list.

  • X'20' indicates an MQ script
  • X'08' indicates the beginning of the CONTENT chain
  • X'04' indicates the end of the CONTENT chain
  • X'02' indicates truncated data
  • X'01' indicates MQPUT data
  • X'00' indicates MQGET data.

  For example, if the MQGET is comprised of three <CONTENT> tags, this byte’s value on the:
  

  • First tag is X'28', which indicates that this is data from an MQ script, that it is MQGET data, and that it is the beginning of CONTENT chain.
  • Second tag is X'20', which indicates this data is from an MQ script and that it is MQGET data.
  • Third tag is X'24', which indicates that this is data from and MQ script, that it is MQGET data, and that it is the end of CONTENT chain.

  If the CONTENT tag follows an MQ_PUT tag, this byte’s values on each CONTENT tag is: X'29', X'21', and X'25' respectively.

• The fourth byte indicates the protocol of the given content data. In Performance Test for WebSphere MQ, the protocol value is always X'01'.

• The fifth through the twelfth bytes indicate the record number, beginning with 0000001 (X'F0F0F0F0F0F0F0F1'). This value increases by one for each subsequent CONTENT tag.

  Important

  If you use the <REPLACE> Tag to replace application data during playback, be mindful of this 12-byte header when calculating the offset.

  Header: L L F P N N N N N N N N
  Offset: 0 1 2 3 4 5 6 7 8 9 A B

  Avoid manually calculating the data-replacement offset value by using the offset determination macros that Performance Test for WebSphere MQ provides (see Offset and Length Determination Macros).

<CONTENT> tag for external data

Identifies the detail data records that are associated with the preceding MQ_PUT, MQ_PUT1, or MQ_GET tag. The CONTENT tag includes only the FROM and TO parameters when the detail data is stored in an external file.

FROM

A decimal number indicating the first label in the external file containing detail data for this data flow.

TO

A decimal number indicating the last label in the external file containing detail data for this data flow.

The value after the CONTENT tag is called sample data. It is the first few bytes detail data and is provided to support script browsing when the detail is stored separately. The sample bytes are translated from ASCII to EBCDIC if you requested that option at script creation time.

Whether the detail data is contained within the script or in an external file it is prefixed by a 12-byte header that describes the affiliated CONTENT tag. See the description of the 12-byte header discussed in <CONTENT> Tag for Inline Data.

<DETAIL> tag

Indicates the location of the detail data. Detail data are the bytes associated with the recorded MQ_PUT, MQ_PUT1, and MQ_GET calls. This tag appears after the VERSION tag at the beginning of the script.

COMBINED

Indicates that GET and PUT data is stored together in a single PDSE member, either within the script, or in an external file. If the detail data is contained in the script, the value of this parameter is an asterisk (*). If it is stored externally, the value is the DD name of the external file, along with the PDSE member name, which is supplied during script creation. If COMBINED is present, neither GET nor PUT appear on this tag and cannot be added.

GET

Identifies where client data is located. The value is the DD name provided during script creation.

PUT

Identifies where server data is located. The value is the DD name provided during script creation.

<MQ_BACKOUT...> tag

Causes the queue manger to back out all of the MQ_GETs and MQ_PUTs that have occurred since the last ‘syncpoint’.

For CONNECTION_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

For more information about the MQBACK call and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_CLOSE...> tag

Relinquishes access to an object.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

MQCO

MQ close options. The value of this parameter corresponds to the Options parameter on the recorded MQCLOSE call. Valid values are NONE, DELETE, or DELETE_PURGE.

For more information about this tag and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_COMMIT...> tag

Tells the queue manager that the application has reached a syncpoint, and to make permanent all of the MQ_GETs and MQ_PUTs that occurred since the last syncpoint.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags. For more information about the MQCMIT call and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_CONNECT...> tag

Shows the start of an MQ connection. At playback time, the MQ_CONNECT tag starts an MQ connection between Performance Test for WebSphere MQ and a partner application.

For CONNECTION_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

QMGR_NAME

Name of the queue manager responsible for the given connection.

SYSTEM_NAME

Name of the system on which the connection occurred.

JOBNAME

Name of the job that initiated the connection.

STIME

The ‘start time’ (date and time) of the connection.

TRANSLATEA2E

Indicates that the detail data associated with the given connection was translated from ASCII to EBCDIC during script creation. This parameter appears only if the translation option was selected.

<MQ_DISCONNECT...> tag

Breaks the connection between the queue manager and the application.

For CONNECTION_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

<MQ_GET...> tag

Retrieves a message from an open local queue. This tag must follow and MQ_OPEN tag with the same OBJECT_ID.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

CRNTLEN

The length of the actual content. If you specified a truncation value on the WebSphere MQ Create Scripts - Input screen (WebSphere MQ Create Scripts - Input Screen), this value may be smaller than the TRUELEN value.

TRUELEN

The original length of the message retrieved from the queue. Corresponds to the BufferLength value on the MQGET call.

MQGMO Options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags.

MQMD Options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags.

<MQ_INQUIRE...> tag

Returns information about the attributes of an object.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

SELECTORS

Multi-keyword constants corresponding to the array of selectors.

SELECTORCOUNT

Number of attributes requested.

CHARATTRS

The buffer in which character attributes are returned.

CHARATTRLENGTH

The length (in bytes) of the CharAttrs parameter.

INTATTRS

An array of IntAttrCount integer attribute values.

INTATTRCOUNT

The number of elements in the IntAttrs array.

For more information about the MQINQ call and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_OPEN...> tag

Establishes access to an object (queue). MQ_OPEN names the queue, namelist, process definition, or queue manager, to be opened.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

MQOD

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a list of object descriptor fields.

MQOO

MQ open options. The value of this parameter corresponds to the Options parameter on the MQOPEN call. For valid values, refer to IBM’s WebSphere MQ Application Programming Reference.

If the repository does not contain an MQOPEN event and Script Create cannot find queue name information, it generates an ObjectName_In and an ObjectName_Out field containing a question mark ‘?’. Manually replace the question mark with the appropriate object name to prevent the following playback error:

<MQ_PUT...> tag

Puts a message on an open queue or distribution list.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

CRNTLEN

The length of the actual message content. If you specified a truncation value on the WebSphere MQ Create Scripts - Input screen (WebSphere MQ Create Scripts - Input Screen), this value may be smaller than the TRUELEN value.

TRUELEN

The original length of the message as PUT to the queue. Corresponds to the BufferLength value on the MQPUT call.

MQMD options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a complete list of message descriptor fields.

MQPMO options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a complete list of MQPUT message options.

For more information about the MQPUT call and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_PUT1...> Tag

Puts a single message on a queue, whether the queue is open or not.

For CONNECTION_ID, OBJECT_ID, COMPCODE, REASON, and event_seq_num definitions, see Parameters Common to Most Script Tags.

CRNTLEN

The length of the actual message content. If you specified a truncation value on the WebSphere MQ Create Scripts - Input screen (WebSphere MQ Create Scripts - Input Screen), this value may be smaller than the TRUELEN value.

TRUELEN

The original length of the message as put to the queue. Corresponds to the BufferLength value on the MQPUT1 call.

MQMD options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a complete list of message descriptor fields.

MQOD options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a complete list of MQPUT1 message options.

MQPMO options

See Structure Data Types Fields, Field Value Formats, and Associated Script Tags for a complete list of MQPUT1 message options.

For more information about MQPUT1 calls and their parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<MQ_SET...> tag

Changes the attributes of an object represented by a handle.

SELECTORS

Multi-keyword constants corresponding to the array of selectors.

SELECTORCOUNT

Number of attributes requested.

CHARATTRS

The buffer in which character attributes are returned.

CHARATTRLENGTH

The length (in bytes) of the CharAttrs parameter.

INTATTRS

An array of IntAttrCount integer attribute values.

INTATTRCOUNT

The number of elements in the IntAttrs array.

For more information about the MQSET call and its parameters, refer to IBM’s WebSphere MQ Application Programming Reference.

<TIME> tag

Indicates the date and time of the event that follows the TIME tag. Depending on the parameters specified on the playback statements, this tag can be used to control playback timing.

The TIME value is relative to the system on which the scripts were created. It is not GMT. The content of this tag is a time stamp with the format: YYYY/MM/DD_HH:MM:SS.XXXXXX. For example:

<VERSION> tag

Identifies the version of the Performance Test for WebSphere MQ script creation program that created the script.

The VERSION tag appears only once in a script. The value after the VERSION tag is in the form VV.RR.MM, for version, release, and modification level, respectively. For example: