Editing MQ Message Data with File-AID/MVS (MQ)

Review and edit MQ message data (data tagged <CONTENT> in the script) with:

• ISPF Edit or View
• File-AID/MVS version 08.00, providing you are licensed

Invoke File-AID/MVS from an ISPF Edit or View session to review and edit MQ message data in a formatted context. For example, if the message data contains a numeric string that represents a customer ID and account number, identifying the account number portion of the string may be difficult in ISPF Edit and therefore editing, more error prone. Use the MAPD command to invoke File-AID/MVS Edit and apply a record layout that presents the information with labels you define, such as Customer ID and Account Number. Edit information as necessary and exit File-AID/MVS to carry changes over to the ISPF session. End the session to apply changes to the script/detail data set. This process is referred to as mapping message data into application data structures.

If MQ message data is stored in the script, map one message at a time. If it is stored in a separate data set, map individual messages or all messages in the data set at once. Refer to Define Detail Data Storage and Output Requirements.

Assign a PF key to MAPD

Simplify editing individual messages by assigning a PF key to execute the MAPD command. Access the ISPF Keylist Utility by typing KEYS on the Command line of an ISPF Edit or View session. In the definition area next to the desired key, enter an exclamation point (!) followed by MAPD (!MAPD). Refer to the ISPF Keylist Utility Help to learn more about key mapping.

Map an individual message

Make sure the Maintain PDS Statistics option in File-AID/MVS is set to ADD before you begin mapping. Refer to your File-AID/MVS manual or your system programmer for help.

To map individual messages:

1. Open the script or detail data set in ISPF Edit or View.

   Warning

   Important

   ISPF View prompts for confirmation prior to writing changes back to the script or detail data file.

2. Use standard ISPF commands to locate the message to map.

   Warning

   Important

   To view only the message data in a script file, type X ALL on the Command line and press Enter; then type F <CONTENT> ALL and press Enter.

3. If you have not assigned a PF key for the MAPD command, place the cursor on the Command line and enter an exclamation point (!) following by MAPD.

   Warning

   Important

   The command prefix (!) is required only for the first mapping in the session. It is an ISPF standard for invoking a macro. Also, the command prefix may be different depending on the code page your terminal used. In the United States, the exclamation point is typically the correct character. See the note in the Assign a PF Key to MAPD discussion for more information.

4. Position the cursor anywhere right of the line command area on the record you wish to map and press the assigned PF key. If you did not assign a PF key, be sure MAPD is on the Command line and the cursor is correctly positioned, then press Enter.

5. MAPD invokes File-AID/MVS. Refer to the File-AID/MVS documentation for help with the screens it presents. With File-AID/MVS, you can apply a record layout, generate XML from mapped data, XREF information, and filter information to see only the activity needed to review or to edit.

   Warning

   Important

   MAPD creates a temporary data set, with a 4-node naming convention (USERID.MAPDTEMP.DATE.TIME), to pass mapped messages to File-AID/MVS. File-AID/MVS writes changes to the temporary data set. When you leave File-AID/MVS, it passes your changes back to ISPF and deletes the temporary data set. Upon exiting ISPF, MAPD updates the script/detail data set.

   If for some reason, the File-AID/MVS session is lost during edit, delete the temporary data set manually.

   Additionally, you can use the temporary data set as input to an XML generation job. After you submit the job, exit the screen File-AID presents to ensure the temporary data set is available for use. Do not exit File-AID until the job is complete.

   Edit message content as necessary. Make sure Caps Lock is off when you enter File-AID/MVS. If you edit a line and Caps Lock is on, File-AID coverts the entire line to uppercase. Press Cancel to cancel your work and return to ISPF or End to exit File-AID/MVS and transfer any changes to ISPF.

6. To exit the ISPF session without saving changes, press Cancel. To save the work in:
   • An Edit session, press End.
   • A View session, use the Create or Replace commands. Then press End to terminate the session.

Map an entire data file

Make sure the Maintain PDS Statistics option in File-AID/MVS is set to ADD before you begin mapping. Refer to your File-AID/MVS manual or your system programmer for help.

To map an entire data file:

1. Open the detail data set in ISPF Edit or View.

   Warning

   Important

   ISPF View prompts for confirmation prior to writing changes back to the script or detail data file.

2. Place your cursor on the Command line and press the PF key assigned to the MAPD command. If you have not assigned a PF Key, place your cursor on the Command line and type an exclamation point (!) followed by MAPD, then press Enter.

   Warning

   Important

   The command prefix (!) is required only for the first mapping in the session. It is an ISPF standard for invoking a macro. Also, the command prefix may be different depending on the code page your terminal used. In the United States, the exclamation point is typically the correct character. See the note in the Assign a PF Key to MAPDdiscussion for more information.

3. MAPD invokes File-AID/MVS. Refer to the File-AID/MVS documentation for help with the screens it presents. With File-AID/MVS, you can apply a record layout, generate XML from mapped data, XREF information, and filter information to see only the activity needed to review or edit.

   Warning

   Important

   MAPD creates a temporary data set, with a 4-node naming convention (USERID.MAPDTEMP.DATE.TIME), to pass mapped messages to File-AID/MVS. File-AID/MVS writes changes to the temporary data set. When you leave File-AID/MVS, it passes your changes back to ISPF and deletes the temporary data set. Upon exiting ISPF, MAPD updates the script/detail data set.

   If for some reason, the File-AID/MVS session is lost during edit, delete the temporary data set manually.

   Additionally, you can use the temporary data set as input to an XML generation job. After you submit the job, exit the screen File-AID presents to ensure the temporary data set is available for use. Do not exit File-AID until the job is complete.

   Edit message content as necessary. Make sure Caps Lock is off when you enter File-AID/MVS. If you edit a line and Caps Lock is on, File-AID coverts the entire line to uppercase. Press Cancel to cancel your work and return to ISPF or End to exit File-AID/MVS and transfer any changes to ISPF.

   Error

   Warning

   Deleting and inserting messages may cause unsynchronized playback.

   The script contains a link to each message in the detail file that supports playing back the script. If the detail file contains fewer or more messages than the script calls, playback will become unsynchronized. When you exit File-AID/MVS, Performance Test for WebSphere MQ warns you if the message count has been altered.

   If you replace messages by deleting and inserting, be sure the replacement messages contain the same type of data as the original messages.

