7.3.1 Common specifications

Describe common specifications of the data transfer command. The contents are as follows.

Command format and the grammatical rule
Common options
Return code
Log outputting
File path
Configuration files
Operation at the time of the data transfer failure
The execution at the same time on the same PC

Organization of this subsection

(1) Command format and the grammatical rule
(2) Common options
(3) Return code
(4) Log outputting
(5) File path
(6) Configuration files
(7) Operation at the time of the data transfer failure
(8) The execution at the same time on the same PC

(1) Command format and the grammatical rule

Describe the format, the grammatical rule and the specification method of the data transfer command. In addition, in the case of Linux, read the extension "bat" of a command name as "sh".

[Figure]

Call (i) "Option", and call (ii) "Argument".

Specify the data transfer command in accordance with the following grammatical rule.

A specification order is arbitrary when you specify two or more options.
Cannot specify two or more same options.
The command becomes an error when you specify the option not existing.
Enclose by double quotes the value if you specify the value including blank.
Specify an escape character (^) before the character if you specify the command line special character & (Ampersand), ^ (Circumflex accent) and so on.
Cannot specify " (double quotes).
Specify the command whose length is less than 8192 characters.
When you specify two or more values to one option, divide and specify between values by blank.
When two or more values are specified as an option, the value specified first is used as the option in which only one has a value. All the values are used as an option with two or more values.

To Page Top

(2) Common options

Common options of the data transfer command is as follows.

Table 7‒3: The list of common options
No	Options	Meaning
1	-property	Specify the path of the Command Property File (property.xml) which is described the information on User ID/Password to send or receive the data. For more information about the Command Property File, refer to 7.3.1(6) (a) The Command Property File (property.xml).
2	-concurrenttimeout	If the data transfer command has already been executed, this option means the timeout value (seconds) to wait the termination of other execution. Specify 0 to 86400 (24 hours). If you specify 0, the data transfer command ends without the end of execution of other data transfer commands. If you do not specify the timeout value, 0 is applied.

To Page Top

(3) Return code

The return code which is outputted by the execution of the data transfer command is as follows.

In Windows, if it is immediately after termination of the data transfer command, you can check the return value with environment variable "ERRORLEVEL". For example, if you execute "echo %ERRORLEVEL%" by the command line interface immediately after termination of the data transfer command, the return code can be outputted to the standard output.

Table 7‒4: The list of the return code
Return code	Explanation
0	The data transfer command ended normally.
2	The state of the suspended is ended.
3	Refusal state of the reception is ended.
4	The data transfer command ended with warning. Although some tasks ended abnormally, other tasks ended normally.
8	The data transfer command does not execute because another data transfer command has already been executed.
12	Cancellation is ended.
16	The data transfer command ended abnormally. When the error occurred, the following processing is not executed. Details of the error are outputted to log files.
32	Java VM ended abnormally.
64	Java VM could not be run because of the invalid path was specified to the environment variable.

To Page Top

(4) Log outputting

This section describes the application log which is outputted by the data transfer command.

(a) Log level

The list of the application log's log level is as follows.

Table 7‒5: The list of the application log's log level
No	Log level	ID	Severity level	Contents	For monitoring
1	Error	E	Need to manage by representation user or system administrator.	Processing of the data transfer command cannot be continued because of the following cause. The problem of execution environment such as network environment. The problem of the input parameter of the data transfer command. This failure is required to manage by representation user. Management by a system administrator may be required. In this case, the return code 16 or 8 is outputted to log files.	Yes
2	Warn	W	Temporary failures	When you execute the data transfer command, the abnormal event has occurred. Processing of the data transfer command is continued. In this case, the return code 4 is outputted to log files.	Alternative
3	Info	I	Usual events	This log level indicates processing is executing normally.	No

(b) Log files

The specification of log files is as follows.

Table 7‒6: The specification of log files
No	Items	Format or value
1	File format	Text format
2	Character code	UTF-8
3	Newline code	CR+LF

Log files are outputted to the following path. The storage period is 30 days.

<Install destination folder of JP1/DH - AJE (Job Execution)>\log\dwc-yyyyMMddhhmmss-GUID.log

(Explanatory notes)

<Install destination folder of JP1/DH - AJE (Job Execution)>: The folder which was installed the data transfer command.
yyyyMMddhhmmss : The execution date-time of the data transfer command. (yyyy : 4 figures of A.D., MM : 2figures of month, dd : 2figures of day, hh : 2figures of time (24hours), mm : minute, ss : second)

