Using the Script Facility


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

MessageQ Doc Home \| Programmer's Guide \| Previous Topic \| Next Topic \| Contents \| Index

The BEA 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:

Simulate messages sent to an application without writing a test program
Selectively trace messages sent or received by an application and display them on the screen or log them to a file
Capture message traffic and replay the log files to support concurrent development and testing of applications
Simulate message traffic between client/server application components still under development
Create message trace files that assist developers in debugging applications based on message traffic
Stress test applications under different load levels by generating high levels of message traffic
Facilitate the development of large-scale integrated applications by simulating message traffic from remote components

Instructions are entered to the script file using the BEA MessageQ scripting language. When script processing is enabled, BEA 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 BEA 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 BEA MessageQ Script Facility is available on UNIX and OpenVMS systems only.

How to Use the Script Facility

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, BEA MessageQ will highlight the line numbers and describe the errors to help you debug your BEA 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, BEA MessageQ reads the script file, delivers the defined messages to the target queues, and captures messages as specified.

Using the BEA MessageQ Scripting Language

BEA 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. When including a group name in a script, the group name must start with a letter. Group names beginning with a number or special character are not allowed.

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 BEA MessageQ scripting language uses commands to identify the functions to be performed. Table 7-1 describes information on BEA MessageQ Script Facility commands:

Table 7-1 BEA MessageQ Script Facility Commands

Function
Command Begin/End

Modifiers

Description

Send a message

MSG/EOM

Identifies the beginning and end of the message header and content.

Capture messages sent

SET SEND

Sets message capture to include messages sent by the application.

ECHO

Displays messages on the screen.

ECHO LINES=n

Selects the number of lines displayed.

LOG

Writes messages to a log file.

LOG LINES=n

Selects the number of lines logged.

OFF

Captures messages sent by the application in a log file only; does not send messages to the target queue.

ON

Sends messages to the target queue and captures them in a log file. SET SEND ON is the default action for this command.

Capture messages received

SET RECEIVE

Sets message capture to include messages received by the application.

ECHO

Displays messages on the screen.

ECHO LINES=n

Selects the number of lines displayed.

LOG

Writes messages to a log file.

LOG LINES=n

Selects the number of lines logged.

OFF

Prevents the application from receiving messages from sources other than the script file.

ON

Application receives messages from all processes. SET RECEIVE ON is the default action for this command.

Set the log file name

SET LOG

file_name

Specifies the log file name. SET LOG must precede the SET SEND or SET RECEIVE commands in the script.

Add messages to an existing file

SET LOG

file_name APPEND

Adds messages to an existing log file.

Add comments

COMMENT/ENDC

Designates the beginning and end of comments to explain what the script file does.

Set a time delay

DELAY

time

Creates a time delay, which is useful to simulate message arrival patterns.

Repeat an operation

REPEAT/ENDR

Creates a repeat loop construct.

Function	Command Begin/End	Modifiers	Description
Send a message	MSG/EOM		Identifies the beginning and end of the message header and content.
Capture messages sent	SET SEND		Sets message capture to include messages sent by the application.
		ECHO	Displays messages on the screen.
		ECHO LINES=n	Selects the number of lines displayed.
		LOG	Writes messages to a log file.
		LOG LINES=n	Selects the number of lines logged.
		OFF	Captures messages sent by the application in a log file only; does not send messages to the target queue.
		ON	Sends messages to the target queue and captures them in a log file. SET SEND ON is the default action for this command.
Capture messages received	SET RECEIVE		Sets message capture to include messages received by the application.
		ECHO	Displays messages on the screen.
		ECHO LINES=n	Selects the number of lines displayed.
		LOG	Writes messages to a log file.
		LOG LINES=n	Selects the number of lines logged.
		OFF	Prevents the application from receiving messages from sources other than the script file.
		ON	Application receives messages from all processes. SET RECEIVE ON is the default action for this command.
Set the log file name	SET LOG	file_name	Specifies the log file name. SET LOG must precede the SET SEND or SET RECEIVE commands in the script.
Add messages to an existing file	SET LOG	file_name APPEND	Adds messages to an existing log file.
Add comments	COMMENT/ENDC		Designates the beginning and end of comments to explain what the script file does.
Set a time delay	DELAY	time	Creates a time delay, which is useful to simulate message arrival patterns.
Repeat an operation	REPEAT/ENDR		Creates a repeat loop construct.

Capturing, Replaying, and Simulating Message Exchange

The BEA 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.

Figure 7-1 Sending Messages and Capturing Output

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.

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 BEA 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

Or, you can have the receiver program obtain messages from the script and messages from other applications as shown in Figure 7-5.

Figure 7-5 Receiving Messages from Applications and Scripts

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.

