convert()

The sysLib.convert() system function converts data between EBCDIC (host) and ASCII (workstation) formats or performs code-page conversion within a single format.

Syntax

  sysLib.convert(
    target ANY inOut,
    [direction ConvertDirection in,
    conversionTable STRING in] )

target

The name of the variable that contains the data to convert. The data is converted in place based on the field definition of the lowest-level fields (fields with no substructure) in the target object.

Variable-length records are converted for the length of the current record only. The length of the current record is calculated using numElementsItem from the record or is set from the lengthItem in the record. If the variable-length record ends in the middle of a numeric field or a DBCS character, a conversion error occurs and the program ends.

direction

The direction of the conversion. If conversionTable is specified, the direction is required, otherwise it is optional. This parameter uses values from the ConvertDirection enumeration:

remote: The default value. The data is assumed to be in remote format and is converted to local format.
local: The data is assumed to be in local format and is converted to remote format (as defined in the conversion table).

conversionTable

A variable or literal that specifies the name of the conversion table for data conversion. The default value is the conversion table that is associated with the national language code in the targetNLS build descriptor option when the program was generated.

Definition considerations

You can use the linkage options part to perform the following actions:

Request that automatic data conversion generate for remote calls.
Start remote asynchronous transactions.
Access remote files.

Automatic conversion is always performed by using the data structure that is defined for the argument that is being converted. If an argument has multiple formats, do not request automatic conversion. Instead, code the program to explicitly call sysLib.convert() with redefined record declarations that correctly map the current values of the argument.

Example

Record OrderRec
   10 record_type char(3);
   10 productName char(20); 
end 

Record NewOrderRec
   10 record_type char(3);
   10 productNumber bigint;
   10 unitCost decimal(7);
   10 skuNum char(8); 
end

Program ProgramX type basicProgram
   myOrderRec OrderRec;
   myNewOrderRec NewOrderRec {redefines = "myOrderRec"};
   myConvTable char(8);
   
   function main();
      myConvTable = "CSOX850"; // conversion table for US English EBCDIC
      if (myOrderRec.record_type == "00A")
         sysLib.convert(myOrderRec, ConvertDirection.local, myConvTable);
      else
         sysLib.convert(myNewOrderRec, ConvertDirection.local, myConvTable);
      end
     call ProgramY myOrderRec;
   end 
end