Defining the conversion table

You define the conversion table with DFHCNV resource definition macros, which are described below.

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.

If you are running CICS® on System/390® in a z/OS® environment, see Assembling and link-editing the conversion programs.

DFHCNV macro types

The following macros define the conversion table:

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. A conversion template is defined by one or more DFHCNV TYPE=FIELD macros following a DFHCNV TYPE=SELECT macro. A key template consists of one or more DFHCNV TYPE=FIELD macros following a DFHCNV TYPE=KEY macro. Each type of template is terminated by the next non-FIELD macro in the table definition. Figure 14 shows templates within a complete conversion table definition.

Start of change

Defaults for client and server code pages

This section applies only to CICS Transaction Server for z/OS Version 3 Release 1 and later.

Certain distributed components of a CICSplex such as CICS Transaction Gateway for z/OS and CICS Transaction Server for Windows do not provide an override for the default client code page specified in the conversion table. As conversion tables do not have a suffix, a consequence of this is that two tables can be required, each residing on a different library and differing only in the default code page.

In order 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.
End of change

Example sequence--DFHCNV macros

Figure 14 shows a typical sequence of DFHCNV macros. The figure is annotated to show the sets of entries that correspond to resource entries, conversion templates, and key templates. (The indentation is to illustrate nesting. When coding the macros, as with all CICS resource definition macros, observe assembler rules.)

Conversion table for initial program verification (IVP)

When running the IVP jobs for your CICS on System/390 system, you need the conversion table whose source is given in Figure 13. You don’t need to code all these macros. You can generate exactly the same conversion table by assembling the special macro, DFHCNV TYPE=IVP.

Figure 13 is a simple example of a conversion table definition.

All the fields are character, so only a single TYPE=SELECT macro is needed. It specifies OPTION=DEFAULT, and has a single TYPE=FIELD macro to define the whole data record.

The TYPE=KEY macro is followed by a single TYPE=FIELD macro, which redefines the first six bytes of the data record.

Figure 13. Conversion table for IVP
   DFHCNV TYPE=INITIAL
   DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=FILEA,USREXIT=NO
   DFHCNV TYPE=KEY
   DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=6,LAST=YES
   DFHCNV TYPE=SELECT,OPTION=DEFAULT
   DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=80,LAST=YES
   DFHCNV TYPE=FINAL
 
Figure 14. Example of DFHCNV macro sequence
Example of DFHCNV macro sequence

DFHCNV TYPE=INITIAL

The DFHCNV TYPE=INITIAL macro has the following format:

Start of change
Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=INITIAL----------------------------------------->
 
>--+------------------------------------+----------------------->
   |            .-437-----------------. |
   '-,CLINTCP=--+---------------------+-'
                +-SYSDEF--------------+
                |       .-----------. |
                |       V           | |
                '-nnnn----+-------+-+-'
                          '-,nnnn-'
 
>--+------------------------------------+----------------------->
   |            .-037-----------------. |
   '-,SRVERCP=--+---------------------+-'
                +-SYSDEF--------------+
                |       .-----------. |
                |       V           | |
                '-nnnn----+-------+-+-'
                          '-,nnnn-'
 
>--+--------------------------------+--------------------------><
   |                  .-----------. |
   |                  V           | |
   '-,CDEPAGE=--nnnn----+-------+-+-'
                        '-,nnnn-'
 
End of change
TYPE=INITIAL
Defines the beginning of the conversion table.
Start of changeCLINTCP={437|SYSDEF|nnnn[,nnnn, ...]}End of change
Start of changeThe first operand defines the default client Start of changeCCSIDEnd of change to be used when the CLINTCP and CDEPAGE operands are omitted from a DFHCNV TYPE=ENTRY macro.

SYSDEF specifies that the default client code page is determined by the system initialization table parameter CLINTCP. SYSDEF applies only to CICS Transaction Server for z/OS Version 3 Release 1 and later.

For an explanation of code pages, and a list of those that you can specify, see Character data.

End of change
Start of changeSRVERCP={037|SYSDEF|nnnn[,nnnn, ...]}End of change
Start of changeThe first operand defines the Start of changeserver CCSIDEnd of change to be used when the SRVERCP and CDEPAGE operands are omitted from a DFHCNV TYPE=ENTRY macro.

SYSDEF specifies that the default server code page is determined by the system initialization table parameter SRVERCP. SYSDEF applies only to CICS Transaction Server for z/OS Version 3 Release 1 and later

For an explanation of code pages, and a list of those that you can specify, see Character data.

End of change
CDEPAGE=nnnn[,nnnn...]
(Retained for compatibility with earlier releases. Do not use for new definitions. )

