Verbs and Built-in Functions › &ENCODE

&ENCODE

The &ENCODE verb encodes all or part of an MDO into a serial byte stream, ready for transmission.

This verb has the following format:

&ENCODE MDO=sourcemdo
      [ { TRANSLATE={ NO | ISO | DEC | ASCII } |
          TGT_CHARSET=name SRC_CHARSET=name
        [ SINGLE_SUB=xx ]
        [ DOUBLE_SUB=xxxx ] } ]
      [ CHECK | TRANSFER={ NO | BER } ]
      [ INTO MDO=targetmdo ]

An NCL procedure can encode all, or part, of an MDO into a serial byte stream, ready for transmission using the &ENCODE verb.

Operands:

MDO=sourcemdo

(Mandatory) Identifies the source component for the encoding operation. sourcemdo name is:

• A stem name, for example, MDO=ROSE (indicates that the source is an entire MDO)
• A compound name, for example, MDO=CMIP.GETARG (indicates that the source is a component within the MDO)

TRANSLATE={ NO | ISO | DEC | ASCII }

Specifies the translation of character strings. If TRANSLATE=NO is specified, or defaulted, then no character set translation occurs.

During translation, all character codes are assumed to be in EBCDIC and are translated to the indicated character set. Source graphic characters that do not have a defined translation are translated to blanks. Control characters are translated to nulls. When used with a transfer, syntax translation takes place before encoding, but does not affect sourcemdo, the encoded results being placed into targetmdo. When used without a transfer syntax and without the CHECK keyword, the source MDO is modified in place.

TGT_CHARSET=name

Names the target character set. If this operand is specified, the TRANSLATE operand cannot be specified.

Use TGT_CHARSET instead of TRANSLATE to specify translation using the Advanced Translation Facility (ATF).

SRC_CHARSET=name

Names the source character set. If this operand is specified, the TRANSLATE operand cannot be specified.

SRC_CHARSET defaults to SOLVE. However, you can specify any other character set name to indicate that you want to translate from that character set.

SINGLE_SUB=xx

(Optional) Specifies an overriding target one-byte substitution character. The value is in two hexadecimal characters. For example, to replace all untranslatable characters with an EBCDIC question mark, code SINGLE_SUB=3F (assuming TGT_CHARSET=ASCII).

This operand is valid only if TGT_CHARSET is specified.

DOUBLE_SUB=xxxx

(Optional) Specifies an overriding target two-byte substitution character. The value is in four hexadecimal characters.

This operand is valid only if TGT_CHARSET is specified.

CHECK | TRANSFER={ NO | BER }

The CHECK operand specifies that sourcemdo is checked for syntax. No translation or data transfer actually takes place, but the specified component is examined to determine whether it conforms to the abstract syntax definition. All subcomponents are examined. Missing mandatory components or invalid data causes the process to terminate.

The TRANSFER operand specifies the use of transfer syntax when encoding. If NO is specified (or defaulted), then no encoding takes place. TRANSFER=BER indicates the use of Basic Encoding Rules as the transfer syntax.

When the TRANSFER operand indicates use of a transfer syntax, the INTO keyword is required to indicate the targetmdo. Encoding takes place in accordance with the definition of sourcemdo, and the resultant data stream is placed into targetmdo. If translation was also requested (by specifying the TRANSLATE operand), translation of source component character strings occurs before encoding, but sourcemdo is unaffected.

If the TRANSFER operand is omitted, or TRANSFER=NO is specified, no encoding takes place, and the INTO keyword and targetmdo cannot be specified.

• A stem name (for example, MDO=ROSE) indicating that the target is an entire MDO
• A compound name (for example, MDO=CMIP.GETARG) indicating that the target is a component within the MDO

INTO MDO=targetmdo

Specifies the target component for the encode operation. The operand is required when the TRANSFER operand is used, but is otherwise invalid.

If a compound name is used, the MDO must exist and be mapped, or the request fails. If only a stem name is provided, the request creates the MDO if it does not exist. The MDO can be connected to a map on a subsequent NCL statement.

Return Codes:

