Writing Your Own Data Conversion Module

If you are writing your own data conversion module, because your require translations not offered by the in-built modules, the module:

• Should have a name no longer than 8 characters.
• be compiled with CHARSET"ASCII".
• is called using the following interface:

  linkage section.                                                  
  01  lk-function          pic x(3). *> PUT or GET         
  01  lk-len               pic 9(5). *> len of lk-data           
  01  lk-data.                       *> data to translate                               
      05  lk-bytes         pic x(1)              
           occurs 32767 times.                
                                                                           
  procedure division using lk-function                              
                           lk-len                                   
                           lk-data.    
  ...

If the purpose of your module is to perform a translation from ASCII to EBCDIC, lk-function should be set to 'PUT', and if it is to perform a translation from EBCDIC to ASCII, lk-function should be set to 'GET'.

On return from your conversion module, lk-len should hold the length of the returned data. For a single-byte character set, these values will be unchanged, but for a double-byte character set, the length may be different. The retuned value is used by MFFTP to write the output record.

Your Micro Focus product already supports many different codesets, but with the Micro Focus development products, you can install additional ones - see The Codecomp Utility in the Codeset Translation section of the development documentation. The module you create for translation in MFFTP will be similar to the module described there using the sample CSnnnn.cbl program provided (described in To Customize Character Set Conversion). One notable difference is that the interface described above should not be compiled as 'NOCANCEL', as it is only being called from MFFTP.

If you find you have a more general need for a specialist codeset conversion module, and you create a CSnnnn program, you can code your MFFTP conversion module to call into that module.

The conversion module is called at least twice by MFFTP for each job step it is used in. The first 2 calls are to check that a 'round trip' translation works.

• The first call is made with a data length (lk-len) of 256 and the data (lk-data) contains hexadecimal values from x'00' through to x'FF', and the function (lk-function) is PUT.
• The second call contains the output from the first call, and the function is GET.

A comparison is then made to see that the return from the GET call is the same as the input to the PUT call. If the module fail this check, a warning message is issued and the module is not used unless the setting MFFTP_TRANSLATE_SAFETY=OFF is set.

The third and subsequent calls to the module is the translation of the data set, record by record.