White Paper. ReadBlock/WriteBlock vs. ReadBytes/WritesBytes. Last revised: August 10, 2017

Transcription

1 White Paper ReadBlock/WriteBlock vs. ReadBytes/WritesBytes Last revised: August 10, 2017 Licensed Materials - Property of IBM IBM Sterling Gentran:Server for Microsoft Windows Copyright IBM Corp. 1990, All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Page 1 of 6

2 TABLE OF CONTENTS OVERVIEW... 3 READBLOCK... 3 WRITEBLOCK... 3 Example of ReadBlock and WriteBlock... 4 Explanation... 4 READBYTES... 5 WRITEBYTES... 5 Example of ReadBytes and WriteBytes... 6 Explanation... 6 USING READBYTES / WRITEBYTES WITH XML DATA... 6 Page 2 of 6

3 Overview This document will discuss the differences between the Extended Rule functions ReadBlock / WriteBlock and ReadBytes / WriteBytes. ReadBlock The ReadBlock function reads a block of data (segment or record), up to but not including the Segment terminator, from the input file and places it into the argument of a string variable. The ReadBlock and WriteBlock functions are used in conjunction with each other to pass a block of data from the input file to the output file without compliance checking or testing for proper syntax. Together these functions provide a more efficient alternative of using wildcard segments, which are typically implemented in build and break maps and are not permitted with XML File Formats. For positional and delimited data a block of data is the entire segment up to but not including the segment terminator. For XML, each of the following is recognized as separate blocks of data: 1) Element start tag including any attributes 2) PCDATA 3) Element end tag ReadBlock(string_variable); WriteBlock The WriteBlock function writes the data contained in the argument of a string variable to the output file. The ReadBlock and WriteBlock functions are used in conjunction with each other to pass a block of data from the input file to the output file without compliance checking or testing for proper syntax. WriteBlock(string_variable); Page 3 of 6

4 Example of ReadBlock and WriteBlock String [1024] temp_buffer; temp_buffer = ; Position = ftell(0); While readblock(temp_buffer) do Begin If left(temp_buffer,3) = "IEA" then Begin Fseek(0,Position,begin); Break; End Writeblock(temp_buffer); Position = ftell(0); End Explanation 1. Declare and Initialize temp_buffer variable. 2. The Ftell (File Tell) function is performed to get the current file pointer position. 3. The ReadBlock function is then reading the current segment from input file and placing it into the string variable temp_buffer. 4. The If statement will check the first 3 characters of the value contained in the variable temp_buffer to see if they are equal to IEA. a. If the value does equal IEA : i. The rule will perform an Fseek (File Seek) function to assign the file pointer back to the position before the current segment. ii. Then the Break function is performed to break out of the While Loop. b. If the value does not equal IEA : i. The rule will not process the If statement, and will process the WriteBlock function to write the current value in the temp_buffer variable to the output file. ii. The rule then stores the current file pointer position. Page 4 of 6

5 ReadBytes The ReadBytes function reads a number of bytes from the input file. This function is used in conjunction with the WriteBytes function. Used together, the ReadBytes and writebytes function provide an efficient method of passing data through a map if the data does not need to be compliance checked or altered in any way. ReadBytes is similar to the ReadBlock function, but the ReadBlock function only works with entire blocks (i.e., an entire segment or record), and the ReadBytes function works with any quantity of data, whether it is smaller or larger than a block. The ReadBytes function uses two parameters: 1. The string variable into which the data being read will be stored 2. The number of bytes to read. readbytes(string_variable, num_bytes); where: string_variable = variable into which the data being read will be stored num_bytes = integer value representing the number of bytes to read from the input file. Note: Readbytes returns the number of bytes it was actually able to read. WriteBytes The WriteBytes function writes a specified number of bytes to the output file. This function is used in conjunction with the ReadBytes function. Used together, the ReadBytes and WriteBytes function provide an efficient method of passing data through a map if the data does not need to be compliance checked or altered in any way. Note: The translator does not append a segment terminator to the end of the string value written to the output file. WriteBytes is similar to the WriteBlock function, but the WriteBlock function only works with entire blocks (i.e., an entire segment or record), and the WriteBytes function works with any quantity of data, whether it is smaller or larger than a block. The WriteBytes function uses two parameters, first the string variable containing the data to be written to the output file, and second the number of bytes to write. readbytes(string_variable, num_bytes); Where: string_variable = string variable containing the data to be written to the output file num_bytes = integer value representing the number of bytes to read from the write_to_buffer variable and write to the output file Page 5 of 6

6 Example of ReadBytes and WriteBytes String [1024] temp_buffer; temp_buffer = ; While readbytes(temp_buffer,1024) do Begin writebytes(temp_buffer,1024); End Explanation 1. Declare and initialize the temp_buffer variable. 2. The ReadBytes Function will read 1024 bytes from the Input file and store them in the string variable temp_buffer. If the End of File (EOF) is reached before reading 1024 bytes, then everything up to EOF is read into the variable. 3. The WriteBytes Function writes 1024 bytes from the temp_buffer variable to the output file. 4. This rule will be executed until EOF is reached. Using ReadBytes / WriteBytes with XML data Using ReadBytes / WriteBytes on XML data in some cases is better than using ReadBlock / WriteBlock. This is because ReadBlock / WriteBlock reads entire blocks of data where ReadBytes / WriteBytes reads a specified number bytes even if that amount is larger or smaller than a block of data. XML data is in internally converted to Unicode characters before processed. This doubles the size that the string variable needs to be if the ReadBlock / WriteBlock functions are used. If the string variable is not large enough to hold the entire string that has been converted to Unicode, the trailing data is lost. This is where using ReadBytes / WriteBytes is important. In the scenario where you are dealing with larges blocks of data that will vary in size from file to file, it is better to use ReadBytes/WriteBytes to ensure that you will get all the data in a block. Note: Please see the Alphabetical Language Reference section in the ApplIntUsersGuide.pdf or the On-Line Help for Application Integration for more information on using ReadBlock/WriteBlock and ReadBytes/WriteBytes. Page 6 of 6