Hitachi

JP1 Version 11 JP1/Script Description and Reference (For Windows Systems)

8.6.2 Message (output text to a file or window)

Purpose

Outputs specified text to a file or window. Also erases the displayed window and message text.

Window display is supported from JP1/Script 01-01.

Syntax
Message (Target, [OutputName], [Text], [LineLength], [MaxLines], [xPos] [, yPos])
Arguments
Target

Specify the text output destination as one of the following values:

Value

Meaning

Target_File

Output to a file.

Target_DispOn (from 01-01)

Output to a window.

Target_DispClear (from 01-01)

Erase the message text displayed in the window.

Target_DispOff (from 01-01)

Erase the open window.

Target_SPAFile (from 05-20)

Output to the executing script's analysis trace file.

Target_SPXFile (from 05-20)

Output to the executing script's execution trace file.
OutputName

  • If you specified Target_File in Target:

    Specify the full path of the output file as a character string or as a variable that stores this value. If you omit the file extension, .TXT is automatically appended to the file name. However, in JP1/Script 06-00 and later versions, if you specify a file name ending with the extension period (.), the file is regarded as having no extension.

  • If you specified Target_DispOn, Target_DispClear, or Target_DispOff in Target:

    Specify the window title as a character string or as a variable that stores this value.

  • If you specified Target_SPAFile or Target_SPXFile in Target:

    You can omit the OutputName value because the system automatically sets the executing script's analysis trace file or execution trace file for trace output. If you specify OutputName, the system takes the specified string as a window title and outputs the message text to both the trace file and the window.

Text

  • If you specified Target_File, Target_DispOn, Target_SPAFile, or Target_SPXFile in Target:

    Specify the message text to output. Write a character string or specify a variable that stores this value. If #Option = NOCHANGE is missing from the head of the script file, any \r, \n, \t, or \\ strings included in the message text are processed as control codes.

    For details about control codes, see 6.1.11 Script coding conventions.

  • If you specified Target_DispClear or Target_DispOff in Target:

    The Text argument is invalid.

LineLength

  • If you specified Target_File in Target:

    Specify the line length of the output message text, excluding any \r and \n codes included in the message. Write the number of bytes or specify a variable that stores this value.

    You only need to specify a LineLength value the first time you execute the Message command for the file specified in OutputName. If you specify a different line length at any subsequent execution of the Message command for the same output file, the file will be recreated with the new line length.

    You can specify a value in the range from 128 to 1,024.

    The LineLength value is optional. If you omit this value, the value set in Max columns in User trace information in the execution environment file is assumed. If you omit this value and user trace information does not exist, the system assumes 150.

  • If you specified Target_DispOn, Target_DispClear, or Target_DispOff in Target:

    The LineLength value is invalid.

  • If you specified Target_SPAFile or Target_SPXFile in Target:

    The LineLength value is invalid. The system assumes the value set in Max columns in User trace information in the execution environment file.

MaxLines

  • If you specified Target_File in Target:

    Specify the maximum lines in the output message text as a number or as a variable that stores this value.

    As with LineLength, you only need to specify a MaxLines value the first time you execute the Message command for the file specified in OutputName. If you specify a different value in MaxLines at any subsequent execution of the Message command for the same output file, the file will be recreated with the new maximum number of lines.

    You can specify a value in the range from 100 to 9,999.

    The MaxLines value is optional. If you omit this value, the system assumes the value set in Max lines in User trace information in the execution environment file. If you omit this value and user trace information does not exist, the system assumes 1,024.

  • If you specified Target_DispOn, Target_DispClear, or Target_DispOff in Target:

    The MaxLines value is invalid.

  • If you specified Target_SPAFile or Target_SPXFile in Target:

    The MaxLines value is invalid. The system assumes the value set in Max lines in User trace information in the execution environment file.

