The MessageQ Script Facility provides a powerful tool for application developers to use in simulating message exchange between programs. Instead of writing a test program, you create a script file containing instructions for capturing messages sent or received by an application, replaying captured messages, or simulating messages sent from an application that is still under development.
Application developers can use the Script Facility to:
Instructions are entered to the script file using the MessageQ scripting language. When script processing is enabled, MessageQ processes the script file and executes the instructions.
If you need to view or record the exchange of messages between applications under development, you can use the Script Facility to capture messages sent or received by an application. Captured messages can be displayed on a monitor or written to a log file. Message capture documents messages sent and received by an application, enabling developers to debug message exchange.
The MessageQ Script Facility message replay feature is like using a tape recorder with messaging. First, using message capture, you record the messages sent or received by an application. Then, using replay, you send the messages captured in the log file as input to another application. Message replay can be used to debug message exchange between applications that are still under development.
Scripts can also be used to create a message to be sent. For example, if a sender program is under development, you can create a script file to simulate the messages that it will send. Then, when you enable script processing, the messages contained in the script file are delivered to the receiver program to test its response.
Note:
The MessageQ Script Facility is available on UNIX and OpenVMS systems only.
Use the scripting language commands to create script files that send messages, capture messages, or both. You can add instructions to the script file to repeat an operation, add a time delay between functions, or add comments to document the script file.
After you create the script file, you can use the Script Facility to verify that the syntax of the file is correct. If errors exist in the scripting language commands, MessageQ will highlight the line numbers and describe the errors to help you debug your MessageQ script.
When your script file is correct and ready for use, you enable script processing by setting the Script Facility environment variable to the name of the script file or the log file of captured messages to be used as input. When you run your application with the environment variable set, MessageQ reads the script file, delivers the defined messages to the target queues, and captures messages as specified.
MessageQ script files are ASCII files created using a text editor. Though the content must adhere to the scripting language syntax, it is not case sensitive and does not require that data be entered in specific column positions in the file.
On OpenVMS systems, you create a script file using a .PSS file extension. On UNIX systems, you create a script file using a .pss file extension. Use tabs and spaces within the script file to make it easier to read. See the Adding Repeats, Delays, and Comments to Scripts topic for more information on how to add comments to a script file to annotate its purpose and use.
The MessageQ scripting language uses commands to identify the functions to be performed. Table 7-1 describes information on MessageQ Script Facility commands:
The MessageQ Script Facility is most commonly used to capture messages sent or received by an application. Captured messages document message exchange and can be used as the input stream to another application to test its response.
For example, if you are testing message exchange between two running applications, you can use a script file to capture the output of the sender program. Figure 7-1 shows application A sending messages to application B and recording those messages in a log file.
The log file of captured messages can be used to document the messages sent by A. It can also be used as an input stream to B during testing if application A is not always available to send messages.
Depending on the requirements of your test environment and applications, you can choose to capture messages received rather than capturing messages sent. Figure 7-2 shows how to use a log file to capture messages received by an application.
Or, you can have the receiver program obtain messages from the script and messages from other applications as shown in Figure 7-5.
And, if the receiver program is ready for testing, but the sender program is not, you can create a script file to simulate message exchange. If you capture the output of application B during this process, you can use it as input to application A when it is ready for testing as shown in Figure 7-6.
The remaining sections of this topic provide more detailed information and examples of how to create script files.
The SET command is used to select messages for capture. The SET SEND command captures output by recording the messages sent by an application. The SET RECEIVE command captures input by recording the messages received by an application. The SET command uses the following syntax:
The modifiers to these commands are as follows:
How to Use the Script Facility
Using the MessageQ Scripting Language
Capturing, Replaying, and Simulating Message Exchange
Figure 7-1 Sending Messages and Capturing Output
Figure 7-2 Sending Messages and Capturing Input
In this example, the log of messages received by application B matches the log file of messages sent by application A. You can also use the Script Facility when one of your applications is not running. For example, Figure 7-3 shows how application A can capture messages it sends in a log file without MessageQ delivering the messages to application B.
Figure 7-3 Capturing Output Without Sending Messages
Then when application B is ready to test, you can use the script file containing messages sent by application A to test it. Figure 7-4 shows how to replay messages and to restrict application B to receiving only messages from the script file.
Figure 7-4 Replaying Captured Messages
Figure 7-5 Receiving Messages from Applications and Scripts
Figure 7-6 Writing Scripts to Send and Capture Messages
Capturing Messages Using Scripts
SET RECEIVE modifier [FROM MessageQ address]
SET SEND modifier [TO MessageQ address]
The FROM/TO address qualifier is the queue address of the message to which messages will be sent or from which messages will be read when the script is run.
Using the ON/OFF modifiers with the SET SEND and SET RECEIVE commands, you can control the delivery of messages from the script file and from other sources. Following is a list of valid commands that you can enter to your script file to control message delivery with scripts:
To display captured messages on the screen, use the ECHO modifier with the SET SEND or SET RECEIVE commands. Use the ECHO LINES=n modifier if you only want to display a specified number of lines of the message. Following is a list of valid commands that you can enter to your script file to display messages on the screen:
To write messages to a log file, begin by specifying the name of the log file. To create a new log file to store captured messages, use the following command:
Note:
File names are case sensitive on UNIX systems. Enter the file name with the exact upper- and lowercase letters that you will use to retrieve the file. The file name can be specified with a path name or directory name to store it in a specific area. Both absolute and relative path names can be used.
To add captured messages to an existing log file, use the following command:
If you do not provide a file extension, .LOG is used by default on OpenVMS systems and .log is used by default on UNIX systems. If you want to replay the captured messages, use .PSS (OpenVMS) or .pss (UNIX) as the file extension to distinguish the log file as an input file.
The beginning of each log file has a comment line containing the date and time it was created. A comment line is added each time the file is reopened. On UNIX systems, only one log file can be open at a time. On OpenVMS systems, a maximum of four log files can be open at a time.
To write captured messages to a log file, use the LOG modifier with the SET SEND or SET RECEIVE commands. Use the LOG LINES=n modifier if you want to log only a specified number of lines of the message. Following is a list of valid commands that you can enter to your script file to log messages to a file:
Controlling Message Delivery Using Scripts
Displaying Captured Messages on the Screen
Writing Captured Messages to a Log File
SET LOG file_name
SET LOG file_name APPEND
Listing 7-1 shows the syntax of a MessageQ script file that creates a log file named MYLOG.PSS, captures messages sent and received by the application, and displays them on the screen.
Listing 7-1
Sample Script to Capture Messages
COMMENT
Example MessageQ script source file to capture messages,
display them on the screen, and log them to a file.
ENDC
SET LOG MYLOG.PSS
SET RECEIVE ECHO LOG
SET SEND ECHO LOG MSG
TARGET=MHIS_EK_INTERFACE SOURCE=MHIS_REQ_PROCESSOR
CLASS=PAMS TYPE=ASRS_PERF_DATA_REQ
A '1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ'
EOM
Listing 7-2 shows the content of MYLOG.PSS created when script processing is enabled using the script file in the previous example.
Listing 7-2 Sample Log Generated by a Script File
!*** Session begun at 22-MAR-1994 10:37:23.95 *******************
MSG ! Message receive at 22-MAR-1994 10:37:26.21
SOURCE = 20,1 TARGET = 30,1
CLASS = PAMS TYPE = ASRS_PERF_DATA_REQ
XB 31, 32, 33, 34, 35, 36, 37, 38, 39, 30 !'1234567890'
XB 20, 41, 42, 43, 44, 45, 46, 47, 48, 49 !' ABCDEFGHI'
XB 4A, 4B, 4C, 4D, 4E, 4F, 50, 51, 52, 53 !'JKLMNOPQRS'
XB 54, 55, 56, 57, 58, 59, 5A, !'TUVWXYZ'
EOM
Though the format of the message data in the log file varies somewhat from a script file, it can be used exactly as a script file to simulate message exchange. Use a log file as input by setting the MessageQ environment variable DMQ_SCRIPT to equal the log file name. Then run the test application and it will receive and process the messages contained in the log file.
On UNIX systems, only one log file can be open at a time. However, the MessageQ Script Facility on OpenVMS systems lets you log messages to multiple log files simultaneously. Listing 7-3 shows how to write messages received by an application to one log file (RECEIVE.PSS) while writing messages sent by the application to another log file (SEND.PSS).
Listing 7-3 Sample Script Using Multiple Log Files
COMMENT
Example MessageQ script source file WITH LOGGING TO
MULTIPLE LOG FILES
ENDC
SET LOG RECEIVE.PSS
SET RECEIVE LOG
SET LOG SEND.PSS
SET SEND LOG
REPEAT 5
MSG TARGET=MHIS_EK_INTERFACE SOURCE=MHIS_REQ_PROCESSOR
CLASS=PAMS TYPE=ASRS_PERF_DATA_REQ
A '1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ'
A 'MSG FROM REPEAT NUMBER 1 - WHICH IS SENT 5 TIMES'
S 1
EOM
ENDR
To use the MessageQ Script Facility, you set an environment variable on UNIX systems or a logical name on OpenVMS systems to the name of the script file or the log file that you want to use as input to the application being tested. When you run the application after the environment variable is set, the Script Facility reads the script file or log file and uses the pams_put_msg function to deliver the messages contained in the file to the target queue.
Note: The script file may be only one of many sources of messages sent to the application. If messages are delivered to the application's primary queue from sources other than the script file, these messages will also be read and processed.
If the script file requests messages to be captured, the Script Facility signals the application to use MessageQ logging routines that write the messages sent or received by the application to the designated log file.
Script processing on UNIX systems is enabled by defining the environment variable dmq_script as the script file name or log file name that you want to use as input to the program being tested. Before setting the DMQ_SCRIPT environment variable, you must first set the BUS and GROUP_ID environment variables. Use the following commands to set the environment variable to enable script file processing. The command using csh syntax is:
setenv dmq_script mylog.pss
The command using sh syntax is:
DMQ_SCRIPT=mylog.pss
export DMQ_SCRIPT
When you run the application with MessageQ script processing enabled, MessageQ translates this symbol when the pams_attach_q function is called. MessageQ processes the script, directing messages to their target queues and turning on message logging, if applicable.
The Script Facility on UNIX systems also allows developers to initiate script processing for an application that is currently running. To enable script processing for a running application, use the dmqscript utility to direct a script file to the target queue of the application.
To turn on script processing, the script file must begin with the command SET SCRIPTS ON. To turn off script processing, the script must contain the SET SCRIPTS OFF command. Table 7-2 describes the script control commands which are only available on MessageQ for UNIX systems.
Listing 7-4 provides a sample script that turns on script processing to begin message logging for the running application.
Listing 7-4 Turning On Scripts for a Running Application
SET SCRIPTS ON
SET LOG /mypath/mylog.log
SET SEND LOG LINES=999
SET RECEIVE LOG LINES=999
To process a script file, use the following command syntax:
dmqscript -f script_file_name -q nn
where:
MessageQ for OpenVMS software enables script file processing when the logical name DMQ$SCRIPT is defined as a file name or as the word YES. The name of the script file to process can be specified in one of the following ways:
$ DEFINE DMQ$SCRIPT script_file_name
$ DEFINE DMQ$SCRIPT YES
$ RUN application_name
Script file: script_file_name
$ DEFINE DMQ$SCRIPT YES
$ ifn:==$drive_name:[directory_name]application_name
$ ifn script_file_name
When you use the Script Facility on MessageQ for OpenVMS systems, all messages defined in the script file are delivered to the target queue of the application program you run regardless of the specified message TARGET argument specified in the message header phrase.
To stop script file processing, use the DEASSIGN command as follows:
The DMQ$EXAMPLES directory contains a program called sender.c that enables application developers to set the target queue used with script processing. In addition, this program enables an application to read messages from a script file and forward them to a program that is already running.
If you are unable to create a script file using message capture, you can use the MessageQ scripting language to create a new file defining the message that you want to send. When script processing is enabled, MessageQ sends the message to a target queue where it is read by the application being tested.
To create a script file that sends a message to a target queue, use the scripting language to:
$ DEASSIGN DMQ$SCRIPT
Writing Scripts to Send Messages
To define a message, enter the following to the script file:
Listing 7-5 illustrates a MessageQ script file for sending a message to a target queue. The message in this example sends the numbers "0-9" and the letters "A-Z" to a target queue number 1 in group 30.
Listing 7-5
Sample Script to Send a Message
COMMENT
Example MessageQ script source file to send a message
ENDC MSG
TARGET=30,1
SOURCE=20,1
CLASS=PAMS
TYPE=ASRS_PERF_DATA_REQ
A '1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ'
EOM
To form a message header, the MessageQ scripting language uses descriptors to designate the target, source, class, and type arguments for the pams_put_msg function. Note that the equal sign (=) is optional, and the commands FROM and TO can replace the commands SOURCE and TARGET. Listing 7-6 shows the format of the message header.
Listing 7-6 Message Header Format
MSG
TARGET = {MessageQ address}
SOURCE = {MessageQ address}
CLASS = {PAMS class number}
TYPE = {PAMS type number}EOM
The message header descriptors require the following input to specify the pams_put_msg arguments:
In addition to the target, source, class, and type descriptors in the message header, the Script Facility on MessageQ for UNIX systems offers descriptors to specify the delivery, undeliverable message action (UMA), and priority arguments for the pams_put_msg function. Valid values for the delivery mode and UMA can be found in the p_symbol.h include file.
These additional UNIX message header descriptors require the following input to specify the pams_put_msg arguments:
Listing 7-7 shows the format of a complete UNIX message header.
Listing 7-7 UNIX Message Header Format
MSG
SOURCE = {MessageQ address}
TARGET = {MessageQ address}
CLASS = {PAMS class name}
TYPE = {PAMS type name}
DELIVERY = {MessageQ delivery mode}
UMA = {MessageQ undeliverable message action}
PRIORITY = {MessageQ priority}EOM
This topic describes the valid syntax for specifying message content. The MessageQ scripting language syntax requires you to specify the data format, data type, and content of the message.
The valid data formats are:
The content of the message is listed after the data format and data type codes. A comma (,) must separate values in the value list. Each value cannot exceed the maximum unsigned value that may be stored in the selected data field.
Table 7-3 lists the valid syntax and provides examples for how to specify message content.
In addition to commands for sending and capturing messages, you can add instructions to scripts that enable them to better simulate production conditions during testing. This topic describes how to:
Adding Repeats, Delays, and Comments to Scripts
The REPEAT and ENDR commands begin and end repeat groups. A repeat group allows messages to be repeated. The format for using this command is as follows:
The message contained between the REPEAT n and the ENDR is repeated n times. On UNIX systems, repeat commands can be nested to any level. On OpenVMS systems, REPEAT commands can be nested up to three levels and can contain any valid script syntax including delays.
The following example shows nested messages. In this example, the script will send one message of message type 1, four messages of message type 2 with a 1.5-second delay between them, and then send the same messages one more time.
You can insert a time delay into a script file by using the DELAY command. The DELAY command allows the simulation of an actual arrival pattern of messages. The DELAY command format follows:
where: For example, specify a delay of 0.5 second as follows:
The duration of the delay applies only to the processing of the MessageQ script file and the time of arrival of messages from the MessageQ script file to the user program. The user program will still receive messages from other sources during a delay interval.
Comments in the script source file can be specified in end-of-line format (<EOL>) or comment command format (COMMENT).
In the following format, text on the line following the exclamation point (!) to the end-of-line tag is ignored. An end-of-line comment can be placed wherever the syntax allows <EOL>.
In the following format, the text following the COMMENT command and all lines within the comment group are ignored until the ENDC command terminates the comment. Note that the comment statement can span any number of lines.
Once you have created the script file, you can verify that the syntax is correct before using it. See the following topics for instructions on how to verify scripts on UNIX and OpenVMS systems and how to resolve reported errors.
MessageQ for UNIX software provides a utility that verifies script syntax. It is called dmqscript. To verify a script file, use the following command syntax:
where: Repeating an Operation
REPEAT <n>
MSG
.
.
.
EOM
ENDRREPEAT 2
MSG
.
. ! MSG TYPE 1
.
EOM
REPEAT 4 ! NESTED REPEAT MESSAGE
MSG
.
. ! MSG TYPE 2
.
EOM
DELAY 1.5
ENDR
ENDR Entering Time Delays
DELAY <min>:<sec>.<tenths>
DELAY <min>:<sec>
DELAY <sec>.<tenths>
DELAY <sec>
min specifies the number of minutes from 0 to 59; sec specifies the number of seconds from 0 to 59; and tenths specifies the number of tenths of a second from 0 to 9.
DELAY 0.5
Entering Comments
End-of-Line Format
! comment text... <EOL>
Comment Command Format
COMMENT
..this shows comment text
which can span lines..
ENDC Verifying Script Files
Verifying Scripts on UNIX Systems
dmqscript -v -f script_file_name
|
-v |
Requests verification of script file syntax. |
|
-f script_file_name |
Provides the name of the script file to verify. The default extension for script files is .pss. |
MessageQ for OpenVMS software provides a utility that verifies script syntax. It is called DMQ$PSSVFY. The DMQ$PSSVFY utility can be accessed using both a menu interface and a command line interface. To use the menu interface, select the PSSVFY option on the MessageQ main menu. You will be prompted to provide the name of the script file to verify.
To use the command line interface, enter the following commands at the DCL prompt:
$ PSSVFY :== $ DMQ$EXE:DMQ$PSSVFY
$ PSSVFY script_file_name
The default file type for script files is .PSS. If you omit the script file name, the utility prompts you to supply it as follows:
$_File name:
If the script verification utility does not find any syntax errors in the file, it displays no output on the screen. If errors are found, this command creates a screen display listing syntax errors and the line number on which they were found. Listing 7-8 provides an example of a script file containing errors.
Listing 7-8 Sample Script File with Errors
REPEAT 2 !Send this message twice
MSG SOURCE = 34,1 TARGET = 35,1
CLASS = MATERIALS
DX 1, 2, 3
EOM
DELAY 10 !Delay 10 seconds before sending the repeat message
Listing 7-9 shows the output displayed on the screen when the script containing errors is processed.
Listing 7-9 Sample Output of Script File Verification Utility
%PAMSCRIPT-E-IVMSGTARG, Invalid message target name at line 3
-PAMSCRIPT-E-AMBIG, Ambiguous keyword
%PAMSCRIPT-E-NOMSGTO, Missing TARGET phrase in message definition
at line 5
%PAMSCRIPT-E-NOMSGTYPE, Missing TYPE phrase in message definition
at line 5
%PAMSCRIPT-E-IVDATATYPE, Invalid data type (expecting B, W, or L)
at line 5
%PAMSCRIPT-E-MISENDR, Unbalanced REPEAT at line 1, missing closing
ENDR command
%PAMSCRIPT-E-ERRORS, Errors encountered in script source file
Use the line numbers and error messages to identify the incorrect syntax in your script file. Use a text editor to make the corrections and verify the script again to ensure that all of the errors identified are corrected.