CONVERT

This verb converts ASCII character strings to EBCDIC and EBCDIC character strings to ASCII.

A program might perform data conversion when it communicates with a node that expects EBCDIC data or when it must convert names to pass over an interface, such as APPC, that requires EBCDIC names.

struct convert
  {
  unsigned short    opcode;        /* Verb identifying operation code.       */
  unsigned char     opext;         /* Reserved.                              */
  unsigned char     reserv2;       /* Reserved.                              */
  unsigned short    primary_rc;    /* Primary return code from verb.         */
  unsigned long     secondary_rc;  /* Secondary (qualifying) return code.    */
  unsigned char     direction;     /* Direction of conversion - ASCII to     */
                                   /* EBCDIC or vice-versa.                  */
  unsigned char     char_set;      /* Character to use for the conversion    */
                                   /* A, AE, or user-defined G.              */
  unsigned short    len;           /* Length of string to be converted.      */
  unsigned char    *source;        /* Pointer to string to be converted.     */
  unsigned char    *target;        /* Address to put converted string at.    */
  } CONVERT;

direction

The nature of the code conversion.

SV_ASCII_TO_EBCDIC

Converts ASCII characters to EBCDIC

SV_EBCDIC_TO_ASCII

Converts EBCDIC characters to ASCII

char_set

The set of characters permitted in the source string. You can specify three types of ASCII/EBCDIC conversion tables for use by the CONVERT verb: SV_A, SV_AE, and SV_G. The type-A and type-AE tables are defined within Personal Communications.

The format of a conversion table consists of 32 lines of 32 characters each. Each line represents 16 printable hexadecimal characters followed by a carriage return and line feed. The first 16 lines provide the information for ASCII-to-EBCDIC conversion. The second 16 lines provide the information for EBCDIC-to-ASCII conversion. The table must include all 32 lines.

When Personal Communications performs a conversion, it uses the numeric equivalent of each incoming character as a 0-origin index into the conversion table. This index specifies the table location containing the hexadecimal value of the converted character. For example, assume the 48th position in the table contains a value of X'F0' . Personal Communications and Communications Server converts incoming characters with a value of 48 (X'30') to a value of 240 (X'F0').

Table A

Table A converts uppercase letters A through Z, numeric characters 0 through 9, and special characters $, #, and @. The first character of the source string must be either an uppercase letter or one of the three special characters; if it is not, no conversion is done, and the INVALID_FIRST_CHARACTER secondary return code is returned. In the ASCII-to-EBCDIC direction, lowercase ASCII characters are converted to uppercase EBCDIC characters.

Trailing blanks (blanks at the end of the source string) are converted to blanks in both directions. In contrast, embedded blanks are converted to X'00'.

If any source character is converted to X'00', CONVERSION_ERROR is returned. However, the entire conversion is completed.

Table AE

Table AE converts alphanumeric characters (A through Z, a through z, 0 through 9), special characters $, #, and @, and the period (.). There are no restrictions on the first character of the string.

Trailing blanks (blanks at the end of the source string) are converted to blanks in either direction. In contrast, embedded blanks are converted to X'00'.

If any source character is converted to X'00', CONVERSION_ERROR is returned. However, the entire conversion is completed.

Table G

You can use a G table to convert from any character to any other character (not just from ASCII to EBCDIC or EBCDIC to ASCII). However, you must specify ASCII_TO_EBCDIC on the CONVERT verb to use the top half of the table and specify EBCDIC_TO_ASCII to use the bottom half.

Personal Communications will look in the registry under

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/Personal Communications /
                                 CurrentVersion/COMTBLG

to get the full path name to the G table. Communications Server will look in the registry under

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/Communications Server/
                                 CurrentVersion/COMTBLG

to get the full path name to the G table. For 32-bit Windows clients, the location of the Table G path in the registry is:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/Comm.Server for NT SNA/Client/
                                 CurrentVersion/COMTBLG

len

The number of characters to be converted.

The length of the string must not extend beyond the segment size allocated for source or target.

source

The address of the character string converted.

target

The address receiving the converted character string.

The OK return code indicates that the CONVERT verb ran successfully.

The following shows the primary and secondary error return codes associated with the CONVERT verb and the location of the return code's description.