Figure 7-6 Writing Scripts to Send and Capture Messages

For some programs, script output is buffered, depending on the operating system and whether the program is running in the background. For example, on a Solaris system, output from dmqcls is unbuffered, but output from dmqtest is buffered.

The remaining sections of this topic provide more detailed information and examples of how to create script files.

Capturing Messages Using Scripts

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:

SET RECEIVE  modifier [FROM MessageQ address]
SET SEND     modifier [TO MessageQ address]

The modifiers to these commands are as follows:

ON/OFF-determines whether messages are sent to the target or only to the log file, and whether the receiver program receives all input or input only from the script file
ECHO-displays captured messages on the screen
LOG-writes captured messages to the specified log file

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.

Controlling Message Delivery Using Scripts

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:

Command
Description

SET SEND OFF

Captures messages sent by the application but does not deliver them to the target queue.

SET SEND ON

Captures messages sent by the application and delivers them to the target queue. ON is the default for the SET SEND command.

SET RECEIVE OFF

Captures messages received by the application, but restricts the application to receiving only those messages sent from the script.

SET RECEIVE ON

Captures messages received by the application from the script and any other source. ON is the default for the SET RECEIVE command.

Command	Description
SET SEND OFF	Captures messages sent by the application but does not deliver them to the target queue.
SET SEND ON	Captures messages sent by the application and delivers them to the target queue. ON is the default for the SET SEND command.
SET RECEIVE OFF	Captures messages received by the application, but restricts the application to receiving only those messages sent from the script.
SET RECEIVE ON	Captures messages received by the application from the script and any other source. ON is the default for the SET RECEIVE command.

Displaying Captured Messages on the Screen

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:

Command
Description

SET SEND ECHO

Displays the messages sent by the application to the screen.

SET SEND ECHO LINES=n

Displays n lines of the messages sent by the application to the screen.

SET RECEIVE ECHO

Displays the messages received by the application to the screen.

SET RECEIVE ECHO LINES=n

Displays n lines of the messages received by the application to the screen.

Command	Description
SET SEND ECHO	Displays the messages sent by the application to the screen.
SET SEND ECHO LINES=n	Displays n lines of the messages sent by the application to the screen.
SET RECEIVE ECHO	Displays the messages received by the application to the screen.
SET RECEIVE ECHO LINES=n	Displays n lines of the messages received by the application to the screen.

Writing Captured Messages to a Log File

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:

SET LOG file_name

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.

Note: If SET LOG is used in a script, the pams_get_msg call used to activate scripting must be at least 1036 bytes in size.

To add captured messages to an existing log file, use the following command:

SET LOG file_name APPEND

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:

Command
Description

SET SEND LOG

Writes the messages sent by the application to the specified log file.

SET SEND LOG LINES=n

Logs n lines of the messages sent by the application to the specified log file.

SET RECEIVE LOG

Logs the messages received by the application to the specified log file.

SET RECEIVE LOG LINES=n

Logs n lines of the messages received by the application to the specified log file.

Command	Description
SET SEND LOG	Writes the messages sent by the application to the specified log file.
SET SEND LOG LINES=n	Logs n lines of the messages sent by the application to the specified log file.
SET RECEIVE LOG	Logs the messages received by the application to the specified log file.
SET RECEIVE LOG LINES=n	Logs n lines of the messages received by the application to the specified log file.

Listing 7-1 shows the syntax of a BEA 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 BEA 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.

Writing Captured Messages to Multiple Log Files

On UNIX systems, only one log file can be open at a time. However, the BEA 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

Replaying Messages

To use the BEA 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 BEA MessageQ logging routines that write the messages sent or received by the application to the designated log file.

Script Processing on UNIX Systems

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

Define the DMQ_SCRIPT environment variable after running the Group Control Process (dmqgcp) to boot the system. If DMQ_SCRIPT is defined before booting the system, processing a script produces error messages for each line of the script.

When you run the application with BEA MessageQ script processing enabled, BEA MessageQ translates this symbol when the pams_attach_q function is called. BEA MessageQ processes the script, directing messages to their target queues and turning on message logging, if applicable. Script processing on UNIX systems begins when the target process issues a pams_get_msg or pams_get_msgw call.

Client programs do not access the DMQ_SCRIPT environment variable or perform script processing directly. Instead, the client program uses the associated Client Library Server (CLS) to perform script processing. Writing to the log file or echoing output is performed relative to the CLS rather than the client program.

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 BEA MessageQ for UNIX systems.

Table 7-2 Script Control Commands (UNIX only)

Function
Command Begin/End

Modifier

Description

Enable script processing

SET SCRIPTS

ON

This command is sent to an application that is already running, enabling it to receive messages from a script file or begin capturing messages.