GUID : The random character string of GUID format

Note:: Whenever you execute the data transfer command, a new log file is outputted to the default output folder. When the log output folder does not exist, it is created automatically and the log is outputted. In addition, if you execute the data transfer command after the storage period, log files will be deleted automatically.

(c) Output format

The output format of the application log is as follows.

Date Delimiter Time [Figure] VersionLog levelMessage IDMessage text

(Explanatory notes): : This sign shows a blank which is one byte.

The example output of the application log is as follows.

2011/04/19T20:38:21.500 01-07 INFO DWCO1001_I Command start.

2011/04/19T20:38:28.250 01-07 INFO DWCO1041_I Sending files completed.

2011/04/19T20:38:28.250 01-07 INFO DWCO1002_I Command finished.

The output contents of the application log are as follows. For concrete messages, refer to 7.4.2 Messages of the data transfer command.

Table 7‒7: The output contents of log files
No	Items	Figures	Output contents
1	Date	10	yyyy/MM/dd yyyy : 4 figures of A.D. MM : 2figures of month dd : 2figures of day
2	Delimiter	1	T
3	Time	12	HH:mm:ss.SSS HH : 2figures of time (24hours) mm : minute ss : second SSS : millisecond In addition, the output time is the time of client.
4	Version	8	01-05 Left-justification, and right-hand side is filled up with .
5	Log level	5	Log level. This is left-justification. For more information, refer to 7.3.1(4) (a) Log level.
6	Message ID	10	ID to specify the messages. XXXXYYYY_Z XXXX : Product code YYYY : Message number Z : ID of the log level (I : Info, W : Warn, E : Error)
7	Message text	Variable length	The contents of message Newline may be included when it includes the stack trace information on Java.

To Page Top

(5) File path

Specify the file path of the data transfer command with an absolute path.

The path notation can be specified in the format of both UNC format and local path format. But the transmission speed may become a low under the following condition because the transmission speed between the client and the network folder becomes a bottleneck.

When you send files on the network
When you receive files by the network folder

In such a case, we recommend you to specify the local file path which is specified as the data transfer command because the fast communication which is the feature of Data Highway - Server cannot be employed efficiently.

To Page Top

(6) Configuration files

The explanation about the configuration files is as follows.

Table 7‒8: The list of the configuration files
No	Configuration files	Explanation
1	The Command Property File	Specify the information on user's User ID/Password.
2	The Received List File	Received delivery information is indicated.

(a) The Command Property File (property.xml)

This is the XML file which is described the information on user's User ID/Password. Specify this file's path as an argument when you execute the data transfer command. Since the password is described with plain text, set up suitable security such as setting up the right to access.

The specification of the Command Property File is as follows.

Table 7‒9: The specification of the Command Property File
No	Items	Format or value
1	File format	XML format
2	Character code	UTF-8
3	Newline code	CR+LF

The format of the Command Property File is as follows.

<?xml version="1.0" encoding="utf-8" ?>
<property>
    <serverUrl>value</serverUrl>
    <userId>value</userId>
    <password>value</password>
    <authenticationMethod>value</authenticationMethod>
    <certificatePath>value</certificatePath>
    <certificatePassword>value</certificatePassword>
    <useProxy>value</useProxy>
    <proxyHost>value</proxyHost>
    <proxyPort>value</proxyPort>
    <proxyId>value</proxyId>
    <proxyPassword>value</proxyPassword>
</property>

Each setting item is as follows.

