Defining the conversion table

You define the conversion table with DFHCNV resource definition macros. The output of the DFHCNV macro assembly contains templates specifying resource conversion requirements and conversion tables to enable the required conversions. User-generated conversion tables must be placed in the DFHCNV macro source.

DFHCNV macro types

DFHCNV TYPE=INITIAL
Defines the beginning of the conversion table. It defines the default client and server CCSIDs.
DFHCNV TYPE=ENTRY
Specifies a name and type to uniquely identify a data resource. Specify a DFHCNV TYPE=ENTRY macro for each resource for which conversion is required; data is not converted for resources that are not defined in a DFHCNV TYPE=ENTRY macro. The entry for one resource is concluded by the next TYPE=ENTRY statement, or by the end of the table. The CCSID to be used is specified.

You can create generic templates that apply to multiple resources of the same resource type. You do this by using the RPFX or XRPFX parameters of the DFHCNV TYPE=ENTRY macro to specify a prefix that can be matched against multiple resource names, rather than using the full name of a specific resource.

Defining resources in this way means that sequence is important in the conversion table. For example, when specifying file resources, if prefix AB precedes prefix ABCD, the former entry is used to convert data for a file resource named ABCDEFGH. This example would give you an error when assembling the conversion table. To avoid errors, you should put the most specific resource names at the top of the conversion table, with the least specific prefix at the bottom.

When no resource name or prefix is specified, the default conversion template is used for that particular resource type.

For an example of the DFHCNV TYPE=ENTRY macro, see DFHCNV TYPE=ENTRY.

DFHCNV TYPE=KEY
Applies only to an FC entry. Use this macro only if a record might need to be accessed by key (if records are always accessed by relative record number or relative byte address, do not code a TYPE=KEY macro). If you use this macro, it must immediately follow a TYPE=ENTRY macro, and must be followed by one or more TYPE=FIELD macros, which define the data conversion to be applied to the key.
DFHCNV TYPE=SELECT
Defines selection of a record (FC record, TS data, TD data, IC start “from” data, or COMMAREA transmitted with DPL) for data conversion based on the value of a field in the record. Each TYPE=SELECT macro is followed by one or more TYPE=FIELD macros, which define the data conversion to be applied if the record satisfies the test defined in the TYPE=SELECT macro. The last TYPE=SELECT macro for each entry is an OPTION=DEFAULT macro, which defines the conversion to be applied to a record that satisfies no preceding TYPE=SELECT macro.
DFHCNV TYPE=FIELD
Specifies the position and length of a field, and the conversion to be applied to it. You must specify a TYPE=FIELD macro for each field for which conversion is required.
DFHCNV TYPE=FINAL
Concludes the conversion table definition.

Conversion and key templates

Templates are table entries defining fields in a data area or key that are to be converted and the conversion method to be applied to each field. There are two types of template: conversion templates and key templates.

  • A conversion template is defined by one or more DFHCNV TYPE=FIELD macros following a DFHCNV TYPE=SELECT macro.
  • A key template is defined by of one or more DFHCNV TYPE=FIELD macros following a DFHCNV TYPE=KEY macro.

Both types of template are terminated by the next non-FIELD macro in the table definition. Figure 2 shows templates within a complete conversion table definition.

Defaults for client and server code pages

To reduce the number of conversion tables required, you can specify that the default client or server code page is defined in the system initialization table.

For the client code page:
  1. In the DFHCNV TYPE=ENTRY and TYPE=SELECT macros, specify the value SYSDEF for the CLINTCP parameter.
  2. In the system initialization table, set a default client code page by specifying a value for the CLINTCP parameter. You can use any value supported for the CLINTCP parameter on the DFHCNV macro. The default is CLINTCP=437.
For the server code page:
  1. In the DFHCNV TYPE=ENTRY and TYPE=SELECT macros, specify the value SYSDEF for the SRVERCP parameter.
  2. In the system initialization table, set a server code page by specifying a value for the SRVERCP parameter. You can use any value supported for SRVERCP parameter on the DFHCNV macro. The default is SRVERCP=037.

Hints on coding the macros

You can improve the performance of data conversion by coding your macros to benefit from the way in which CICS® processes the conversion tables.

  1. Define entries for the most frequently-used resources first, to reduce search time.
  2. Define USERDATA fields in consecutive entries. This reduces the time needed by your conversion program to scan the template.
  3. For variable-length fields, define the maximum length required. (Comparisons and conversions are applied to the shorter of the actual data length or the template length. For example, if the data is 100 bytes long but the template describes 120 bytes, up to 100 bytes are converted. If the data is 100 bytes and the template describes 80 bytes, only 80 bytes are converted.)
  4. If function-shipped data is not accessed by CICS Transaction Server for z/OS® but only by the connected system, you do not need to specify conversion details. For example, when a CICS Transaction Server for z/OS file is used to store data that is shared by several ASCII-based systems.

Assembling and link-editing the conversion programs

You can use the standard procedure DFHAUPLE to assemble the DFHCNV table.

You can optimize CICS virtual storage use by link-editing the DFHCNV table and the DFHUCNV program with a MODE statement specifying AMODE(31) and RMODE(ANY). The table and program are then loaded in 31-bit storage (above 16 MB but below 2 GB) if enough CICS storage is available.