ssh-translation-table

ssh-translation-table — Secure Shell File Transfer Translation Table

Synopsis

ssh-translation-table [options...]
[filename]

Description

ssh-translation-table (ssh-translation-table.exe on Windows) is a utility program that can be used for generating template translation tables used in file transfer with the scpg3 or sftpg3 file transfer clients. Translation table is stored to filename. If filename is not given, translation table is displayed.

Options

The following options are available:

-b, --binary

Use z/OS-specific binary file format.

-f, --from=CODESET

Specify the codeset of the data in the file when translation is done while reading from the file, or codeset of the data in transfer when translation is done while writing to the file (default: ISO8859-1). For example:

--from ISO8859-1

-t, --to=CODESET

Specify the codeset of the data in transfer when translation is done while reading from the file, or codeset of the data in the file when translation is done while writing to the file (default: IBM-1047,swaplfnl). For example:

--to IBM-1047

-l, --list-charsets

List available character sets. Note that all character sets are not single byte character sets. Only single byte character sets can be used.

-D, --debug=LEVEL

Sets the debug level. LEVEL is a number from 0 to 99, where 99 specifies that all debug information should be displayed. This should be the first argument on the command line.

-h, --help

Displays a short summary of command-line options and exits.

File Transfer Translation Table

File transfer translation table is a simple text file containing two tables describing the character conversion. The first table is used for converting data while writing to the file and the second table is used for converting the data while reading from the file. The table itself is a simple list of 255 values represented as two hexadecimal values (from 00 to FF). The position of the value is the index for conversion. The first position, i.e. position 00, represents the converted value for byte value of 0.

The hexadecimal values in the tables are case-insensitive. So values 0a and 0A are the same. Also, it is possible to add comments into the file. The comment starts with character '#'. Everything after that until end of line is treated as comment and ignored. Also all white spaces are ignored.

	Note
	Only single byte translations are supported with translation tables.

Here is an example translation table generated with command ssh-translation-table:

## SSH TRANSLATION TABLE FILE FORMAT VERSION 1.0
##################################################################
#
# This file is an example translation table that can be used to
# translate data from 'ISO8859-1' to 'IBM-1047,swaplfnl' while reading
# from a file or from 'IBM-1047,swaplfnl' to 'ISO8859-1' while writing
# to a file.
#
# The format of translation table file is following:
#
# - White spaces are ignored.
# - Everything after '#' character until end of line is a comment
#   that is ignored.
# - The first table is used when writing data to a file.
# - The second table is used when reading data from a file.
# - Both tables must exist.
# - Table is a simple hexadecimal representation of the
#   translation. Each value is represented as two hexadecimal
#   characters. The first line gives the values in table
#   positions 0-15 (00-0F), the second line 16-31 (10-1F)
#   and so on.
#
# Note: Only single byte translations are supported.
#
#################################################################

# Inbound (network to file) translation table:
# IBM-1047,swaplfnl -> ISO8859-1

#0-1-2-3-4-5-6-7-8-9-A-B-C-D-E-F
000102039C09867F978D8E0B0C0D0E0F #0
101112139D0A08871819928F1C1D1E1F #1
808182838485171B88898A8B8C050607 #2
909116939495960498999A9B14159E1A #3
20A0E2E4E0E1E3E5E7F1A22E3C282B7C #4
26E9EAEBE8EDEEEFECDF21242A293B5E #5
2D2FC2C4C0C1C3C5C7D1A62C255F3E3F #6
F8C9CACBC8CDCECFCC603A2340273D22 #7
D8616263646566676869ABBBF0FDFEB1 #8
B06A6B6C6D6E6F707172AABAE6B8C6A4 #9
B57E737475767778797AA1BFD05BDEAE #A
ACA3A5B7A9A7B6BCBDBEDDA8AF5DB4D7 #B
7B414243444546474849ADF4F6F2F3F5 #C
7D4A4B4C4D4E4F505152B9FBFCF9FAFF #D
5CF7535455565758595AB2D4D6D2D3D5 #E
30313233343536373839B3DBDCD9DA9F #F

# Outbound (file to network) translation table:
# ISO8859-1 -> IBM-1047,swaplfnl
#
#0-1-2-3-4-5-6-7-8-9-A-B-C-D-E-F
00010203372D2E2F1605150B0C0D0E0F #0
101112133C3D322618193F271C1D1E1F #1
405A7F7B5B6C507D4D5D5C4E6B604B61 #2
F0F1F2F3F4F5F6F7F8F97A5E4C7E6E6F #3
7CC1C2C3C4C5C6C7C8C9D1D2D3D4D5D6 #4
D7D8D9E2E3E4E5E6E7E8E9ADE0BD5F6D #5
79818283848586878889919293949596 #6
979899A2A3A4A5A6A7A8A9C04FD0A107 #7
202122232425061728292A2B2C090A1B #8
30311A333435360838393A3B04143EFF #9
41AA4AB19FB26AB5BBB49A8AB0CAAFBC #A
908FEAFABEA0B6B39DDA9B8BB7B8B9AB #B
6465626663679E687471727378757677 #C
AC69EDEEEBEFECBF80FDFEFBFCBAAE59 #D
4445424643479C485451525358555657 #E
8C49CDCECBCFCCE170DDDEDBDC8D8EDF #F