Table 7‒10: Setting items of the Command Property File
No	Setting items	Element name	Explanation	Default value
1	Connection server URL	serverUrl	Specify URL of the connection server. (Example) https://jp1dh-hitachi.co.jp/	N/A
2	User ID	userId	Specify the User ID for login to the connection server. When you specify "Login by Certification" as Authentication method, you can omit to specify this setting item. When you specify "Login by Password" as Authentication method, you must specify this setting item. (Example) user@company	N/A
3	Password	password	Specify the Password for login to the connection server. Authentication system of the login user appoints a password registered with a directory server of the connection at the time of "LDAP authentication system". When you specify "Login by Certification" as Authentication method, you can omit to specify this setting item. When you specify "Login by Password" as Authentication method, you must specify this setting item. Specify the password character string^#1 by plain text, or specify the digest^#2 of the password character string by the hexadecimal format. Use "LDAP authentication" for authentication system, cannot appoint the digest form. Example of the specification in plain text : password When you specify this setting item by the digest, the digest character string of 40 characters is filled in after "text:HEX:". The digest character string portion does not have distinction of a capital letter and a small letter. The digest can be specified what is displayed on the password area at exporting. Example of the specification in the digest : text:HEX:5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8 In addition, you cannot specify the character string which starts in "text:HEX:" as the password character string of plain text. (Example) password	N/A
4	Authentication method	authenticationMethod	Specify the authentication method. When you omit to specify this setting item, "Login by Password" is applied. PASSWORD : Login by Password CERTIFICATION : Login by Certification	PASSWORD
5	Path of the certificate file	certificatePath	Specify the path of the certificate file with an absolute path. When you specify "Login by Password" as Authentication method, you can omit to specify this setting item. When you specify "Login by Certification" as Authentication method, you must specify this setting item.	N/A
6	Password of the certificate file	certificatePassword	Specify the password of the certificate file. When you specify "Login by Password" as Authentication method, you can omit to specify this setting item. When you specify "Login by Certification" as Authentication method, you must specify this setting item.	N/A
7	Proxy use flag	useProxy	Specify whether the command uses the proxy server. When the command uses the proxy server : true When the command does not use the proxy server : false This setting item does not distinguish a capital letter and a small letter. (Example) true	False
8	Hostname of the proxy server	proxyHost	Specify the hostname or IP address of the proxy server. (Example1) Proxyserver (Example2) 192.168.0.1	N/A
9	Port number of the proxy server	proxyPort	Specify the port number of the proxy server. This item can be specified with the range of 0 to 65535. (Example) 3128	N/A
10	Authentication ID of the proxy	proxyId	Specify the Authentication ID of the proxy server. (Example) user	N/A
11	Authentication password of the proxy	proxyPassword	Specify the Authentication password of the proxy server. (Example) password	N/A

#1

One-byte alphabet and numbers can be used. The number of letters must meet the requirements of authentication rules. The following symbols can also be used.

!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

#2

The digest is the format which Data Highway - Server stores the password in the database. It is impossible to restore an actual password character string from this value. The password information is outputted with the digest format on Password in the export CSV.

Specify the value in accordance with the input rule of XML. Especially, be careful when you specify the special symbol in XML. When you specify the following character, replace it to the entity reference (escape character) or use the CDATA section.

Table 7‒11: Escape character of XML
No	Character	Notation by the entity refernce
1	`<`	`<`
`2`	`>`	`>`
`3`	`&`	`&`
`4`	`"`	`"`
`5`	`'`	`'`

In addition, control characters such as the newline may be shown with the entity according to the standard of XML. The order of the appearance of XML's attribute does not have sequentiality according to the protocol of XML.

Example for setting is as follows.

<?xml version="1.0" encoding="utf-8" ?>
<property>
    <serverUrl>https://jp1dh-hitachi.co.jp/</serverUrl>
    <userId>user@company</userId>
    <password>password</password>
    <authenticationMethod>CERTIFICATION</authenticationMethod>
    <certificatePath>C:/hitachi/hitachi01.dat</certificatePath>
    <certificatePassword>hitachi01</certificatePassword>
    <useProxy>true</useProxy>
    <proxyHost>proxyserver</proxyHost>
    <proxyPort>8080</proxyPort>
    <proxyId>proxyid</proxyId>
    <proxyPassword>proxypassword</proxyPassword>
</property>

(b) The Received List File

The received list is described in this file. Specify this file's path as an argument when you execute the data transfer command. The delivery which are described in this file are treated as being received, and they are not received after that.

Do not modify this file because it is updated automatically when the command receive the data. And, it is necessary to prepare another file for every user of Data Highway - Server.

To Page Top

(7) Operation at the time of the data transfer failure

When a certain error occurs during execution of the data transfer command and the command fails, the data transfer is cancelled including the following processing. The retry is not executed automatically. Send or receive the data again.

To Page Top

(8) The execution at the same time on the same PC

The data transfer command cannot be executed at the same time on the same PC. When the command is executed at the same time on the same PC, it becomes in a suspended state while the timeout which is specified as options is passed. However, even if it is the case on the same PC, when OS account which executes the data transfer command is divided, it can be executed at the same time according to the number of the execution account.

To Page Top