Chapter 1: Command Line Utilities

ims.nn script

Some commands require the prefix NN, such as NNCrypt, NNPutMsg, and NNGetMsg. These files are used in conjunction with Open Transport-XML implementations. See the e-Biz Impact Monitoring Guide and the e-Biz Impact Application Guide for more information.

NNCrypt

Description

Encrypts a file with a private key. Use NNCrypt to encrypt or decrypt the nnsyreg.dat configuration file.

Syntax

NNCrypt {-encrypt | -decrypt} -file  fileName

Parameters

-encrypt -file fileName – encrypt the specified file.
-decrypt -file fileName – decrypt the specified file.

Encrypting a file does not change its functionality. After a file has been encrypted, the configuration files can be used the same as a file that is not encrypted.

NNGetmsg

Description

Performs a get of messages for testing. NNGetmsg reads an inbound transport, retrieves one message at a time, and writes each message to the output file until the transport is empty.

Syntax

NNGetmsg -o output filename
     -t transport ID
     -x context ID
     [-p]
     [-v]
     [-pFile parameter filename]
     [-pGroup parameter group]
     [-m message ID]
     [-commitInterval {number > 0 | ALL}]
     [-blockingTimeout {time in milliseconds | INFINITE}
     [-delimiter delimiter]
     [-messageCount n]

Parameters

-o output filename – required. The output file to which message are written. The user must have write privileges in the directory in which NNGetmsg is executed.
-t transport ID – required. The transport ID from which the message is read.
-x context ID – optional. The Open Transport context ID to use when retrieving messages from a transport. The default is “output”.
-p – optional. Writes message properties to the output file (output filename). The default is to write message properties to the screen.
-v – optional. Turns on verbose mode where NNGetmsg logs are written to the screen. The defaults is no logging.
-pFile parameter filename – optional. The name of the file from which to read program arguments.
-pGroup parameter group – optional. The parameter group location within the parameter file.
-m message ID – optional. NNGetmsg retrieves the next message matching the specified ID from the transport. The messageID can be specified in ASCII-encoded hexidecimal code because message IDs typically contain unprintable characters. An error is returned if the transport does not support retrieving messages based on the messageID.
-commitInterval {number > 0 | ALL} – optional. The number of messages that can be received from the transport as part of a single transaction. If the commitInterval is larger than the number of available messages, NNGetmsg sends all available messages within one transaction. If the number of messages does not divide evenly into the commitInterval, the final transaction will contain fewer messages than the commitInterval value specified. The value must be greater than zero. The value “ALL” commits all messages in a single transaction. If the value is not specified, the default is one (1). This parameter is ignored if the transport is non-transactional.
-blockingTimeout {time in milliseconds | INFINITE} – optional. Specify a blocking timeout in milliseconds or specify “INFINITE”. NNGetmsg blocks on an empty transport for the time you specify before ending. An error is returned if the transport does not support blocking.
-delimiter delimiter– optional. The delimiter used to separate messages in the output file. The value can be any number of printable or non-printable characters. Only application information is written to the output file. Control information, such as message properties, message descriptor fields, message count, or message size, is not written to the output file. The assumption is that the output file is intended for reload to a transport at a later date. Output files generated by NNGetmsg with the delimiter property are readable by NNPutmsg.
-messageCount n – enter the number of messages to receive.

Remarks

NNgetmsg expects the defined transport name to exist and to be enabled.

Examples

Use the following examples for reference.

Example 1 – this example uses the default context “output” to put all messages from the OutQ transport to the file outputfile.txt.
```
NNGetmsg -o outputfile.txt -t OutQ -v
```
Example 2 – this example uses the “rules” context to put all messages from the OutQ transport to the file outputfile.txt. The message properties are also sent to outputfile.txt.
```
NNGetmsg -o outputfile.txt -t OutQ -v -x rules -p
```

NNPutmsg

Description

Performs a put of messages for testing. NNPutmsg reads messages from a file and puts the messages on the specified transport as defined by the nnsyreg.dat file.

Syntax

NNPutmsg -t transport ID
     [-i input filename]
     [-a application group]
     [-m message type]
     [-x context ID]
     [-r]
     [-S component name]
     [-C {MSG | SUB}]
     [-d]
     [-v]
     [-pFile parameter filename]
     [-pGroup parameter group]
     [-delimiter delimiter]
     [-persistent]
     [-nonPersistent]
     [-messageProperties {property name=property value,
                                        property name=property value,
                                        property name=property value}]
     [-commitInterval {number > 0 | ALL}]
     [-repeatCount number > 0]
     [-chunkSize number > 0]

Parameters

-t transport ID – required. The ID of the transport where the message is sent.
-i input filename – optional. The input file from which NNPutmsg reads. The file must reside in the directory from which the process is run, or the fully qualified path must be provided. The default is an empty message.
-a application group – optional. The application group to associate with the message.
-m message type – optional. Sets the message type.
-s context ID – optional. Specifies the Open Transport context ID to use when sending the message. The default context ID is used if this parameter is not specified.
-r – optional. Reloads the message.
-S component name – required if -r is set. Identifies which component name to reload. If the process cannot set this property, a failure occurs and the process terminates.
-C {MSG | SUB} – required if -r is set. Specifies the message type of the component being reloaded.
-d – optional. Shuts down the message.
-v – optional. Turns on verbose mode where NNPutmsg logs are written to the screen. The default is no logging.
-pFile parameter filename – optional. Specifies the name of the file from which to read the program arguments.
-pGroup parameter group – optional. Specifies the parameter group location within the parameter file.
-d delimiter – optional. The delimiter used to parse messages. This value can be a printable or non-printable characters.
-persistent – optional. Sends the message in persistent mode.
-nonPersistent – optional. Sends messages in non-persistent mode.
-messageProperties – optional. Allows multiple properties to be set for messages prior to sending the message to the transport. Specify binary property values using ASCII-encoded hexidecimal code. This parameter allows you to set transport-specific message properties, such as AppIdentityData, filed in the WebSphere MQ message descriptor. Using this method requires accuracy for the property name.
-commitInterval {number > 0 | ALL} – optional. The number of messages to send as a single transaction. The value must be greater than zero. The value “ALL” sends all messages in a single transaction. If you do not specify this value, it defaults to one (1). If commitInterval is larger than the number of available messages, NNPutmsg sends all available messages within one transaction. If the number of messages does not divide evenly into the commitInterval, the final transaction will contain fewer messages than the commitInterval value specified. This parameter is ignored if the transport is non-transactional.
-repeatCount number > 0 – optional. Sends each message the number of times specified here. This value must be greater than zero. If this value is not specified, the default is one (1).
-chunkSize number > 0 – optional. Parses messages into chunks of the size specified by this parameter. This value must be greater than zero.

Remarks

Parsing messages from a single file Messages can be parsed by using a delimiter or a chunk size, depending on the parameter value specified. Because the delimiter and chunkSize parameters are mutually exclusive, specify a value for only one of these parameters. If neither a delimiter nor chunkSize is specified, NNPutmsg assumes the file contains one message.

Examples of delimiters include:

-delimiter 0x32

-delimiter @@@@

A chunkSize parses the input file into messages of fixed size, measured by byte count. For example:

-chunkSize 10

This example parses an input file containing 100 bytes into 10 messages, each 10 bytes in size.

Sending persistent or non-persistent messages All messages in a given run, from the start until the stop of the executable, are sent in persistent or non-persistent mode, depending on which parameter is set when NNPutmsg is started. Use the following guidelines to determine whether to use persistent or non-persistent mode:

Persistent mode writes all messages to a persistent store. This allows data to be recoverable in the case of a system failure. With this mode, the time required by NNPutmsg to put each message is increased.
Non-persistent mode stores messages in memory during processing. If there is a system failure, data is not recoverable.

If a persistence mode is not specified, NNPutmsg defaults to the behavior specified by the transport. Some transports support only persistent messages, others support only non-persistent messages.

Examples

Use the following examples for reference.

Example 1 – this example uses default context to put a message from inputfile.txt onto RulesIn transport with application group and message type properties set. The message contains all data from inputfile.txt until the end of the file.
```
NNPutmsg -i inputfile.txt 
```
```
    -a TestApp
```
```
    -m TestFmt
```
```
    -t RulesIn
```
```
    -v
```
Example 2 – This example uses rules context to put a message from inputfile.txt onto RulesIn transport with application group and message type properties set. Before message evaluation, a reload occurs for the subscription TestSub.
```
NNPutmsg -i inputfile.txt
```
```
    -a TestApp
```
```
    -m TestFmt
```
```
    -t RulesIn
```
```
    -v
```
```
    -x rules
```
```
    -r
```
```
    -C SUB
```
```
    -S TestSub
```
Example 3 – this example uses rules context to put a message from inputfile.txt onto InQ transport with application group and message type properties set. The reload and component type signals a reload of the rule set before evaluating the message.
```
NNPutmsg -i inputfile.txt
```
```
    -a TestApp
```
```
    -m TestFmt
```
```
    -t InQ
```
```
    -v
```
```
    -x rules
```
```
    -r
```
```
    -C SUB
```
Example 4 – this example uses rules context to put a message from inputfile.txt onto InQ transport with application group and message type properties set. The shutdown property signals a shutdown after message evaluation.
```
NNPutmsg -i inputfile.txt
```
```
    -a TestApp
```
```
    -m TestFmt
```
```
    -t InQ
```
```
    -v
```
```
    -x rules
```
```
    -r
```
```
    -d
```

See Monitoring e-Biz Impact and the Open Transport 2.6 Configuration Guide on the e-Biz Impact SyBooks CD that comes with the product, and the New Era of Networks Adapter for SAP R/3 3.9 User’s Guide on the Sybase Product Manuals Web site for more information about using NN-type commands.

View this book as PDF