4. To exit the ISPF session without saving changes, press Cancel. To save your work in:
   • An Edit session, press End.
   • A View session, use the Create or Replace commands. Then press End to terminate the session.

Access MAPD help panels

Access MAPD help panels, by typing MAPD space HELP or MAPD space question mark (?) on the Command line in the ISPF Edit or View session and pressing Enter.

Troubleshoot message mapping

MAPD presents information, error, and warning messages in the ISPF session. Depending on your ISPF settings, message content either appears on the first line of the display or in a pop-up window. Most message are fairly intuitive. However, some may be more difficult to troubleshoot. This section explains each message and provides the appropriate action to take, if any.

Script dataset messages

'CURSOR NOT ON <CONTENT> - SEE USER’S GUIDE'

Explanation: The data set containing the message you are mapping is not a script data set.

User Response: Press Enter to clear the message and Cancel to exit the ISPF session. Locate the appropriate data set and try again.

'DATA CHANGES DETECTED - EXTRA RECORD(S) IGNORED'

Explanation: You added one or more records while editing in File-AID/MVS. MAPD sent a single message, so it expects to receive a single record.

System Action: MAPD ignores the additional records when transferring changes back to ISPF. However, ISPF will reflect changes, if any, made to the originally mapped message.

'INVALID CONTENT LENGTH - SEE USER'SGUIDE'

Explanation: While editing a script data set the message length attribute byte was modified.

System Action: MAPD will not transfer data to File-AID/MVS if the message length does not match the value of the length attribute byte.

User Response: Press Enter to clear the message. If editing was effected in the current ISPF session, press cancel to exit the session without saving changes and try again.

'SCRIPT & DETAIL MUST BE COMBINED - SEE USER’S GUIDE'

Explanation: You are attempting to map from a script data set that is stored separately from the detail data set (message data). It contains links to the message data and the first part of each message for identification purposes. Refer to Define Detail Data Storage and Output Requirements.

User Response: Press Cancel to exit the ISPF session. Locate the corresponding detail data set and map messages from there.

Detail dataset messages

'CURSOR NOT ON DETAIL RECORD' - SEE USER’S GUIDE

Explanation: You are either attempting to map from a data set that is not a detail data set or you inadvertently altered a detail data sequence number.

User Response: Press Enter to clear the message. Then make sure you are in a detail file.
If you are in a detail file and inadvertently alter a sequence number in the current ISPF session, cancel without saving your work and start over. If the sequence number was altered in another ISPF session and saved, then regenerate the script and detail.

'LINE(S) DELETED - DETAIL OUT OF SYNC'

Explanation: While editing a detail data set in File-AID/MVS, you deleted a record, which causes an unsynchronized playback.

User Response: Press Cancel to exit the ISPF session without saving changes to the detail data set.

'LINE(S) INSERTED - DETAIL OUT OF SYNC'

Explanation: While editing a detail data set in File-AID/MVS, you inserted a record, which causes an unsynchronized playback.

User Response: Press Cancel to exit the ISPF session without saving changes to the detail data set.

'MESSAGE DATA SPANS MULTIPLE LINES - SEE USER'S GUIDE '

Explanation: When the script was created, if the length of the MQ message data is longer than the detail data set’s logical record length (LRECL), the message spans more than one line. This message appears when you try to map an entire file containing messages that span more than one line.

User Response: Press Enter to clear the message. The cursor will position to the first offending message. Map messages individually or regenerate the script and detail with an LRECL equal to or greater than the maximum message length.

General information and error messages

'32K MAXIMUM LRECL EXCEEDED'

Explanation: You are attempting to map a file containing messages larger than 32KB. The maximum record length supported by MAPD is 32KB.

'COMMAND NOT FOUND'

Explanation: The ISPF Edit Macro invocation character is missing or incorrect. ISPF requires the invocation character for the first use of the macro in a given session.

User Response: Prefix the MAPD command with the appropriate macro invocation character. This is the character that maps to hexadecimal value X‘5A’. For devices using the EBCDIC Code Page 037, the prefix character is an exclamation point (!).

'DATA CHANGES DETECTED'

Explanation: This message informs you that data has been changed.

User Response: If you did not intend to change data, press Enter to clear the message and Cancel to exit the ISPF session without saving the changes.

'INVALID PARAMETER'

Explanation: On the Command line, MAPD is followed by text that is not recognized as a valid parameter.

User Response: Press Enter to clear the message. Remove characters following the MAPD command and press Enter to resume work. 

'NO CHANGES DETECTED'

Explanation: This message informs you that data has not been changed.

User Response: Press Enter to clear the message and return to ISPF.

'NO DATA RETURNED FROM FILE-AID'

Explanation: You deleted the message in File-AID/MVS. File-AID/MVS had no data to return.

System Action: No changes are made to the MQ message data.

User Response: Press Enter to clear the message and return to the ISPF session.