jis-output-file

function

Library: Character encodings, international (OMEFIO)
Include: omefio.xin

Declaration

define external string sink function jis-output-file
                value string filename
  exceptions-to value io-exception exceptions-to optional

Argument definitions

filename: the name of the JIS encoded file you want to write

exceptions-to: location that errors will be recorded

Purpose

This external function accepts UTF-8 encoded data and writes that data to the file named in the "filename" argument, converting the UTF-8 encoding to a JIS encoding. The program writes out UTF-8, but the file receives JIS.

If a zero-length filename is used (that is, ""), then jis-output-file does not open a file, but writes to standard output. The zero-length file name option allows the conversion functionality to be used in an OmniMark program that is being used as a filter.

There are three types of errors, categorized according to how they are handled:

Whenever an invalid or out-of-range encoding is found, it is converted to the ASCII DEL character (0x7F) on output. If "exceptions-to" is specified, the "io-exception" object is marked for a data encoding error, and the function continues processing.
If the external string sink function cannot be created, either because the declaration does not match what is expected or because there is not enough memory to create the source object, an error is signaled to OmniMark, and your program is terminated.
If "exceptions-to" is specified, then for any other type of error that occurs during memory allocation, file opening or closing, or reading or writing, the "io-exception" object is marked for the error found, and processing continues. If "exceptions-to" is not specified, an error is signaled to OmniMark and your program is terminated.

The file format is produced according to the Japanese Industry Standards JIS X 0201, JIS X 0208, and JIS X 012. The file format uses escape sequences based on ISO 2022 (also known as JIS X 0202) to shift between the encodings defined by the three standards. On output, the escape sequences defined by the latest versions of the standards are used.

Example:

  ; Opening output files to write JIS-encoded files using "New JIS", "Old JIS" and
  ; "New JIS" using the 1990 standard, respectively.
  
  open my-jis-output as jis-output-file "myfile.jis"
  open my-jis-output as jis-output-file "myfile.oj" encoding jisio-old
  open my-jis-output as jis-output-file "myfile.j2" encoding jisio-1990

Related Topics

Other Library Functions