Each possible value is equivalent to a pair of CLINTCP and SRVERCP entries or (for user-defined conversion) to a SRVERCP entry.

437
Is equivalent to:
  • CLINTCP=437
  • SRVERCP=037
932K
Is equivalent to:
  • CLINTCP=932
  • SRVERCP=930
932
Is equivalent to:
  • CLINTCP=932
  • SRVERCP=931
USR
Is equivalent to:
  • SRVERCP=USR
USRD
Is equivalent to:
  • SRVERCP=USRD

DFHCNV TYPE=ENTRY

The DFHCNV TYPE=ENTRY macro instruction has the following format:

Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=ENTRY--,RTYPE=--+-FC-+-------------------------->
                                +-IC-+
                                +-PC-+
                                +-TD-+
                                '-TS-'
 
>--+-----------------------------------+------------------------>
   '-CLINTCP=--+---------------------+-'
               +-SYSDEF--------------+
               |       .-----------. |
               |       V           | |
               '-nnnn----+-------+-+-'
                         '-,nnnn-'
 
>--+---------------------+-------------------------------------->
   '-SRVERCP--+--------+-'
              +-SYSDEF-+
              '-nnnn---'
 
>--+-| Resource (standard syntax) |--------------------------------------------+-->
   '-| Resource (extended syntax for CICS TS for z/OS Version 2.3 and later) |-'
 
   .-,USREXIT=YES-.
>--+--------------+--+---------------+-------------------------><
   +-,USREXIT=NO--+  '-,CDEPAGE=nnnn-'
   '-,--program---'
 
Resource (standard syntax):
 
|--+-,RNAME=resourcename------+---------------------------------|
   '-,XRNAME=xxxxxxxxxxxxxxxx-'
 
Resource (extended syntax for CICS TS for z/OS Version 2.3 and later):
 
|--+--------------------------+---------------------------------|
   +-,RNAME=resourcename------+
   +-,RPFX=resourceprefix-----+
   +-,XRNAME=xxxxxxxxxxxxxxxx-+
   '-,XRPFX=xxxxxxxxxxxxxx----'
 
TYPE=ENTRY
Specifies that this macro defines a resource by name and type.
RTYPE={FC|TS|TD|IC|PC}
Specifies the type of resource:
FC 
A file
TS 
A temporary storage queue
TD 
A transient data queue
IC 
An interval control start with data
PC
A program link with a COMMAREA.
Start of changeCLINTCP={nnnn[,nnnn, ...]|SYSDEF}End of change
Start of changeThe first operand defines the default client code page to be used.

SYSDEF specifies that the default client code page is determined by the system initialization table parameter CLINTCP. SYSDEF applies only to CICS Transaction Server for z/OS Version 3 Release 1 and later.

For an explanation of code pages, and a list of those that you can specify, see Character data.

End of change
Start of changeSRVERCP={nnnn|SYSDEF}End of change
Start of changeThe operand defines the server code page to be used.

SYSDEF specifies that the server code page is determined by the system initialization table parameter SRVERCP. SYSDEF applies only to CICS Transaction Server for z/OS Version 3 Release 1 and later.

For an explanation of code pages, and a list of those that you can specify, see Character data.

End of change
RNAME=resourcename
Specifies the name of the resource in up to eight characters. If shorter, it is padded with blanks; if longer, it is truncated. The name can be:
RPFX=resourceprefix
Applies only to CICS TS for z/OS Version 2.3 and later. Specifies a resource prefix of up to 7 characters for programs, TS queues and files; or 3 characters for TD queues and transactions. The resource prefix allows resources of a particular type to be grouped together using just one macro. All resources of the specified type and prefix will be treated in the same way. Order is important, so the most specific resource names should be at the top of the converstion table, with the least specific prefixes at the bottom. If none of the parameters are specified at this point in the macro, the default template is used for all resources within the specified resource type.
XRNAME=xxxxxxxxxxxxxxxx (RTYPE=TS only)
Specifies the resource name in hexadecimal notation. It can include up to 16 hexadecimal digits, padded with blanks if necessary.
XRPFX=xxxxxxxxxxxxxx (RTYPE=TS only)
Applies only to CICS TS for z/OS Version 2.3 and later. Specifies a resource prefix of up to 14 hexadecimal digits. The resource prefix allows resources of a particular type to be grouped together. All resources of the specified type and prefix will be treated in the same way. Order is important, so the most specific resource names should be at the top of the conversion table, with the least specific prefixes at the bottom.If none of the parameters are specified at this point in the macro, the default template is used for all resources within the specified resource type.
USREXIT={YES|NO|program}
Specifies whether the user data conversion exit is called.
YES
User-defined conversion is required for this resource. DFHUCNV is invoked. Code this if you need your customized version of DFHUCNV to convert some data for this resource.
NO
User-defined conversion is not required for this resource. The user-replaceable conversion program is not called. Code this to eliminate the overhead of calling the program unnecessarily.
program (applies only to CICS TS for z/OS Version 2.2 and later)
User-defined conversion is required for this resource; program is invoked. Code this if you need your user-supplied program, program, to convert some data for this resource.
CDEPAGE=nnnn
(Not for new definitions. Retained for compatibility with earlier releases.)

