MapForce provides the ability to read BLOB (binary large object) data from binary files into a mapping, and then consume it without changing the internal structure of the binary data (raw). For example, you can save binary data to a database BLOB field, to a field of type xs:base64Binary in an XML file, or send it to a Web service*.
* Web service calls are supported in MapForce Enterprise Edition only.
You can also create mappings that read binary data from some source (such as a BLOB field in a database, a field of type xs:base64Binary in an XML file, or a Web service) and then write binary files to the disk.
The following are just some example scenarios that benefit from the ability to read or write binary files:
•Extract binary content encoded as base-64 data from an XML file and save it to the disk (for example, as a PDF file)
•Process image files stored on the disk and send them as base-64 encoded binary content to a Web service
•Extract BLOB content from a database table and save it as image files to the disk (one image file for each row in the database table)
•Read image files from the disk and save them to a database table as BLOB data fields.
|Note:||Mapping data to or from binary files requires BUILT-IN as a transformation language. You can preview the mapping in MapForce (and save the output files, if any) or choose to execute it with MapForce Server (licensed separately) on a different computer or platform. It is not supported to generate an executable C#, C++, or Java program from mappings that read or write binary files.|
Adding binary files to the mapping
As such, there is no component kind associated with binary files in MapForce, like it is the case, for example, with XML, text, or JSON files. Instead, to help you accomplish goals such as the ones above, the following MapForce built-in functions are available:
You can find these functions in the Libraries window (more specifically, in the "lang" library). To use either of the functions in a mapping, drag them from the Libraries window into the mapping, or double-click inside an empty area of the mapping and start typing the function name to select it. For further information, see Adding Functions to the Mapping.
This function returns the content of the specified file as a BLOB (binary large object) of type xs:base64Binary. Note that even though the data type is called "base64Binary", the internal representation is just a BLOB. Only when you map the function's result to an XML node of type xs:base64Binary will it actually be base64-encoded. You could also map the function's result to xs:hexBinary, to a database blob, or to a binary field in a Protocol Buffers structure.
To read a binary file into a mapping, supply its path as input to the filepath argument. If the filepath is relative, then MapForce will look for the file in the same directory as the mapping. The must-exist argument is optional; if the file cannot be opened and this parameter is true, the mapping throws an error. If the file cannot be opened and this parameter is false, an empty binary is returned.
This function writes binary content to the specified file path and returns the path of the written file. If a binary file is the only desired output, connect the function's result to a simple output component. Because this function writes a file whenever its output is used in the mapping, it is recommended to connect the function's result directly to a target component, without using other processing in between.
To write binary files, supply their path as input to the filepath argument. If filepath is relative, then MapForce will generate the file in the same directory as the mapping. The content argument must be connected to the actual binary content (for example, a BLOB field in a database).
When you preview the mapping in MapForce, the function generates temporary files by default, instead of writing files directly to the disk. To save the temporary files to disk, first click the Output tab, and then click the Save generated output or Save all generated outputs toolbar button, as applicable.
To configure MapForce to write output directly to final files instead of temporary, select the Tools | Options menu command, click General, and then select the Write directly to final output files option. Be aware that this option overwrites any existing files with the same name.
The function always returns the final (not temporary) file name, even when the final file is not saved to the disk yet (that is the case when you preview the mapping and the Write directly to final output files option is disabled).
Note that it is not supported for a mapping to read back its own output file.