xPos

  • If you specified Target_DispOn or Target_DispClear in Target, or specified Target_SPAFile#1 or Target_SPXFile#1 in Target in order to output trace messages to a window as well as to a trace file:

    Specify the horizontal distance from the left side of the screen to the left edge of the window. Specify the distance in pixels, where the left side of the screen is 0, or write a variable that stores this value.

    If you omit this argument, the window is centered horizontally on the screen. If you specify a negative value, zero is assumed.

  • If you specified Target_File or Target_DispOff in Target, or specified Target_SPAFile#2 or Target_SPXFile#2 in Target in order to not output trace messages to a window:

    The xPos value is invalid.

yPos

  • If you specified Target_DispOn or Target_DispClear in Target, or specified Target_SPAFile#1 or Target_SPXFile#1 in Target in order to output trace messages to a window as well as to a trace file:

    Specify the vertical distance from the top of the screen to the top of the window. Specify the distance in pixels, where the top of the screen is 0, or write a variable that stores this value.

    If you omit this argument, the window is centered vertically on the screen. If you specify a negative value, zero is assumed.

  • If you specified Target_File or Target_DispOff in Target, or specified Target_SPAFile#2 or Target_SPXFile#2 in Target in order to not output trace messages to a window:

    The yPos value is invalid.

#1 When a value is specified in OutputName

#2 When no value is specified in OutputName

Description

The Message command outputs a specified message text to a specified file or window. The command may also erase the displayed window and text message.

The command returns True on successful execution, or False if an error occurs.

Notes

  • You cannot use this command in a script started as a service. An execution error occurs if this command is used.

  • Take care when specifying an initialization file in the folder set in the environment variable ProgramFiles (normally the Program Files folder on the system drive) or WinDir (normally the Windows folder on the system drive). For details, see 1.8.2 Command behavior.

  • You can configure access permissions when creating a file specified for Target_File. In the following registry key, set the access permissions beforehand:

Registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Hitachi\JP1/Script\SPTX\Option

Value name

SecurityAttributesSucceed

Value datatype

REG_DWORD

Value

0: Access permissions are not set.

1: Access permissions are set to "Inherit access permissions from parent folders".

2: Access permissions are set to "Everyone: Full control".

If no value is set, or a value other than those above is set, the setting defaults to 0.

When the setting takes effect

The setting takes effect the next time the script file is executed.

Important note

  • If a script that specifies multi-activation in the execution environment contains a Message command that specifies Target_SPAFile or Target_SPXFile, and that script file is executed several times concurrently, the messages are output to the same analysis trace file or execution trace file. Note that because of this, exclusion control is applied to that file and execution performance may drop. The same situation occurs when the file name that is output by Target_File is fixed.

  • The files output by the Message command are not processed by the log file trapping function of JP1/Cm2/Extensible SNMP Agent or JP1/Base.

  • If you created files by using the Message command with Target_File specified, do not output these files in text format by using commands for manipulating files and folders or by using other applications. The output result of the subsequent Message command cannot be guaranteed.

  • If you create a large number of user trace files with unique names by using the Message command with Target_File specified, the increase in trace management files may have adverse effects on the performance of script execution. Script execution may terminate abnormally due to insufficient memory, or command execution may result in an error as shown in the following examples:

    - Script execution terminates abnormally with termination code 20.

    - The Copy command displays the message Insufficient memory.

    In this case, use the TextOpen, TextWrite, or TextClose command instead of the Message command to create a trace file.

Example
' Write the script execution log to "Logging.txt".
Message (Target_File, _BIN_+"Logging.txt", "Execution_
         has started.", 30, 100)
  ...
Message (Target_File, _BIN_+"Logging.txt", "Execution_
         has ended.")
 
' Display the script execution history on the screen.
Message (Target_DispOn, "Execution status", "Started",_
         , , 100, 100)
  ...
Message (Target_DispOn, "Execution status", "Ended", ,_
         , 100, 100)
Sleep (3000)
Message (Target_DispOff, "Execution status")

Display example

[Figure]

JP1/Script version

Supported from JP1/Script 01-00.

To Page Top

Trademarks

Copyright (C) 2016, Hitachi, Ltd.

Copyright (C) 2016, Hitachi Solutions, Ltd.