The code page must be one of those entered in the CDEPAGE option of the DFHCNV TYPE=INITIAL macro. Each possible value is equivalent to a pair of CLINTCP and SRVERCP entries or (for user-defined conversion) to a SRVERCP entry. The CLINTCP and SRVERCP values to which each value resolves are given in the description of the CDEPAGE option of the DFHCNV TYPE=INITIAL macro.

DFHCNV TYPE=KEY

The DFHCNV TYPE=KEY macro is valid only for FC RTYPE requests, and, if coded, must immediately follow a DFHCNV TYPE=ENTRY macro. The macro has the following format:

Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=KEY--------------------------------------------><
 
TYPE=KEY
Indicates the start of conversions to be applied to a key. This macro is not required if access is only by RRN or RBA. If access is by key but no TYPE=KEY statement is present, the key is not converted. You must provide matching conversion details (DFHCNV TYPE=FIELD macros) for the key, as part of each conversion template that applies to this file, or an INVREQ condition may be returned on the file control EXEC CICS request.

DFHCNV TYPE=SELECT

The DFHCNV TYPE=SELECT macro instruction has the following format:

Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=SELECT--,OPTION=--+-COMPARE-+--,OFFSET=nnnn----->
                                  '-DEFAULT-'
 
>--+-,DATA='dd...dd'--+----------------------------------------><
   '-,XDATA='xx...xx'-'
 
TYPE=SELECT
Indicates the start of conversion definitions (DFHCNV TYPE=FIELD macros) to be applied to a record that satisfies the comparison defined in this macro. If the defined comparison is not satisfied by the data in the record, the conversion program (DFHCCNV) skips to the next TYPE=SELECT macro, until it finds a match or reaches the OPTION=DEFAULT macro. Every TYPE=SELECT macro must be followed by at least one TYPE=FIELD macro.
OPTION={COMPARE|DEFAULT}
States the basic selection options:
COMPARE
Indicates that the data should be converted according to the specifications in the following DFHCNV TYPE=FIELD macros, if the record satisfies the comparison defined in this macro (OFFSET and DATA or XDATA options).
DEFAULT
Indicates that the data should be converted according to the specifications in the following DFHCNV TYPE=FIELD macros, if the record has not satisfied the comparison defined in any previous DFHCNV TYPE=SELECT COMPARE macro.

For each resource entry (started by a TYPE=ENTRY macro) the last TYPE=SELECT macro must specify OPTION=DEFAULT. No other TYPE=SELECT macro in the entry should specify OPTION=DEFAULT.

The following options are ignored if OPTION=DEFAULT is coded.

OFFSET=nnnn
Specifies the byte offset in the record at which the comparison should be made, up to a maximum of 65535.
DATA='dd...dd'
(Use only if the data to be tested is defined as DATATYP=CHARACTER, SOSI=NO)

Specifies the comparison data as a character string, with a maximum length of Start of change255End of change characters. Because you specify this data on the System/390 system, it is in EBCDIC. The system converts the incoming data from ASCII to EBCDIC before checking it against the comparison data, so that EBCDIC is compared with EBCDIC. Outgoing data is in EBCDIC, so the comparison is made in EBCDIC without conversion.

XDATA='xx...xx'
(Use if DATA option is not used)

Specifies the comparison data as a hexadecimal string, with an even number of digits, maximum length 254 digits. Data is compared against this field, without conversion.

DFHCNV TYPE=FIELD

The DFHCNV TYPE=FIELD macro instruction occurs as many times as needed, and has the following format:

Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=FIELD--,OFFSET=nnnn--,DATATYP=--+-BINARY----+--->
                                                +-CHARACTER-+
                                                +-GRAPHIC---+
                                                +-NUMERIC---+
                                                +-PD--------+
                                                '-USERDATA--'
 
>--,USRTYPE=nnn--,DATALEN=nnnn--+-----------+------------------->
                                '-,LAST=YES-'
 
>--+-----------------+-----------------------------------------><
   |         .-NO--. |
   '-,SOSI=--+-----+-'
             '-YES-'
 