Disable script processing

OFF

This command turns off script processing for a running application. The application no longer receives messages from the script file and stops capturing -messages.

Function	Command Begin/End	Modifier	Description
Enable script processing	SET SCRIPTS	ON	This command is sent to an application that is already running, enabling it to receive messages from a script file or begin capturing messages.
Disable script processing		OFF	This command turns off script processing for a running application. The application no longer receives messages from the script file and stops capturing -messages.

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:

-f script_file_ name

Provides the name of the script file to process. The default extension for script files is .pss.

-q nn

Specifies the queue number of the application to which the script control commands SET SCRIPTS ON or SET SCRIPTS OFF should be directed.

Script Processing on OpenVMS Systems

BEA 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 the logical name DMQ$SCRIPT to pass the script file name directly to the Script Facility as follows:
```
$ DEFINE DMQ$SCRIPT script_file_name
```
Then run the application that you want to test using the script file as input.
Set the logical name DMQ$SCRIPT to YES, run the application that you want to test, and enter the script file name in response to the prompt as follows:
```
$ DEFINE DMQ$SCRIPT YES
$ RUN application_name
Script file: script_file_name
```
Define a DCL foreign command to invoke an image file name. The script file name then can be entered directly on the DCL command line, as follows:
```
$ DEFINE DMQ$SCRIPT YES
$ ifn:==$drive_name:[directory_name]application_name
$ ifn script_file_name
```

When you use the Script Facility on BEA 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:

$ DEASSIGN DMQ$SCRIPT

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.

Writing Scripts to Send Messages

If you are unable to create a script file using message capture, you can use the BEA MessageQ scripting language to create a new file defining the message that you want to send. When script processing is enabled, BEA 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:

Designate the beginning and end of the message
Specify the source, target, type and class descriptors that form the message header
Create the message content

Defining Messages in Scripts

To define a message, enter the following to the script file:

The MSG command to designate the beginning of the message definition
The message header information including the target, source, class, and type of the message
The message data
The EOM command to designate the end of the message definition

Listing 7-5 illustrates a BEA 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

Defining the Message Header

To form a message header, the BEA 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:

Argument
Description

TARGET

The queue address to which the messages in the script file are sent. The Script Facility allows the PAMS_ prefix to be omitted. On OpenVMS systems, the script file messages are directed to the primary queue of the running application regardless of the target queue specified.

SOURCE

Queue address of the message source. The script facility allows the PAMS_ prefix to be omitted.

TYPE

Descriptor identifying the message type. The Script Facility allows the MSG_TYP_ prefix to be omitted.

CLASS

Descriptor identifying the message class. The script facility allows the MSG_CLS_ prefix to be omitted.

Argument	Description
TARGET	The queue address to which the messages in the script file are sent. The Script Facility allows the PAMS_ prefix to be omitted. On OpenVMS systems, the script file messages are directed to the primary queue of the running application regardless of the target queue specified.
SOURCE	Queue address of the message source. The script facility allows the PAMS_ prefix to be omitted.
TYPE	Descriptor identifying the message type. The Script Facility allows the MSG_TYP_ prefix to be omitted.
CLASS	Descriptor identifying the message class. The script facility allows the MSG_CLS_ prefix to be omitted.

Additional Arguments for UNIX Systems

In addition to the target, source, class, and type descriptors in the message header, the Script Facility on BEA 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:

Argument
Description

DELIVERY

Value for the delivery mode as defined in the p_symbol.h include file.

UMA

Value for the undeliverable message action as defined in the p_symbol.h include file.

PRIORITY

Message priority, where 0 is the lowest priority and 99 is the highest priority.

Argument	Description
DELIVERY	Value for the delivery mode as defined in the p_symbol.h include file.
UMA	Value for the undeliverable message action as defined in the p_symbol.h include file.
PRIORITY	Message priority, where 0 is the lowest priority and 99 is the highest priority.

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 value}
   UMA  = {MessageQ undeliverable message action value}
   PRIORITY = {MessageQ priority}

EOM

Defining the Message Data

This topic describes the valid syntax for specifying message content. The BEA MessageQ scripting language syntax requires you to specify the data format, data type, and content of the message.

The valid data formats are:

D-Decimal
X-Hexadecimal
O-Octal
Z-Zero-fill
A-ASCII
S-ASCII space-fill

The binary data formats allow the specification of bytes, words, and longwords. Data types for each data format are described in the script file as follows:

B-A list of 8-bit bytes
W-A list of 16-bit words
L-A list of 32-bit longwords

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.

Table 7-3 Valid Message Data Syntax

Data Format
Syntax/Description

Decimal Binary Data

D (B/W/L) <SIGNED_NUMBER>, ... <SIGNED_NUMBER>