# EOF

	Note
	When ICU libraries are used for generating ASCII to EBCDIC translation tables, '`,swaplfnl`' must be added to EBCDIC codepage name so that ASCII newline character is correctly translated to EBCDIC newline character.

In order to create custom translation tables, first create a standard table and manually edit it to suite your needs.

Translation tables can be used with SSH Tectia file transfer clients and server. The translation can be performed either in the client or in the server. The translation table file must be available in the host that is performing the translation.

Using Translation Tables with sftpg3

Translation table filename is specified using site parameter TRANSFER_TRANSLATE_TABLE or E. Since translation table filename can be part of file transfer advice string, '/' character must be encoded as '%2f'. Also, the parameter must be just one value without spaces. Space must be encoded as '%20'.

	Note
	File transfer clients sftpg3 and scpg3 encode '`/`' internally as '`%2f`'.

	Note
	If translation is performed in SSH Tectia sftpg3 or scpg3 client, server does not have to be SSH Tectia.

Here is an upload example, where translation is done in the sftpg3 client:

$ sftpg3 user@example.com
sftp> lsite E=/path/to/ISO8859-1_to_IBM-1047,swaplfnl.txt
sftp> sput ISO8859-1_file.txt IBM-1047_file.txt

With the lsite command, translation is activated on the local end. Text file is translated from ISO8859-1 to IBM-1047 and transferred as a binary file.

	Note
	Since translation tables only handle single byte convertions it is not possible to change newline convention from DOS to Unix or MVS with the translation table only.

The following example shows the download of a file:

$ sftpg3 user@example.com
sftp> lsite E=/path/to/ISO8859-1_to_IBM-1047,swaplfnl.txt
sftp> sget IBM-1047_file.txt ISO8859-1_file.txt

In this upload example, translation is done in the remote server:

$ sftpg3 user@example.com
sftp> ascii
sftp> site E=/path/to/IBM-1047,swaplfnl_to_ISO8859-1.txt
sftp> sput ISO8859-1_file.txt IBM-1047_file.txt

With the site command, translation is activated on the remote end. Text file is first transferred as text to remote end and then translated from ISO8859-1 to IBM-1047.

	Note
	Since now the translation is done on the remote end, it is possible to first perform newline conversion on the client. Also newline conversion where the length of the data changes, like from DOS to UNIX, can be done in this case.

The following example shows the download of the file:

$ sftpg3 user@example.com
sftp> ascii
sftp> site E=/path/to/IBM-1047,swaplfnl_to_ISO8859-1.txt
sftp> sget IBM-1047_file.txt ISO8859-1_file.txt

Using Translation Tables with scpg3

Here is an upload example, where translation is done in the scpg3 client:

$ scpg3 --src-site=E=/path/to/ISO8859-1_to_IBM-1047,swaplfnl.txt 
ISO8859-1_file.txt user@example.com:IBM-1047_file.txt

With the --src-site option, translation is activated on the local end. Text file is translated from ISO8859-1 to IBM-1047 and transferred as a binary file.

The following example shows the download of the file:

$ scpg3 --dst-site E=/path/to/ISO8859-1_to_IBM-1047,swaplfnl.txt 
user@example.com:IBM-1047_file.txt ISO8859-1_file.txt

In this upload example, translation is done in remote server:

$ scpg3 -a --dst-site=E=/path/to/IBM-1047,swaplfnl_to_ISO8859-1.txt 
ISO8859-1_file.txt user@example.com:IBM-1047_file.txt

With the --dst-site option, translation is activated on the remote end. Text file is first transferred as text to remote end and then translated from ISO8859-1 to IBM-1047.

	Note
	Since now the translation is done on the remote end, it is possible to first perform newline conversion on the client. Also newline conversion where the length of the data changes, like from DOS to UNIX, can be done in this case.

The following example shows the download of the file:

$ scpg3 -a --src-site=E=/path/to/IBM-1047,swaplfnl_to_ISO8859-1.txt 
user@example.com:IBM-1047_file.txt ISO8859-1_file.txt

Using Translation Tables with OpenSSH

Here is an upload example, where translation is done in SSH Tectia Server:

$ sftp user@example.com
sftp> put ISO8859-1_file.txt 
/ftadv:E=%2fpath%2fto%2fIBM-1047,swaplfnl_to_ISO8859-1.txt/IBM-1047_file.txt

With ftadv string in destination file name, translation is activated on the remote end. Text file is first transferred to remote end and then translated from ISO8859-1 to IBM-1047.

	Note
	When translation table information is given in `ftadv` string, '`/`' character must be encoded as '`%2f`'. Also, since the parameter must be just one value without spaces, space must be encoded as '`%20`'.

The following example shows the download of the file:

$ sftp user@example.com
sftp> get /ftadv:E=%2fpath%2fto%2fIBM-1047,
swaplfnl_to_ISO8859-1.txt/IBM-1047_file.txt ISO8859-1_file.txt