For &RETCODE 4, the &SYSMSG variable contains a warning message describing the condition.

For &RETCODE 8, the &SYSMSG variable contains an error message describing the component in error, and the actual error condition.

Notes:

• When communicating with other open systems, it is necessary to encode data for transmission in a manner understood by both parties. This means that both systems need only agree on the format of the transmitted data, and not how that data is processed or kept locally in each system.

  A transfer syntax describes the format of the transmitted data. The transfer syntax formally defines the rules for converting an abstract data structure as defined by the abstract syntax into a serial data stream.

  Mapping Services uses Abstract Syntax Notation One (ASN.1), defined by ISO 8824 as the abstract syntax used to describe data structures within your product region. It also uses Basic Encoding Rules (BER) defined by ISO 8825, as the transfer syntax used to serialize data for transmission.

  Using the &ENCODE verb, an NCL procedure can encode all, or part of an MDO, into a serial byte stream, ready for transmission. Often, this process must take place in stages, as some ASN.1 structures require that various substructures are already encoded elsewhere before the structure itself is encoded. To cater for this requirement, encoding takes place from one MDO to another. When all encoding is complete the final MDO is transmitted as a serial byte stream.

  The &DECODE verb provides the reverse process, creating the logical ASN.1 components from a serial byte stream.

  In addition to the serialization of data for transmission, the &ENCODE and &DECODE verbs provide the ability to translate between the ASN.1 defined character sets into the local format, EBCDIC.

• The Advanced Translation Facility (ATF) only translates some data types.

  Important differences exist between ATF and the &ENCODE/&DECODE verbs translation facility.

  ENCODE could optionally translate from EBCDIC to ASCII, ISO, or DEC.

  The differences between the ENCODE TRANSLATE=ASCII operation and the ATF translation from EBCDIC to ASCII are:

  • The ENCODE substitution character is X'20', whereas the ATF substitution character is X'1A'.
  • ENCODE translates most control characters to X'20', not to their ASCII equivalents.
  • ENCODE translates X'B0' in EBCDIC to X'5E' in ASCII. This character is the ASCII caret (^). However, B0 in EBCDIC is not assigned.

  The differences between the DECODE TRANSLATE=ASCII operation and the ATF translation from ASCII to EBCDIC are:

  • The DECODE substitution character is X'40', whereas the ATF substitution character is X'3F'.
  • DECODE translates most ASCII control characters to X'00' (but other undefined characters get translated to X'40').
  • DECODE absorbs the following ASCII characters (that is, no output character is generated): X'0F', X'8E', X'8F'.

  Do not replace the use of ASCII translation in ENCODE/DECODE with ATF directly.

Example 1:

&ENCODE MDO=ROSE CHECK

This example validates that an MDO conforms to its defined abstract syntax definition.

Example 2:

&ENCODE MDO=CMIP.GETARG TRANSLATE=ISO

&ENCODE MDO=ROSE TRANSLATE=DEC TRANSFER=NO

In these examples, components present in sourcemdo, and defined as ASN.1 character strings, are translated from EBCDIC to the indicated character set.

Example 3:

&ENCODE MDO=CMIP.GETARG TRANSFER=BER INTO +
      MDO=ROSE.ROIVAPDU

&ENCODE MDO=ROSE TRANSLATE=NO TRANSFER=BER INTO +
      MDO=BYTESTR

&ENCODE MDO=ROSE TRANSLATE=ASCII TRANSFER=BER INTO +
      MDO=BYTESTR

In these examples, sourcemdo is encoded into a serial byte stream, with character string translation from EBCDIC to the indicated character set, if any.

Example 4:

&ENCODE MDO=IN TGT_CHARSET=ASCII

This example translates character data in the MDO IN into ASCII.

Example 5:

&ENCODE MDO=IN TGT_CHARSET=JIS7 TRANSFER=BER INTO MDO=OUT

This example translates character data in the MDO IN into JIS7, a standard for single/double-byte character data, and applies ISO BER encoding too. The result is placed into the MDO OUT.

More information:

Code Page Selection

&DECODE