9.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
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". DWClient.bat Command type { -Option A | Value a { Value b { Value c...}}}…(i) { -Option B | Value a { Value b { Value c...}}}…(i)
Call (i) "Option", and call "Argument" summarizes the (i).
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.
(2) Common options
Common options of the data transfer command is as follows.
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 9.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. |
(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.
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. |
(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.
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.
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.
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.
installation-folder\log\dwc-yyyyMMddhhmmss-GUID.log
(Explanatory notes)
-
installation-folder: 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
- Important
-
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 Version Log level Message ID Message text
The example output of the application log is as follows.
2011/04/19T20:38:21.500 02-03 INFO DWCO1001_I Command start. 2011/04/19T20:38:28.250 02-03 INFO DWCO1041_I Sending files completed. 2011/04/19T20:38:28.250 02-03 INFO DWCO1002_I Command finished.
The output contents of the application log are as follows. For concrete messages, refer to 9.4.2 Messages of the data transfer command.
No |
Items |
Figures |
Output contents |
---|---|---|---|
1 |
Date |
10 |
yyyy/MM/dd
|
2 |
Delimiter |
1 |
T |
3 |
Time |
12 |
HH:mm:ss.SSS
In addition, the output time is the time of client. |
4 |
Version |
8 |
01-09 Left-justification, and right-hand side is filled up with space. |
5 |
Log level |
5 |
Log level. This is left-justification. For more information, refer to 9.3.1(4) (a) Log level. |
6 |
Message ID |
10 |
ID to specify the messages. XXXXYYYY_Z
|
7 |
Message text |
Variable length |
The contents of message Newline may be included when it includes the stack trace information on Java. |
(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.
(6) Configuration files
The explanation about the configuration files is as follows.
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.
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> <errorNotice>value</errorNotice> <errorMailSubject><![CDATA[value]]></errorMailSubject> <errorMailMessage><![CDATA[value]]></errorMailMessage> <notificationToCompanion>value</notificationToCompanion> </property>
Each setting item is as follows.
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 |
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.
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 |
12 |
Need of command-error email notifications |
errorNotice |
Specify whether to send an email notification of an error when it occurs during command execution. To enable notifications: true To disable notifications: false This item is not case-sensitive. If you specify a value other than specifiable values, an error occurs. If the item itself is omitted, it is set to false. If more than one tag is present, the value in the last tag will be effective. (Example) true |
false |
13 |
Message subject of command-error email notifications |
errorMailSubject |
Specify the message subject of command-error email notifications with no more than 128 characters. If you specify a value for this item, the subject of notifications is created with a product name added to the specified subject value. If this tag is omitted, the system's default message subject is used to send error notification messages. You can use characters that are available for message subjects in general. Note that if the subject contains any &, <, or > characters, you must enter them in the form of XML escape characters, as listed in Table 9-10. If you specify a value other than specifiable values, an error occurs. If more than one tag is present, the value in the last tag will be effective. |
N/A |
14 |
Message body of command-error email notifications#3 |
errorMailMessage |
Specify the message body of command-error email notifications with no more than 512 characters. If this tag is omitted, the system sends error notification messages with no body text. You can use characters that are available for the message body in general. Note that if the message body contains any &, <, or > characters, you must enter them in the form of XML escape characters, as listed in Table 9-10. If you specify a value other than specifiable values, an error occurs. If more than one tag is present, the value in the last tag will be effective. |
N/A |
15 |
Need of error notification messages to senders or recipients of delivery |
notificationToCompanion |
Specify whether to send error notification messages upon command execution to recipient users of delivery for sending errors, or to sender users for reception errors. Note that this tag is not for data transfer management commands.
This item is not case-sensitive. If you specify a value other than specifiable values, an error occurs. If the item itself is omitted, it is set to false. If more than one tag is present, the value in the last tag will be effective. (Example) true |
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.
- #3
-
An error notification message looks like as follows:
JP1/DH - Server -------------------------------------------------------------------- Command error notification -------------------------------------------------------------------- A command error occurred. Executed by: name-of-the-user-who-executed-the-command (email-address-of-this-user) Command type: type-of-the-command message-body-specified-by-the-user Note: This is an auto-generated message. Please do not reply to this message. JP1/DH - Server
Most portions of the notification, except for the message body specified by the user, are based on the language set for the user who executed command (in Japanese, English, or Chinese).
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. In addition, save the command property file in UTF-8 encoding. If the file is encoded in a different character set, the system may fail to read it.
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> <errorNotice>true</errorNotice> <errorMailSubject><![CDATA[Error notification]]></errorMailSubject> <errorMailMessage><![CDATA[Check the command that caused the error.]]></errorMailMessage> <notificationToCompanion>true</notificationToCompanion> <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.
(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.
If you specified the -resumestatus option to transfer or receive the data, you can resume the transferring or reception by using the RESUME command. For details, see 9.3.2 (3) Resumption of the file transfer which is under suspending.
(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.
However, even on the same computer, if you use a separate Windows account to execute an administrator command, you can simultaneously execute an equal number of commands as the number of such accounts.
In addition, when multiple commands were in the standby state, the order of execution might be different from the order of activation. For example, if command B and command C go into the standby state while command A is being executed, the command to be executed after command A ends is either command B or command C.
The administrator command can be executed at the same time on the same PC. The administrator command and data transfer command can be executed at the same time on the same PC.