TYPE=FIELD
Specifies conversion specifications for a data field. There must be one such statement for each field in a record. Start of changeYou cannot code a TYPE=FIELD macro until you have coded a TYPE=SELECT macro.End of change
OFFSET=nnnn
Specifies the byte offset in the record or key at which the conversion should start, up to a maximum of 65535. (For TYPE=KEY conversions, this is the byte offset from the start of the key not from the start of the record. The file’s FCT entry defines the offset of the first byte of the key from the start of the record.)
DATATYP={CHARACTER|PD|BINARY|USERDATA|GRAPHIC|NUMERIC}
Specifies the type of conversion required:
CHARACTER
Specifies character fields.
PD
Specifies packed decimal data in System/390 format.

If workstation packed decimal (PD) fields are to be transmitted to a System/390, specify the IBMCOMP and SIGN EBCDIC directives with the CICSCOMP command used to compile a CICS Transaction Server for Windows COBOL/2 application program. If this program sends data to the System/390, packed decimal fields are in System/390-compatible format. Define such fields as PD (no conversion needed). Any packed decimal data in non-System/390 format (for example, workstation native mode) should be defined for USERDATA conversion, and the user-replaceable program DFHUCNV must contain the necessary conversion code.

BINARY
Specifies binary data in Start of changebig-endianEnd of change format.

The CICS Transaction Server for Windows user can specify the IBMCOMP directive with the CICSCOMP command used to compile a CICS Transaction Server for Windows COBOL/2 application program that creates binary fields in Start of changebig-endianEnd of change-compatible format.

By default, COBOL/2 binary fields are held on the workstation in Start of changelittle-endianEnd of change format, and should be defined as NUMERIC. C language integer fields are always held on the workstation in Start of changelittle-endianEnd of change format, and should be defined as NUMERIC.

By default, BINARY data is not converted. This default action can be overridden to allow requests from platforms that support different binary architectures to access the same System/390 resource using the same conversion table.

USERDATA
Specifies data to be converted by the user-replaceable program DFHUCNV. The DFHCCNV conversion code bypasses these fields. See the USRTYPE operand below.
GRAPHIC
Specifies fields that contain DBCS characters only.
NUMERIC
Specifies that binary fields held on the workstation in INTEL format (for example, C Language integer datatype) need to be converted to System/390 format. Integers (four bytes) or short integers (two bytes) can be converted.
Start of changeUSRTYPE=nnnEnd of change
Specifies a value that is made available to the user-replaceable conversion program DFHUCNV. The values you provide can be in the range 80 to 128 (X'50' to X'80'). The default value is 80 (X'50'). If more than one type of user-defined conversion is possible, you can use this value to specify to DFHUCNV what conversion is needed for each field.

This option is ignored if DATATYP=USERDATA is not specified.

DATALEN=n
Specifies the length of the data field to be converted, in bytes, up to a maximum of 65535. For variable length fields, specify the maximum possible length.

If DATATYP=NUMERIC, DATALEN must be 2 or 4.

LAST=YES
Specifies that this is the last field definition for this TYPE=SELECT statement.
SOSI=YES|NO
Enter YES for a mixed string containing SBCS and DBCS characters; enter NO for an SBCS string. This field is valid only if DATATYPE=CHARACTER has been entered in this macro. The default is NO.

DFHCNV TYPE=FINAL

The DFHCNV TYPE=FINAL macro instruction ends the table. It must occur only once, as the last definition.

Read syntax diagramSkip visual syntax diagram>>-DFHCNV--TYPE=FINAL------------------------------------------><
 

Hints on coding the macros

CICS does not check the order of the fields defined in the table, or for overlap. This is relevant to the first two hints below:

  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 accessed only by a remote CICS Transaction Server for Windows or CICS on Open Systems system, and never by the System/390 system, there is no need to provide conversion details. A typical case is a System/390 file used to pass data between CICS Transaction Server for Windows users.
  5. CICS Transaction Server for Windows assumes that record key formats are not redefinable, so they must be the same for all redefined record types. If a resource has a key template, then all conversion templates for that resource must exactly replicate the key conversion specified in the key template.

Related concepts
Where data conversion takes place
Function shipping and DPL
Distributed transaction processing
Transaction routing
Types of conversion
Character data
Binary data
The conversion process
User-defined conversion tables
Example macros
The user-replaceable conversion program
Related tasks
Avoiding data conversion
Resource definition to enable data conversion
Assembling and link-editing the conversion programs
Related reference
Where data conversion takes place
Character dataThe user-replaceable conversion program

9.
FC record, TS data, TD data, IC start "from" data, or COMMAREA transmitted with DPL

[[ Contents Previous Page | Next Page Index ]]