Contents of the message format to be created in file adapters are described here.

(a) Request message format of file adapters

Send the following information in the request message used for requesting execution of file operations:

• File operation information
• Data for writing a file

Information of file operations

File operation information is required to access a file. The following table describes the contents of file operation information:

Table 3-14 File operation information

Information	Description
File name	Specifies the name of the file that is to be read or written. Specify the file name in the absolute path. Length of the file name can be within the range of 1 to 200 bytes when it is converted to UTF-8. Spaces present before and after the file name are deleted. For Windows, the path is case-insensitive. You cannot specify a file in the following manner: A file name containing relative path, expression of a parent directory ("..\", "../"), and current directory expression (".\", "./"). For UNIX, file name containing symbolic link. For Windows, a file name containing the UNC format, stream name of NTFS or reserved device name.
Reading mode	Specifies the mode for reading a file. The mode name is as follows: Batch Spaces present before and after the specified value are deleted.
Writing mode	Specifies the mode for writing a file. Mode names are as follows: New Add Spaces present before and after the specified value are deleted.

Data for writing a file

Specifies the user data to be specified in a request message, when sending a writing request for an XML file or a binary file.

The contents of a request message differ as per the format or type of the file to be read or written. Therefore, describe only the required information in a message from the file operation information and data for writing a file at the time of message creation.

The following table describes the information required for a request message, when reading an XML file:

Table 3-15 Information of a request message when reading an XML file (XML message)

Information	Tag name within a message	Specified value	Default value at the time of omission	Specification
Root element	ReadRequest	-	-	Y
File header element	fileheader	-	-	Y
File name element	filename	File name	-	Y
File mode element	filemode	all	all	N

Legend:

Y: Must be specified.

N: Can be omitted.

-: Not applicable.

The following table describes the information required for a request message, when writing an XML file:

Table 3-16 Information of a request message when writing an XML file (XML message)

Information	Tag name within a message	Specified value	Default value at the time of omission	Specification
Root element	WriteRequest	-	-	Y
File header element	fileheader	-	-	Y
File name element	filename	File name	-	N
File mode element	filemode	new	new	N
Data for writing a file	userdata	Optional to user	-	Y

Legend:

Y: Must be specified.

N: Can be omitted.

-: Not applicable.

The following table describes the information required for a request message, when reading a binary file:

Table 3-17 Information of a request message when reading a binary file (XML message)

Information	Tag name within a message	Specified value	Default value at the time of omission	Specification
Root element	ReadRequest	-	-	Y
File header element	fileheader	-	-	Y
File name element	filename	File name	-	Y
File mode element	filemode	all	all	N

Legend:

Y: Must be specified.

N: Can be omitted.

-: Not applicable.

When writing a binary file, the request message will have binary format. The following figure shows the structure of a request message in binary format:

Figure 3-6 Structure of a request message in binary format

The overall length of a message must consist of the following relational expression:

 
Overall length >= 10 + L1 + 10 + L2
 

The following table describes the information required for a request message, when writing a binary file:

Table 3-18 Information of a request message when writing a binary file (binary message)

Information	Specified value	Default value at the time of omission	Specification
Length of a file name	Specify byte length of a file name with decimal numeric string.	-	Y
File name	File name	-	Y
Length of a file option	Specify byte length of a file option with decimal numeric string.	-	Y
File option	New writing: mode=new Additional writing: mode=append	mode=new	N
User data	Optional to user	-	Y#

Legend:

Y: Must be specified.

N: Can be omitted.

-: Not applicable.

Note#

You can specify 0 byte.

For details on the sample of each request message, see (f) Message examples.

(b) Response message format of file adapters

Send the following information in the response message that returns the information on reading a file adapter to the invoker of a file adapter:

• Data for reading a file
• File writing process result

Data for reading a file

Specifies the user data to be stored and to be returned to a response message, when reading an XML file or a binary file.

Result of file writing process

The result of writing process is stored in a response message, when writing an XML file or a binary file. If the writing process fails, the file adapter notifies an exception to HCSC server and does not return a response message. The result of writing process is stored to a response message only when the writing process ends successfully. Therefore, return value of the response message must be "OK" at the time of writing.

The contents of a response message differ as per the format and type of the file to be read or written. The following table describes the information of a response message that is returned when a file is to be read and written:

Table 3-19 Information of response message

File format and type	Information	Tag name within a message	Return value
Reading an XML file	Data for reading a file	Optional to user	Optional to user
Writing an XML file	Result of file writing process	status	OK
Reading a binary file	Data for reading a file	-	Optional to user
Writing a binary file	Result of file writing process	status	OK

Legend:

-: Not applicable.

(c) Types of a message format

If message formats of a file adapter invoker (standard message) and a file adapter (service component message) are different, create message format definition files of a file adapter invoker (standard message) and a file adapter (service component message). Map the respective message formats from the data transformation (mapping) definition screen.

The following table describes the message format definition file to be created when performing data transformation:

Table 3-20 Message format definition file to be created

File format and type	Request message		Response message
	Standard message (invoker)	Service component message (file adapter)	Standard message (invoker)	Service component message (file adapter)
Reading an XML file	XML#	XML	XML#	XML
Writing an XML file	XML#	XML	XML#	XML
Reading a binary file	XML#	XML	XML	Binary
Writing a binary file	XML	Binary	XML#	XML

Legend:

XML: XML format definition file

Binary: Binary format definition file

Note#

When the message format of file adapter invoker (standard message) and file adapter (service component message) is same, you need not create and set the message format definition file of the file adapter invoker (standard message).

The message format definition file to be created differs depending on whether to handle data in XML format or in binary format (other than XML format) in a message to be used in a file adapter.

• When handling data in XML format
  When handling data in XML format, create an XML format definition file. Create the XML format definition file as XML schema file (extension: .xsd). For details on how to create XML format definition file, see (d) Creating an XML format definition file.
  
• When handling data in binary format
  When handling data in binary format (other than XML format), create a binary format definition file. The binary format definition file is created, when you define the storage format of a value within the data in binary format (such as length of a value, its relation with another value) and add the defined information in XML schema file (extension: .fdx). The binary format definition file is created as per XML specifications. Hence you can use this file as the transformation source and destination, when defining data transformation in same way as the XML format definition file. For details on how to create a binary format definition file, see (e) Creating a binary format definition file.
  

(d) Creating an XML format definition file

Method of creating a standard message and file adapter (service component message) is as follows:

Creating an XML format definition file of a standard message

Create an XML format definition file of a standard message using WST (Web Standard Tools) provided by Eclipse.

The XML format definition file to be created must comply with the scoping of the XML schema that can be used on the HCSC server. For details on the conditions, see 2.6.5 Scoping of XML schema in the manual Service Platform Basic Development Guide.

If an error occurs, when you select the message format file to be used for defining a file adapter and a business process (error message having message ID starting with KECX), an error exists in XML schema file. Here, see the message 11.KECX (message output by XML Processor) in the manual Application Server Messages, and take actions.

Creating an XML format definition file of file adapter (service component message)

The following table describes the definition file used by a user and the need for editing this file, when creating the XML format definition file of a file adapter (service component message):

Table 3-21 Definition file used by the user and the need for editing this file

File operation mode	Message type	Definition file that is used	Editing by user
Reading	Request message	adpff_read.xsd	N
	Response message	Created by user	Y
Writing	Request message	adpff_header.xsd	N
		adpff_write.xsd	Y
	Response message	adpff_result.xsd	N

Legend:

Y: Must be edited.

N: Need not be edited.

The method of creating the XML format definition file is described here for each file operation mode:

For reading

When reading an XML file using a file adapter, create the following message format definition file:

• Request message: XML format definition file
• Response message: XML format definition file
  

  Figure 3-7 Message flow at the time of reading an XML file

  

• Request message
  For the XML format definition file for a request message, use the following files:
  Format definition file for a request message (for reading XML and binary format)
  Installation directory of the service platform\CSC\custom-adapter\File\schema\adpff_read.xsd
  
• Response message
  The user creates the XML format definition file for the response message on his own.
  

For writing

When writing an XML file using a file adapter, create the following message format definition file:

• Request message: XML format definition file
• Response message: XML format definition file
  

  Figure 3-8 Message flow at the time of writing an XML file

  

• Request message
  Use the following file and the template file to create the XML format definition file for a request message:
  File operation information file for a request message (for XML format writing)
  Installation directory of the service platform\CSC\custom-adapter\File\schema\adpff_header.xsd
  Format definition template file for a request message (for XML format writing)
  Installation directory of the service platform\CSC\custom-adapter\File\schema\templates\adpff_write.xsd
  The user must edit the format definition template file for a request message. The following figure shows the locations to be edited in the format definition template file for a request message:
  

  Figure 3-9 Format definition template file for a request message

  

The following table describes the format definition template file for a request message according to the line number given in the figure. Note that line numbers given in the figure are not included in the actual template.

Table 3-22 Description of the format definition template file for a request message

Line number	Description
4th line	Specifies name space declaration of the file operation information file (for XML format writing: adpff_header.xsd) for a request message.
5th line	Specifies name space declaration of this template file. The user declares any prefix in the value of targetName space attribute specified in the 7th line.
6th line	When importing another schema file, specify name space declaration of that schema.#1, #2
7th line	Specifies the target name space of this template file. The user specifies a unique target name space in the value of targetName space attribute.
9th ~10th line	Specifies import declaration of the file operation information file for a request message (for XML format writing: adpff_header.xsd). For this template file, import the file operation information file for a request message (for XML format writing). The user modifies the value of schemaLocation attribute in the relative path on which the file operation information file for a request message exists (for XML format writing). Same directory is mentioned by default.
14th~20th line	Specifies WriteRequest element declaration. It is the root element of a request message. For a file adapter, acquire this element name and determine file I/O type (WriteRequest: Writing, ReadRequest: Reading). Wait for fileheader element and userdata element. The user specifies the prefix declared in the 5th line as a prefix of userdata element.
22nd line	Specifies userdata element declaration.
23rd line	Specifies the XML schema information used for user data.#1, #2

Note#1

There are 2 types of specification methods. One is to specify directly in this file. Another is to create a file separately to specify the XML schema information used for user data and import it from this file. When importing, specify the target name space of the schema to be imported in the 6th line and import statement of the schema to be imported in 12th line. For details on the specification example, see (f) Message examples.

Note#2

When specifying the XML schema information used for user data, you cannot declare multiple elements in the child element of the userdata element. Declare only 1 child element of userdata element, since it becomes the root element when writing an XML file.

• Response message
  Use the following file for the XML format definition file for a response message:
  Format definition file for a response message (for XML and binary format writing)
  Installation directory of the service platform\CSC\custom-adapter\File\schema\adpff_result.xsd
  

(e) Creating a binary format definition file

The method to create a binary format definition file is described here.

The following table describes the definition file used by the user and the need for editing this file, when creating a binary format definition file:

Table 3-23 Definition file used by the user and the need for editing this file

File operation mode	Message type	Definition file that is used	Editing by user
Reading	Request message	adpff_read.xsd	N
	Response message	Created by user	Y
Writing	Request message	adpff_write.fdx	Y
	Response message	adpff_result.xsd	N

Legend:

Y: Must be edited.

N: Need not be edited.

The method to create a binary format definition file is described here.

For reading

When reading a binary file using a file adapter, create the following message format definition file:

• Request message: XML format definition file
• Response message: Binary format definition file
  

  Figure 3-10 Message flow at the time of reading a binary file

  

Request message

For the XML request message format definition file, use the following file:

Format definition file for a request message (for XML and binary format reading)

Installation directory of the service platform\CSC\custom-adapter\File\schema\adpff_read.xsd

Response message

The user creates the binary format definition file for a response message on his own.

For writing

When writing a binary file using a file adapter, create the following message format definition file:

• Request message: Binary format definition file
• Response message: XML format definition file
  

  Figure 3-11 Message flow at the time of writing a binary file

  

Request message

The user creates the binary format definition file for a request message by editing the following template file in the binary format definition screen:

Format definition template file for a request message (for binary format writing)

Installation directory of the service platform\CSC\custom-adapter\File\schema\templates\adpff_write.fdx

The following figure shows the format definition template file for a request message:

Figure 3-12 Format definition template file for a request message screen

The following table describes the setup value of the format definition template file for a request message:

Table 3-24 Setup value of the format definition template file for a request message

Element name	Data type	Size (byte)	Occurrence count	Description
adpff_write	-	-	-	Root element
fileheader	-	-	1 time	File operation information element
filename_length	Integer	10	1 time	File name length element
filename	String	Variable	1 time	File name element
fileoption_length	Integer	10	1 time	File option length element
fileoption	String	Variable	1 time	File option element

Legend:

-: Not applicable.

• Creation method
  The user creates a user data element of any element name as a child element of the root element (adpff_write element). However, the user must create this element such that fileheader element becomes first. Operation is not guaranteed, if the fileheader element is not first. Once the user creates the binary format definition file, he saves it with any name, and specifies it in the service adapter settings screen. The following figure shows the sample screen of the binary format definition file after it is created. The user declares a customer element as the user-data element in the sample screen and creates the name element and the address element as its child element.
  

  Figure 3-13 Sample screen after the binary format definition file is created

  

Response message

For the XML format definition file for a response message, use the following file:

Format definition file for a response message (for XML and binary format writing)

Installation directory of the service platform\CSC\custom-adapter\File\schema\adpff_result.xsd

(f) Message examples

Examples of a request message when performing each file operation are as follows:

To describe message examples, the following table lists the format definition files for a request message used for defining the request message format:

Table 3-25 Format definition file list for a request message that is provided

File name	Contents	Editing
adpff_read.xsd	Format definition file for a request message (for XML and binary format reading)	N
adpff_write.xsd	Format definition template file for a request message (for XML format writing)	Y
adpff_write.fdx	Format definition template file for a request message (for binary format writing)	Y

Legend:

Y: This file is to be used after editing it.

N: This file is to be used without editing it.

Request message at the time of reading a file

Use the request message format definition file (for XML and binary format reading) for a request message format at the time of reading a file. Use the contents of the request message format definition file as are without changing them.

An example of describing a request message at the time of reading a file is described here.

 
<?xml version="1.0" encoding="UTF-8"?>
<adpff:ReadRequest xmlns:adpff="http://FlatFiles.cstmadp.csc.soft.Hitachi.co.jp/ReadRequest">
  <fileheader>
    <filename>C:\WORK\ReadFile.xml</filename>
    <filemode>all</filemode>
  </fileheader>
</adpff:ReadRequest>
 

Request message at the time of writing a file (XML format)

Use the format definition template file (for XML format writing) for the request message format at the time of writing a file in XML format. Append the XML schema information of user data to the request message format definition file and create the request message format definition file.

Following are the 2 methods for appending the XML schema information of user data:

• Specify the XML schema information directly in the request message format definition file
• Import the XML schema information in the request message format definition file

When specifying XML schema information of user data directly

An example of specifying the XML schema information for the user data directly in the request message format definition file is as follows:

 
<?xml version="1.0" encoding="UTF-8"?>
<!-- All Rights Reserved. Copyright (C) 2007, Hitachi, Ltd. -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:adpff="http://FlatFiles.cstmadp.csc.soft.Hitachi.co.jp/WriteRequest"
            xmlns:wr="http://WriteRequest"
            targetName space="http://WriteRequest">
  <xsd:import name space="http://FlatFiles.cstmadp.csc.soft.Hitachi.co.jp/WriteRequest"
              schemaLocation="adpff_header.xsd"/>
  <xsd:element name="WriteRequest" type="wr:format"/>
 
  <xsd:complexType name="format">
    <xsd:sequence>
      <xsd:element name="fileheader" type="adpff:fileheader"/>
      <xsd:element name="userdata" type="wr:userdata"/>
    </xsd:sequence>
  </xsd:complexType>
 
  <xsd:complexType name="userdata">
    <xsd:sequence>
      <xsd:element name="customer" type="wr:customer"/>
    </xsd:sequence>
  </xsd:complexType>
 
  <xsd:complexType name="customer">
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string" />
      <xsd:element name="address" type="xsd:string" />
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>
 
 
An example of describing a request message that complies with above-mentioned XML schema is as follows:
 
<?xml version="1.0" encoding="UTF-8"?>
<wr:WriteRequest xmlns:wr="http://WriteRequest">
  <fileheader>
    <filename>C:\WORK\writeXML.xml</filename>
    <filemode>new</filemode>
  </fileheader>
  <userdata>
    <customer>
      <name>Hitachi Taro</name>
      <address>Yokohama Totsuka</address>
    </customer>
  </userdata>
</wr:WriteRequest>
 

Importing the XML schema information of the user data

An example of importing the XML schema information of the user data in the request message format definition file and specifying that information is as follows:

 
<?xml version="1.0" encoding="UTF-8"?>
<!-- All Rights Reserved. Copyright (C) 2007, Hitachi, Ltd. -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:adpff="http://FlatFiles.cstmadp.csc.soft.Hitachi.co.jp/WriteRequest"
            xmlns:wr="http://WriteRequest"
            targetName space="http://WriteRequest"
            xmlns:usr="http://UserSchema">
 
  <xsd:import name space="http://FlatFiles.cstmadp.csc.soft.Hitachi.co.jp/WriteRequest"
              schemaLocation="adpff_header.xsd"/>
 
  <xsd:import name space="http://UserSchema" schemaLocation="User.xsd"/>
 
  <xsd:element name="WriteRequest" type="wr:format"/>
  <xsd:complexType name="format">
    <xsd:sequence>
      <xsd:element name="fileheader" type="adpff:fileheader"/>
      <xsd:element name="userdata" type="wr:userdata"/>
    </xsd:sequence>
  </xsd:complexType>
 
  <xsd:complexType name="userdata">
    <xsd:sequence>
      <xsd:element ref="usr:customer"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>
 
The contents of the imported User.xsd are as follows:
 
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:usr="http://UserSchema"
            targetName space="http://UserSchema">
  <xsd:element name="customer">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="name" type="xsd:string"/>
        <xsd:element name="address" type="xsd:string"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>
 
An example of specifying a request message that complies with the above-mentioned XML schema is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<wr:WriteRequest xmlns:wr="http://WriteRequest">
  <fileheader>
    <filename>C:\WORK\writeXML.xml</filename>
    <filemode>new</filemode>
  </fileheader>
  <userdata>
    <usr:customer xmlns:usr="http://UserSchema">
      <name>Hitachi Tarou</name>
      <address>Yokohama Totsuka</address>
    </usr:customer>
  </userdata>
</wr:WriteRequest>
 

Request message at the time of writing a file (binary format)

Use the format definition template file for a request message (for writing in binary format ) in the request message format at the time of writing a file in binary format. Import the request message format definition file in the project for creating the binary format definition file of Eclipse and add the definition for the user data.

A request message is handled in the XML format on a business process. Hence convert this message into a request message in binary format of a file adapter by transforming the file from the XML format to binary format using data transformation functionality.

An example of defining the request message format definition file and an example of defining data transformation of a request message are as follows:

If you import the request message format definition file that is provided, the definition of file operation information of a file adapter is displayed.

Figure 3-14 Definition screen in which the provided file is imported

Add the definition of the user data in this definition screen. Elements of name and address are defined as customer data in the following example:

Figure 3-15 Definition screen in which definition of the user data is added

Transform the data from the calling request message format of a file adapter into the binary format definition file that is created. Data length of filename and fileoption elements is automatically set in filename_length and fileoption_length elements using the data transformation function.

Figure 3-16 Data transformation definition screen

Set the message format definition file of transformation source and the message format definition file of transformation destination on the data transformation (mapping) definition screen and define the transformation.

For details on how to define data transformation, see 6. Defining Data Transformation in the manual Service Platform Basic Development Guide.

The procedure for defining a file adapter is as follows:

1. Display service adapter settings screen.
   For details on how to display the service adapter settings screen, see 3.3.1(4) Displaying the service adapter settings screen.
   
2. Edit [Service name] and [Service ID] of the service component control information, if necessary.
3. Click the [Add] button of the service component control information and specify the definition pattern and the operation name.
4. Select [Synchronous] from the drop-down list of [Communication model] of the operation information.
5. Perform steps from 6. to 17. for a request message.
6. Perform the following operation:
   

   When you specify a standard message format

   Perform steps from 7. to 10. and proceed to step 11.

   When you do not specify a standard message format

   Proceed to step 11.

7. Check the [Use] check box of a standard message.
8. Specify [Format ID] of a standard message.
9. Click the [Browse] button of a standard message and specify a standard message format in [Message format].
   For details on the message format that can be specified, see 2.6.5 Scoping of XML schema in the manual Service Platform Basic Development Guide.
   
10. Click the [Display] button of a standard message.
    If the message format is XML, a standard message format is displayed. Confirm the specified standard message format, if necessary.
    
11. Specify [Format ID] of service component message.
12. Confirm that the following message format is set as per the definition pattern specified in step. 3.
    

    If the definition pattern is "XML reading" or "Binary reading"

    Service component of request message: adpff_read.xsd

    Service component of response message: None

    If the definition pattern is "XML writing" or "Binary writing"

    Service component of request message: None

    Service component of response message: adpff_result.xsd

13. Click the [Display] button of service component message.
    If the message format is XML, the service component message format is displayed. Confirm the specified service component message format, if necessary.
    
14. Perform the following operation:
    

    If you check the [Use] check box of a standard message

    Perform steps from 15. to 17. And proceed to step 18.

    If you do not check the [Use] check box of a standard message

    Proceed to step 18.

15. Enter the file name of the data transformation definition.
16. Click the [Edit] button.
    The data transformation definition screen is displayed. When defining for the first time, the [Select root element] dialog box is displayed.
    
17. Map the contents of a standard message with that of a service message.
18. Perform steps from 6. to 17. even for a response message.
19. Click the service adapter definition (details) tab.
    The service adapter settings screen (details) is displayed.
    
20. Confirm the name of the service adapter (EJB-JAR file).
21. Confirm that the following utility class is added to the utility class (JAR file):
    
    • adpffpc.jar (Protocol converter archive file)
22. Confirm the definition contents, select [File] - [Save] from Eclipse menu and save the definition contents.

Create the file adapter execution environment property file using a sample file. Storage location of the sample file is as follows:

 
Installation directory of the service platform\CSC\custom-adapter\File\config\templates\adpff_exe.properties
 

The procedure for creating the file adapter execution environment property file is as follows:

1. Copy the sample file and store it in the following directory:
   

    
   Installation directory of the service platform\CSC\custom-adapter\File\config
    

2. Change the name of the sample file to <Service ID>.properties.
3. Edit and save the definition contents.

The file adapter execution environment property file is reflected in the execution environment, when you start a file adapter. When changing the contents of the file adapter execution environment property file, stop the file adapter, and then perform the operation. If you restart the file adapter, the changed contents are reflected in the execution environment.

For details on the file adapter execution environment property file, see File adapter execution environment property file in the manual Service Platform Reference Guide.