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.
The following macros define the conversion table:
- 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. There must be one for each resource for which conversion is required
(no conversion is applied to a resource that is 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.
CICS TS for z/OS Version 2.3 and later
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 order becomes 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).
When used, this macro 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 9 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. There must be 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.
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.
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:
- In the DFHCNV TYPE=ENTRY and TYPE=SELECT macros, specify the value SYSDEF
for the CLINTCP parameter.
- 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:
- In the DFHCNV TYPE=ENTRY and TYPE=SELECT macros, specify the value SYSDEF
for the SRVERCP parameter.
- 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.
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
The DFHCNV TYPE=INITIAL macro has the following format:

>>-DFHCNV--TYPE=INITIAL----------------------------------------->
>--+------------------------------------+----------------------->
| .-437-----------------. |
'-,CLINTCP=--+---------------------+-'
+-SYSDEF--------------+
| .-----------. |
| V | |
'-nnnn----+-------+-+-'
'-,nnnn-'
>--+------------------------------------+----------------------->
| .-037-----------------. |
'-,SRVERCP=--+---------------------+-'
+-SYSDEF--------------+
| .-----------. |
| V | |
'-nnnn----+-------+-+-'
'-,nnnn-'
>--+--------------------------------+--------------------------><
| .-----------. |
| V | |
'-,CDEPAGE=--nnnn----+-------+-+-'
'-,nnnn-'

- TYPE=INITIAL
- Defines the beginning of the conversion table.
CLINTCP={437|SYSDEF|nnnn[,nnnn, ...]}
The first operand defines the default client
CCSID
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.
SRVERCP={037|SYSDEF|nnnn[,nnnn, ...]}
The first operand defines the
server CCSID
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.
- 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:
- 932K
- Is equivalent to:
- 932
- Is equivalent to:
- USR
- Is equivalent to:
- USRD
- Is equivalent to:
The DFHCNV TYPE=ENTRY macro instruction has the following format:

>>-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.
CLINTCP={nnnn[,nnnn, ...]|SYSDEF}
The 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.
SRVERCP={nnnn|SYSDEF}
The 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.
- 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:
- A System/390 file name (up to eight characters).
- A TS queue name (up to eight characters).
Note:
Although CICS TS for OS/390® Release 3 and above support TS queue names of up to16 characters,
DFHCNV only supports TS queue names of up to 8 characters.
- A TD queue name (up to four characters).
- An IC start transaction id (up to four characters).
- The name of the program being linked (up to eight characters).
- 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.
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:

>>-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.
The DFHCNV TYPE=SELECT macro instruction has the following format:

>>-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
255
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.
The DFHCNV TYPE=FIELD macro instruction occurs as many times as needed,
and has the following format:

>>-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.
You cannot code
a TYPE=FIELD macro until you have coded a TYPE=SELECT macro.
- 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
big-endian
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
big-endian
-compatible format.
By default, COBOL/2 binary fields are held on the workstation in
little-endian
format, and should be defined as NUMERIC. C language integer fields
are always held on the workstation in
little-endian
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.
USRTYPE=nnn
- 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.
The DFHCNV TYPE=FINAL macro instruction ends the table. It must occur only
once, as the last definition.

>>-DFHCNV--TYPE=FINAL------------------------------------------><
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:
- Define entries for the most frequently-used resources first, to reduce
search time.
- Define USERDATA fields in consecutive entries. This reduces the time needed
by your conversion program to scan the template.
- 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.)
- 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.
- 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.

FC record, TS data,
TD data, IC start "from" data, or COMMAREA transmitted with DPL
[[ Contents Previous Page | Next Page Index ]]