Adding Binary Files to the Mapping
To map data to or from binary files encoded in Protocol Buffers format, you must first add their accompanying .proto file to the MapForce mapping, as shown below.
To add a .proto file as mapping component:
1.On the Insert menu, click Protocol Buffers File. Alternatively, click the Insert Protocol Buffers File toolbar button.
2.Do one of the following:
a.To open a .proto file stored on the local disk, browse for the file, and click Open.
b.To open a .proto file from a URL, click Switch to URL and enter the URL of the file in the dialog box, see Adding Components from a URL.
c.To open a .proto file previously defined as a global resource, click Switch to Global Resource. For information about global resources, see Altova Global Resources.
3.A .proto file typically contains several message types. When prompted, select the message type that is the top object in the hierarchy (the so-called "root").
4.Click OK. A dialog box appears.
5.If you intend to read data from a Protocol Buffers binary file, click Browse and select the binary instance from which you want to read data. If you intend to write data to a Protocol Buffers file, or select an instance at a later time, click Skip.
If the .proto file can be read successfully, MapForce displays its structure on the mapping similar to how it does for other component types, for example:
So far, you have added a binary component to the mapping; however, the mapping is not yet complete, because it does not read or write any data. For examples that illustrate complete mappings, see:
The File/Blob button on the binary component opens a context menu with several commands that are useful in the following situations:
•Use File Names from Component Settings - This is the option selected by default and it is meaningful when your mapping reads or generates a single binary file. When this option is set, you can change the name of the file from the "Component Settings" dialog box, see Binary Component Settings.
•Use Dynamic File Names Supplied by the Mapping - This command is meaningful when your mapping should read or generate multiple binary files. When this option is set, you can no longer change the file name from the "Component Settings" dialog box. Instead, you set the file names based on some information that is coming from the mapping itself. For an example of use, see Example: Write Data to Protocol Buffers.
•Parse Blobs to Protocol Buffers - This command turns the component into a parsing component. This helps you parse a binary value in Protocol Buffers format so that it becomes a mappable tree structure. This works in a similar way to string parsing and serialization (see Parsing and Serializing Strings), only in this case it works not with character strings but with binary byte strings. For example, in the component below, you can connect an item of binary type to the "Blob" input on the left side. At mapping runtime, this binary value will be parsed and it will pass data onto the outputs of the mappable structure on the right side.
•Serialize Protocol Buffers to Blobs - This command turns the component into a serialization component. This helps you serialize a mappable tree structure to a binary value in Protocol buffers format. For example, in the component below, you can connect items of appropriate types to the mappable structure on the left side. At mapping runtime, the structure will be serialized and it will populate the single output (of binary type) on the right side, so that you can connect it further to a target component. This may be useful when your mapping should write data as a BLOB (Binary Large Object) type to some target database. Another use is to write data to binary fields (of type "bytes") of a target Protocol Buffer component.