The values are stored in the message in binary format. The word decimal applies only to the base used in entering the data values in the script file. The values are not stored in packed decimal format.

Hexadecimal Binary Data

X (B/W/L) <HEX_NUMBER>, ... <HEX_NUMBER>

The values are stored in the message as unsigned hexadecimal values.

Octal Binary Data

O (B/W/L) <OCTAL_NUMBER>, ... <OCTAL_NUMBER>

The numeric values in the octal binary data phrase are unsigned octal numbers.

Zero-Fill Binary Data

Z (B/W/L) <NUMBER>, ... <NUMBER>

The values are stored in the message as unsigned decimal values.

ASCII Data

A(<NUMBER>)'<ASCII_CHARACTERS>'

A(<NUMBER>)"<ASCII_CHARACTERS>"

An unsigned decimal value specifying the number of blanks to fill into successive fields of the size specified by data type. This format allows the text string to be left-justified into a field <NUMBER> length long. This allows easy space-filling of a field after the text string.

Characters in the quoted string fill into successive bytes starting at the current position in the message text. Note that spaces and tabs are significant when enclosed in quoted strings and that the case of characters in quoted strings is preserved.

ASCII Space-Fill Data

S<NUMBER>

An unsigned decimal value that specifies the number of spaces to fill into successive bytes starting at the current position in the message text

Data Format	Syntax/Description
Decimal Binary Data	D (B/W/L) <SIGNED_NUMBER>, ... <SIGNED_NUMBER> The values are stored in the message in binary format. The word decimal applies only to the base used in entering the data values in the script file. The values are not stored in packed decimal format.
Hexadecimal Binary Data	X (B/W/L) <HEX_NUMBER>, ... <HEX_NUMBER> The values are stored in the message as unsigned hexadecimal values.
Octal Binary Data	O (B/W/L) <OCTAL_NUMBER>, ... <OCTAL_NUMBER> The numeric values in the octal binary data phrase are unsigned octal numbers.
Zero-Fill Binary Data	Z (B/W/L) <NUMBER>, ... <NUMBER> The values are stored in the message as unsigned decimal values.
ASCII Data	A(<NUMBER>)'<ASCII_CHARACTERS>' A(<NUMBER>)"<ASCII_CHARACTERS>" An unsigned decimal value specifying the number of blanks to fill into successive fields of the size specified by data type. This format allows the text string to be left-justified into a field <NUMBER> length long. This allows easy space-filling of a field after the text string. Characters in the quoted string fill into successive bytes starting at the current position in the message text. Note that spaces and tabs are significant when enclosed in quoted strings and that the case of characters in quoted strings is preserved.
ASCII Space-Fill Data	S<NUMBER> An unsigned decimal value that specifies the number of spaces to fill into successive bytes starting at the current position in the message text

Adding Repeats, Delays, and Comments to Scripts

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:

Repeat an operation in a script
Enter time delays to simulate message arrival patterns
Add comments to document script functions

Repeating an Operation

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:

REPEAT <n>
     MSG
       .
       .
       .
     EOM
ENDR

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.

REPEAT 2
     MSG
       .
       . ! MSG TYPE 1
       .
     EOM
    REPEAT 4   ! NESTED REPEAT MESSAGE
         MSG
           .
           .   ! MSG TYPE 2
           .
         EOM
         DELAY 1.5
    ENDR
ENDR

Entering Time Delays

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:

DELAY <min>:<sec>.<tenths>

DELAY <min>:<sec>

DELAY <sec>.<tenths>

DELAY <sec>

where:
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.

For example, specify a delay of 0.5 second as follows:

DELAY 0.5

The duration of the delay applies only to the processing of the BEA MessageQ script file and the time of arrival of messages from the BEA MessageQ script file to the user program. The user program will still receive messages from other sources during a delay interval.

Entering Comments

Comments in the script source file can be specified in end-of-line format (<EOL>) or comment command format (COMMENT).

End-of-Line Format

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>.

! comment text... <EOL>

Comment Command Format

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.

COMMENT
..this shows comment text
which can span lines..
ENDC

Verifying Script Files

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.

Verifying Scripts on UNIX Systems

BEA 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:

dmqscript -v -f script_file_name

where:

-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.

Verifying Scripts on OpenVMS Systems

BEA 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 BEA 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:

Resolving Script Verification Errors

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.

-f script_file_ name	Provides the name of the script file to process. The default extension for script files is .pss.
-q nn	Specifies the queue number of the application to which the script control commands SET SCRIPTS ON or SET SCRIPTS OFF should be directed.

-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.

Table 7-1 BEA MessageQ Script Facility Commands

Table 7-2 Script Control Commands (UNIX only)

Table 7-3 Valid Message Data Syntax