The user-replaceable conversion program

This section describes the user-replaceable data conversion program.

User-named conversion programs

Important

This section applies only to CICS® Transaction Server for z/OS®, Version 2 Release 2 and later.

Releases of CICS TS for z/OS from Version 2.2 onwards allow you to replace DFHUCNV, the default user-replaceable conversion program supplied with your CICS on System/390® product, by one or more user-named conversion programs.

DFHUCNV is invoked if:

A user-named conversion program is invoked if:

In the following sections, the generic term "DFHUCNV" represents both the (possibly customized) IBM-supplied conversion program and user-named conversion programs

.

DFHUCNV

For an explanation of why you might need to amend or replace DFHUCNV, refer to User/CICS conversion. If you find that the standard conversion supplied by DFHCCNV meets your needs, you don’t need to use DFHUCNV.

DFHUCNV is described in the following topics:

With this information you can write your own conversion program, using the supplied program as a base.

Input to DFHUCNV

The first statement in the supplied version of DFHUCNV is a DFHCNV TYPE=DSECT macro, which generates DSECTs that describe the parameter list (see Parameter list (DFHUVNDS)) and the conversion template (see the general description of conversion and key templates in Conversion and key templates and the reference information in Conversion and key templates).

DFHUCNV starts with a DFHCNV TYPE=DSECT in the following format:

DFHCNV  TYPE=DSECT

The DFHCNV TYPE=DSECT macro generates the following:

Parameter list (DFHUVNDS)

Figure 23 shows the DFHUNVDS DSECT, which maps the parameter list passed to DFHUCNV in the COMMAREA. If a parameter is zero, no data is available. If you do not create a conversion template for the resource, DFHUCNV is invoked, but only the following fields in the parameter list contain data:

Figure 23. DFHUNVDS--DSECT that maps the parameter list passed to DFHUCNV
DFHUNVDS DSECT
UNVRSTP  DS    AL4                 PTR-TO-RESOURCE TYPE
UNVRNMP  DS    AL4                 PTR-TO-RESOURCE NAME
UNVDIRP  DS    AL4                 PTR-TO-CONVERSION DIRECTIVE
CNVRQATE EQU   X'02'               REQUEST ASCII TO EBCDIC
CNVRPETA EQU   X'04'               RESPONSE EBCDIC TO ASCII
UNVDTMP  DS    AL4                 PTR-TO-DATA CONV TEMPLATE
UNVDLNP  DS    AL4                 PTR-TO-DATA TEMPLATE LENGTH
UNVKTMP  DS    AL4                 PTR-TO-KEY CONV TEMPLATE
UNVKLNP  DS    AL4                 PTR-TO-KEY TEMPLATE LENGTH
UNVATEP  DS    AL4                 PTR-TO-ASCII/EBCDIC TRANS TABLE
UNVETAP  DS    AL4                 PTR-TO-EBCDIC/ASCII TRANS TABLE
UNVATED  DS    AL4                 PTR-TO-DBCS ASCII/EBCDIC TRANS TABLE
UNVETAD  DS    AL4                 PTR-TO-DBCS EBCDIC/ASCII TRANS TABLE

UNVOVLY  DS    0H                  OVERLAY SECTION
         ORG   UNVOVLY             TS REQUEST OVERLAY
UNVTSDP  DS    AL4                 PTR-TO-TS DATA
UNVTSLNP DS    AL4                 PTR-TO-TS DATA LENGTH
         ORG   UNVOVLY             TD REQUEST OVERLAY
UNVTDDP  DS    AL4                 PTR-TO-TD DATA
UNVTDLNP DS    AL4                 PTR-TO-TD DATA LENGTH
         ORG   UNVOVLY             IC REQUEST OVERLAY
UNVICDP  DS    AL4                 PTR-TO-IC DATA
UNVICLNP DS    AL4                 PTR-TO-IC DATA LENGTH
         ORG   UNVOVLY             PC REQUEST OVERLAY
UNVPCDP  DS    AL4                 PTR-TO-PC DATA
UNVPCLNP DS    AL4                 PTR-TO-PC DATA LENGTH
         ORG   UNVOVLY             FC REQUEST OVERLAY
UNVFCDP  DS    AL4                 PTR-TO-FC DATA
UNVFCLNP DS    AL4                 PTR-TO-FC DATA LENGTH
UNVFCKP  DS    AL4                 PTR-TO-FC KEY
UNVFCKLP DS    AL4                 PTR-TO-FC KEY  LENGTH
         ORG   ,
UNVMRTNE DS    A                   PTR-TO-MBCS TRANSLATION ROUTINE
UNVCLIDP DS    AL4                 A "client" CCSID
*                                    (for example, 00819)
UNVSRIDP DS    AL4                 A "server" CCSID
*                                    (for example, 00285)

The following is a detailed description of the parameters:

UNVRSTP
Points to a one-byte resource type that indicates the resource being referenced by this request. The meanings of the resource types are defined in DSECT DFHCNVDS. The resource types are FC, IC, TS, TD, and PC.
UNVRNMP
Points to an eight-character field containing the resource name, padded with blanks if necessary. These may be:
UNVDIRP
Points to a one-byte field that shows what conversion is required:
UNVDTMP
Points to the start of the conversion template found by CICS to match this resource. If UNVDTMP is zero no template was found.
UNVDLNP
Points to a field that gives the length of the conversion template. The field is:
UNVKTMP (file control requests only)
Points to the start of the template found by CICS for the key part of the request or response. If UNVKTMP is zero, either there is no key template or the record is accessed by relative record number or relative byte address.
UNVKLNP (file control requests only)
Points to a field that gives the length of the key conversion template. The field is:
UNVATEP
Points to a 256-byte SBCS translation table used for converting character data from client encoding to server encoding.
UNVETAP
Points to a 256-byte SBCS translation table used for converting character data from server encoding to client encoding.
UNVATED
Points to a DBCS translation table used for converting character data from client encoding to server encoding.
UNVETAD
Points to a DBCS translation table used for converting character data from server encoding to client encoding.

The overlay section depends on resource type:

TS requests:

UNVTSDP
Points to the start of the TS record being read or written. The field is:
UNVTSLNP
Points to a field that gives the length of the TS record.

TD requests:

UNVTDDP
Points to the start of the TD record being read or written.
UNVTDLNP
Points to a field that gives the length of the TD record. The field is:

IC requests:

UNVICDP
Points to the "from" area of an IC START request.
UNVICLNP
Points to a field that gives the length of the "from" area. The field is:

PC requests:

UNVPCDP
Points to the start of the COMMAREA being supplied.
UNVPCLNP
Points to a field that gives the length of the COMMAREA. The field is:

FC requests:

UNVFCDP
Points to the start of the file control record being read or written.
UNVFCLNP
Points to a field that gives the length of the file control record. The field is:
UNVFCKP
Points to the start of the key for the file control record being read or written.
UNVFCKLP
Points to a field that gives the length of the key. The field is:
UNVMRTNE
Points to a translation routine that must be used for translations to or from an MBCS code page. The relevant client code pages are 954, 964, and 970.

The routine expects Register 1 to point to a structure defined by the DFHUNVM DSECT:

DFHUNVM DSECT
UNVMTABP  DS    AL4            Set to value in UNVATED or UNVETAD
UNVMINP   DS    AL4            Address of source data
INVMINL   DS    FL4            Length of source data
UNVMOUTP  DS    AL4            Address of target buffer
UNVMOUTL  DS    FL4            Length of target buffer
 
UNVCLIDP (applies only to CICS TS for z/OS Version 2.2 and later)
Points to a fullword field that gives the IBM-defined CCSID, for example 00819, corresponding to the "client" code page.
UNVSRIDP (applies only to CICS TS for z/OS Version 2.2 and later)
Points to a fullword field that gives the IBM-defined CCSID, for example 00285, corresponding to the "server" code page.
Conversion and key templates

In the COMMAREA, fields UNVDTMP and UNVDLNP point to the conversion template and its length. Fields UNVKTMP and UNVKLNP point to the key template and its length. Figure 24 illustrates the use and meaning of these fields.

Figure 24. Parameter fields and the conversion templates
Parameter fields and the conversion templates

Each type of template consists of field conversion records, one for each field in the data record or key. Each field conversion record has the same layout, shown under Field conversion records, and mapped by a supplied DSECT, DFHCNVDS (see DFHCNVDS, DSECT for field conversion records). Figure 25 shows the relationship between a template, field conversion records, and DFHCNVDS. The figure shows DFHCNVDS overlaying the first field conversion record in a template for a data record or key with six fields.

Figure 25. Field conversion records and a conversion or key template
The picture shows a conversion or key template consisting of six field conversion records. (The template is thus for a data record or key with six fields.) It shows the DFHCNVDS DSECT overlaying the first field conversion record in the template.
Field conversion records

For CICS TS for z/OS, Version 2.2 and later, a field conversion record has the following layout:

Table 40. Layout of a field conversion record for CICS TS for z/OS, Version 2.2 and later
CNVRLEN CNVRTYPE Reserved CNVDATTY CNVDATAO CNVDATAL
Record length Record type Reserved Data type Data offset Data length
Byte 1 Byte 2 Byte 3 Byte 4 Byte 5-8 Byte 9-12

For all CICS on System/390 products other than CICS TS for z/OS Version 2.2 and later, a field conversion record has the following layout:

Table 41. Layout of a field conversion record for CICS on System/390 products other than CICS TS for z/OS Version 2.2 and later
CNVRLEN CNVRTYPE Reserved CNVDATTY CNVDATAO CNVDATAL
Record length Record type Reserved Data type Data offset Data length
Byte 1 Byte 2 Byte 3 Byte 4 Byte 5-6 Byte 7-8

In Table 40 and Table 41, record length and type refer to the length and type of the field conversion record. The names in the top row are those used in the DSECT DFHCNVDS which maps field conversion records (see Figure 26 and Figure 27). A template has as many field conversion records as are necessary to describe all the fields in the data record or key.

For DFHUCNV, CNVRLEN is X'0C' for releases of CICS TS for z/OS from Version 2.2 onwards, and X'08' for all other CICS on System/390 products. CNVRTYPE is always X'04' (field). DFHUCNV must interpret CNVDATTY values in the range X'50' through X'80' according to user specifications, and apply the appropriate conversions. DFHUCNV should ignore fields with CNVDATTY values outside the range X'50' to X'80'.

EQUATEs in DFHCNVDS

Note that DFHCNVDS contains EQUATEs that are useful in your conversion program, as follows:

For resource type addressed by the parameter list
          CNVFC           FILE CONTROL
          CNVTS           TEMPORARY STORAGE
          CNVTD           TRANSIENT DATA
          CNVIC           INTERVAL CONTROL
          CNVPC           PROGRAM CONTROL
For field type in the template
          DTBIN           BINARY
          DTPD            PACKED DECIMAL
          DTCHAR          CHARACTER
          DTMIX           MIXED CHARACTER
          DTDBCS          DBCS CHARACTER
          DTNUM           INTEL INTEGER

Two additional EQUATEs, DTUSRMIN and DTUSRMAX, define the limits of the range of data types (X'50' to X'80') reserved for user definition. Ensure that DFHUCNV can deal with any data type in this range that can be used in your installation.

The supplied DFHUCNV program contains examples of the use of CNVTS, DTUSRMIN, and DTUSRMAX--see Supplied user-replaceable conversion program.

DFHCNVDS, DSECT for field conversion records
CICS TS for z/OS, Version 2.2 and later, version

Figure 26. DFHCNVDS, DSECT that maps conversion/key templates passed to DFHUCNV. This is the CICS TS for z/OS, Version 2.2 and later, version.
DFHCNVDS DSECT
*
*        PROVIDES A MAPPING OF THE FIELD CONVERSION RECORDS USED
*        WHEN DECIDING WHETHER TO CONVERT USER DATA.
*        A SET OF FIELD DEFINITIONS MAKE UP A TEMPLATE
*
CNVRLEN  DS    AL1                 LENGTH OF THIS RECORD
CNVRTYPE DS    XL1                 TYPE OF RECORD
*
*        EQUATES FOR RECORD TYPES
*
CNVTFLD  EQU   X'04'               FIELD (ONLY VALID TYPE IN
*                                  TEMPLATE)
CNVOVLY  DS    0H
**
**
         ORG   CNVOVLY             TYPE FIELD
         DS    XL1                 RESERVED
CNVDATTY DS    XL1                 DATA TYPE
*
*        EQUATES FOR DATA TYPES
*
DTBIN    EQU   X'01'               BINARY
DTPD     EQU   X'02'               PACKED DECIMAL
DTCHAR   EQU   X'03'               CHARACTER
DTMIX    EQU   X'04'               MIXED CHARACTER
DTDBCS   EQU   X'05'               DBCS
DTNUM    EQU   X'06'               NUMERIC
DTUSRMIN EQU   X'50'               MINIMUM USER DATA TYPE
DTUSRMAX EQU   X'80'               MAXIMUM USER DATA TYPE
*
CNVDATAO DS    AL4                 DATA OFFSET
CNVDATAL DS    AL4                 DATA LENGTH
**
*
*        EQUATES FOR RESOURCE TYPES
*
CNVFC    EQU   X'01'               FILE CONTROL
CNVTS    EQU   X'02'               TEMP STORAGE
CNVTD    EQU   X'03'               TRANS DATA
CNVIC    EQU   X'05'               INTERVAL CONTROL
CNVPC    EQU   X'06'               PROGRAM CONTROL

DFHCNVDS, DSECT for field conversion records
Non-CICS TS for z/OS, Version 2.2 and later, version

Figure 27. DFHCNVDS, DSECT that maps conversion/key templates passed to DFHUCNV. This is the version for all CICS on System/390 products other than CICS TS for z/OS, Version 2.2 and later.
DFHCNVDS DSECT
*
*        PROVIDES A MAPPING OF THE FIELD CONVERSION RECORDS USED
*        WHEN DECIDING WHETHER TO CONVERT USER DATA.
*        A SET OF FIELD DEFINITIONS MAKE UP A TEMPLATE
*
CNVRLEN  DS    AL1                 LENGTH OF THIS RECORD
CNVRTYPE DS    XL1                 TYPE OF RECORD
*
*        EQUATES FOR RECORD TYPES
*
CNVTFLD  EQU   X'04'               FIELD (ONLY VALID TYPE IN
*                                  TEMPLATE)
CNVOVLY  DS    0H
**
**
         ORG   CNVOVLY             TYPE FIELD
         DS    XL1                 RESERVED
CNVDATTY DS    XL1                 DATA TYPE
*
*        EQUATES FOR DATA TYPES
*
DTBIN    EQU   X'01'               BINARY
DTPD     EQU   X'02'               PACKED DECIMAL
DTCHAR   EQU   X'03'               CHARACTER
DTMIX    EQU   X'04'               MIXED CHARACTER
DTDBCS   EQU   X'05'               DBCS
DTNUM    EQU   X'06'               NUMERIC
DTUSRMIN EQU   X'50'               MINIMUM USER DATA TYPE
DTUSRMAX EQU   X'80'               MAXIMUM USER DATA TYPE
*
CNVDATAO DS    AL2                 DATA OFFSET
CNVDATAL DS    AL2                 DATA LENGTH
**
*
*        EQUATES FOR RESOURCE TYPES
*
CNVFC    EQU   X'01'               FILE CONTROL
CNVTS    EQU   X'02'               TEMP STORAGE
CNVTD    EQU   X'03'               TRANS DATA
CNVIC    EQU   X'05'               INTERVAL CONTROL
CNVPC    EQU   X'06'               PROGRAM CONTROL

Supplied user-replaceable conversion program

Figure 28 lists the version of DFHUCNV supplied with CICS TS for z/OS, Version 2.2 and later. Figure 29 lists the version of DFHUCNV supplied with all other CICS on System/390 products. Both versions are written in assembler.

The supplied version of DFHUCNV checks for a resource type of TS. If it finds one, it scans down the passed template looking for fields defined with a type in the user-data range. If any are present, DFHUCNV converts them as characters; you can rewrite the conversion code to your own requirements.

User-replaceable conversion program--CICS TS for z/OS, Version 2.2 and later, version
Figure 28. DFHUCNV, user-replaceable conversion program for CICS on System/390--CICS Transaction Server for Windows link. This is the CICS TS for z/OS, Version 2.2 and later, version.
*   MODULE NAME = DFHUCNV                                             
*                                                                     
* DESCRIPTIVE NAME = C.I.C.S./.......                                 
**       CICS TS for Windows USER CONVERSION SAMPLE PROGRAM           
**                                                                    
*                                                                     
* TRANSACTION NAME = Cxxx                                             
**       NOT A TRANSACTION                                            
*                                                                     
* STATUS =n.n.n                                                       
*                                                                     
* FUNCTION =                                                          
*        THIS IS A SAMPLE PROGRAM FOR USER DATA CONVERSION            
*        IT IS INVOKED AS A RESULT OF A FUNCTION                      
*        SHIPPED REQUEST OR RESPONSE VIA THE LU2 REMOTE SERVER        
*        OR LU6.2 HOST MIRROR PROGRAM. IT IS ACTUALLY  CICS           
*        LINKED FROM DFHCCNV TO ALLOW A USER PROGRAM TO               
*        CONVERT DATA OF TYPE USERDATA AS DEFINED IN THE              
*        CICS TS for Windows CONVERSION MACROS (DFHCNV).              
*                                                                     
*        THIS PROGRAM IS CALLED FOR EACH EXEC CICS REQUEST/RESPONSE   
*        FOR WHICH DATA EXISTS FOR CONVERSION FROM ASCII TO EBCDIC.   
*        IF A REQUEST DOES NOT CONTAIN ANY SUCH DATA, THIS PROGRAM    
*        IS NOT INVOKED. THE PROGRAM IS INVOKED BEFORE THE CICS       
*        CONVERSION PROGRAM (DFHCCNV) ATTEMPTS ANY CONVERSION         
*        INBOUND FROM CICS TS for Windows (ASCII TO EBCDIC) OR        
*        OUTBOUND FROM CICS TS for Windows (EBCDIC TO ASCII).         
*                                                                     
*        A COMMAREA IS  PASSED WITHIN WHICH IS A SERIES OF POINTERS   
*        TO INFORMATION THAT CAN BE USED BY THE PROGRAM TO            
*        DETERMINE HOW TO CONVERT ANY RELEVANT DATA. THIS PROGRAM     
*        SHOULD ONLY CONVERT DATA OF TYPE USERDATA AS INDICATED IN    
*        THE CONVERSION TEMPLATES. ANY DATA OF TYPE CHARACTER         
*        WILL BE CONVERTED BY THE CICS CONVERSION MODULE DFHCCNV.     
*                                                                     
*        SEE A LATER DESCRIPTION FOR WHAT THE SAMPLE DOES             
*                                                                     
* NOTES :
*    DEPENDENCIES = S/370
*        IN A CICS MVS/XA ENVIRONMENT, THIS PROGRAM SHOULD  BE
*          LINKED WITH RMODE(ANY) AND RMODE(31). ALL ADDRESSES SHOULD 
*          BE TREATED AS 31 BIT.                                      
*    RESTRICTIONS =                                                   
*          NONE                                                       
*    REGISTER CONVENTIONS =                                           
*          STANDARD EXEC                                              
*    PATCH LABEL = Via DFHPATCH macro                                 
*    MODULE TYPE = EXECUTABLE                                         
*    PROCESSOR = ASSEMBLER                                            
*    ATTRIBUTES = READ ONLY, SERIALLY REUSABLE                        
*                                                                     
* ENTRY POINT = DFHUCNV                                               
*                                                                     
*     PURPOSE =                                                       
*         THIS IS THE ONLY ENTRY POINT FOR ALL FUNCTIONS              
*                                                                     
*     LINKAGE =                                                       
*         EXEC CICS LINK FROM DFHCCNV IS THE ONLY WAY THIS PROGRAM    
*         IS INVOKED                                                  
*                                                                     
*     INPUT =                                                         
*         THE PARAMETERS ARE PASSED USING A COMMAREA AND THE          
*         DSECT DFHUNVDS DESCRIBES THE STRUCTURE OF THESE PARAMETERS  
*         THIS DSECT IS INCLUDED IN THIS PROGRAM BY ISSUING THE       
*         DFHCNV TYPE=DSECT MACRO CALL.                               
*                                                                     
*     OUTPUT =                                                        
*         NO SPECIFIC PARAMETERS  ARE RETURNED, AS THE PURPOSE OF     
*         THIS PROGRAM IS PERFORM CONVERSION ON USER DATA.            
*                                                                     
*     EXIT-NORMAL =                                                   
*         NORMAL RETURN IS VIA AN EXEC CICS RETURN                    
*                                                                     
*     EXIT-ERROR =                                                    
**        SAME AS EXIT NORMAL                                         
*                                                                     
*------------------------------------------------------------------ * 
*                                                                     
* EXTERNAL REFERENCES =                                               
*         NONE                                                        
*                                                                     
*     ROUTINES =                                                      
*         NONE                                                        
*                                                                     
*     DATA AREAS =                                                    
*         NONE                                                        
*                                                                     
*     CONTROL BLOCKS =                                                
*         THE 2 MAIN CONTROL BLOCKS REFERENCED ARE                    
*        DFHUNVDS                                                     
*         DESCRIBES THE PARAMETER LIST PASSED IN THE COMMAREA FROM    
*         DFHCCNV. IT IS BASICALLY CONSISTS OF A LIST OF POINTERS     
*         TO INFORMATION OF INTEREST TO THIS USER PROGRAM. THE FIRST  
*         PART OF THE LIST IS FIXED, AND THE SECOND PART CONSISTS     
*         OF OVERLAYS DEPENDING ON THE RESOURCE TYPE IN QUESTION.     
*        DFHCNVDS                                                     
*         DESCRIBES THE STRUCTURE OF INDIVIDUAL FIELDS IN THE         
*         PASSED TEMPLATE.                                            
*                                                                     
*     GLOBAL VARIABLES =                                              
*         NONE                                                        
*                                                                     
* TABLES =                                                            
*         DATA FROM THE DFHCNV TABLE IS USED BUT THE NECESSARY        
*         ADDRESSES ARE OBTAINED BY DFHCCNV AND PASSED IN THE         
*         COMMAREA                                                    
*                                                                     
* MACROS =                                                            
*         NONE                                                        
*                                                                     
*------------------------------------------------------------------ *  
*                                                                     
* DESCRIPTION                                                         
*    WHAT THIS SAMPLE DOES                                            
*                                                                     
*        DFHUCNV EXECUTES AS AN EXEC CICS PROGRAM.                    
*        DFHUCNV IS CALLED FOR ALL EXEC CICS REQUESTS/RESPONSES THAT  
*        HAVE RESULTED FROM A CICS TS for Windows FUNCTION SHIP REQUEST 
*        AND MAY REQUIRE CONVERSION OF USER DATA FROM ASCII TO EBCDIC 
*        OR VICE VERSA. THE FIRST THING THAT THE SAMPLE DOES IS TO    
*        OBTAIN ADDRESSABILITY TO THE PASSED COMMAREA, AND THEN       
*        CHECK THAT THE REQUEST IS A TEMPORARY STORAGE (TS) REQUEST.  
*        IF NOT WE JUST RETURN.                                       
*        NEXT WE CHECK IF DFHCCNV MANAGED TO LOCATE A CONVERSION      
*        TEMPLATE FOR THE RESOURCE (TS QUEUE) WITH THIS NAME.         
*        IF ONE WAS NOT FOUND (UNVDTMP IS ZERO) THIS MEANS THAT       
*        NO CONVERSION INFORMATION WAS PROVIDED (USING DFHCNV MACROS) 
*        FOR THIS RESOURCE. IN THIS CASE WE WILL NEVER BE ABLE TO     
*        LOCATE ANY USERDATA FIELDS, SO WE JUST RETURN.               
*        ASSUMING WE DID HAVE A TEMPLATE, WE NOW SCAN DOWN THE        
*        TEMPLATE USING THE SUPPLIED TEMPLATE PTR AND LENGTH. THE     
*        MAPPING OF THIS IS PROVIDED BY DFHCNVDS WHICH GIVES          
*        THE STRUCTURE OF THE CONSTITUENT FIELDS.                     
*        EACH FIELD IS EXAMINED, AND WHEN ONE OF TYPE USERDATA        
*        IS FOUND WE DO SOME FURTHER CHECKS AS FOLLOWS.               
*                                                                     
*        IT IS POSSIBLE THAT THE CONVERSION TEMPLATE HAS              
*        DEFINITIONS FOR OFFSETS (AND OFFSETS PLUS LENGTHS) THAT ARE  
*        GREATER THAN THE ACTUAL DATA ON THE EXEC REQUEST/RESPONSE.   
*        OBVIOUSLY IT IS VERY IMPORTANT TO DETERMINE THE LESSER OF    
*        THE ACTUAL DATA AND THE PARTICULAR TEMPLATE FIELD DEFINITION 
*        TO ENSURE WE DO NOT PERFORM CONVERSION OFF THE END OF THE    
*        REAL DATA. ONCE THESE CHECKS ARE DONE THE USERDATA FIELD     
*        CAN BE TRANSLATED AS APPROPRIATE. PURELY AS AN EXAMPLE,      
*        THE SAMPLE PROGRAM CONVERTS THE USERDATA FIELDS AS CHARACTER,
*        BUT IN A REAL PROGRAM, YOU WOULD PERFORM YOUR OWN SPECIAL    
*        TESTING AND CONVERSION AT THIS POINT.                        
*        THIS LAST STEP IS REPEATED FOR EACH FIELD IN THE TEMPLATE    
*        OF TYPE USERDATA, UNTIL THE END OF THE TEMPLATE IS FOUND,    
*        AT WHICH TIME A RETURN IS MADE TO THE CALLER (DFHCCNV).      
*                                                                     
*        WHEN WRITING A VERSION OF THIS PROGRAM TO EXECUTE IN A       
*        CICS MVS/XA ENVIRONMENT, YOU MUST BE PREPARED TO HANDLE      
*        ALL ADDRESSES AS POSSIBLY 31 BIT, AS DFHCCNV AND THE         
*        DFHCNV TABLE (CONTAINING THE TEMPLATES) WILL BE LOADED       
*        ABOVE THE 16M LINE.                                          
*                                                                     
*    CAVEAT                                                           
*                                                                     
*        FULLWORD VALUES ARE NOW PASSED IN THE FOLLOWING              
*        FIELDS:                                                      
*                                                                     
*          CNVDATAL                                                   
*          CNVDATAO                                                   
*                                                                     
*          UNVFCLNP                                                   
*          UNVFCKLP                                                   
*          UNVICLNP                                                   
*          UNVPCLNP                                                   
*          UNVTDLNP                                                   
*          UNVTSLNP                                                   
*                                                                     
*********************************************************************
         DFHCNV TYPE=DSECT                                             
DFHUCNV  CSECT                                                         
         B     IDBYP                                                   
         DFHVM UCNV,ENTRY=DFHUCNV,RMODE=ANY                        
IDBYP    DS    0H                                                      
         DFHREGS ,                                                     
         OC    EIBCALEN,EIBCALEN   ANY COMMAREA ?                      
         BZ    RETURN              NO, JUST RETURN                     
         L     R2,DFHEICAP                                             
         USING DFHUNVDS,R2         ADDRESSABILITY TO COMMAREA          
         L     R10,UNVRSTP         ADDRESS THE RESOURCE TYPE           
         CLI   0(R10),CNVTS        IS IT A TEMPORARY STORAGE TYPE      
         BNE   RETURN              NO, JUST RETURN                     
         ICM   R10,B'1111',UNVDTMP IS THERE A CONVERSION TEMPLATE ?    
         BZ    RETURN              NO, JUST RETURN                     
         USING DFHCNVDS,R10        ADDRESSABILITY TO CONVERSION RECS   
         L     R4,UNVDLNP                                              
         L     R5,0(0,R4)          GET TOTAL TEMPLATE LENGTH           
         AR    R5,R10              END OF TEMPLATE                     
PROCESS  DS    0H                                                      
         CR    R10,R5              HAVE WE REACHED THE END OF TEMPL
         BNL   RETURN              YES                                 
         CLI   CNVRTYPE,CNVTFLD    DOUBLE CHECK ITS A FIELD TYPE REC   
         BNE   RETURN              NO, BETTER RETURN                   
         CLI   CNVDATTY,DTUSRMIN   IN THE USER RANGE ?                 
         BL    NEXTREC             NO, TOO LOW                         
         CLI   CNVDATTY,DTUSRMAX   IN THE USER RANGE ?                 
         BH    NEXTREC             NO, TOO HIGH                        
         L     R4,UNVDIRP          CHECK THE TYPE OF CONVERSION        
         CLI   0(R4),CNVRQATE      ASCII TO EBCDIC REQUEST             
         BNE   TRYEBC              NO...                               
         L     R6,UNVATEP          YES, ADDRESS THE RELEVANT TABLE     
         B     CONT1                                                   
TRYEBC   DS    0H                  MUST BE EBCDIC TO ASCII           
         L     R6,UNVETAP          ADDRESS THE RELEVANT TABLE        
CONT1    DS    0H                                                    
*                                                                    
*        GET LOWER VALUE OF ACTUAL LENGTH AND POTENTIAL LENGTH       
*        INTO R4                                                     
         L     R4,UNVTSLNP                                           
         L     R4,0(0,R4)          PICK UP ACTUAL TS DATA LENGTH     
         LTR   R4,R4               JUST CHECK ITS POSITIVE           
         BNP   RETURN              IF NOT RETURN                     
         L     R7,CNVDATAO         GET THE OFFSET FROM THE TEMPLATE  
         CR    R7,R4               IS THE OFFSET PAST THE DATA       
         BNL   NEXTREC             YES, TRY THE NEXT RECORD          
         A     R7,CNVDATAL         ADD IN THE LENGTH(TEMPLATE)       
         CR    R7,R4               COMPARE OFFSET+LEN WITH REAL DATA 
         BH    LENOK                                                 
         LR    R4,R7                                                 
LENOK    DS    0H                                                    
*        HERE R4 SHOULD BE THE SMALLER OF THE 2 LENGTHS              
*        NOW CALCULATE THE  REAL LENGTH FOR CONVERSION               
         S     R4,CNVDATAO         SUBTRACT THE OFFSET               
         L     R7,UNVTSDP          ADDRESS ACTUAL DATA               
         A     R7,CNVDATAO         ....PLUS OFFSET                   
*                                                                    
*  R7 POINTS AT THE START OF WHERE WE TRANSLATE AND R4               
*  INDICATES THE LENGTH (ENSURING WE DONT GO FURTHER THAN THE       
*  ACTUAL DATA)                                                     
*                                                                   
TRANSMOR DS    0H                                                   
         CH    R4,=H'256'          AT LEAST 256 BYTES TO DO         
         BL    TRREST              NO                               
         TR    0(256,R7),0(R6)     TRANSLATE 256 BYTES              
         SH    R4,=H'256'          DECREMENT THE COUNT              
         AH    R7,=H'256'          INCREMENT THE POINTER            
         B     TRANSMOR            DO SOME MORE                     
TRREST   DS    0H                                                   
         LTR   R4,R4               ANY LEFT TO DO ?                 
         BNP   DONETR              NO                               
         SH    R4,=H'1'            DECREMENT THE COUNTER FOR THE TR 
         EX    R4,TRNSLT                                            
         B     DONETR                                               
TRNSLT   TR    0(0,R7),0(R6)                                        
DONETR   DS    0H                  ALL DATA TRANSLATED              
NEXTREC  DS    0H                                                   
         SR    R4,R4                                                
         IC    R4,CNVRLEN          GET LENGTH OF THIS RECORD        
         AR    R10,R4              AND ADDRESS THE NEXT ONE         
         B     PROCESS                                              
RETURN   DS    0H                                                   
         EXEC  CICS RETURN                                          
        END   DFHUCNV                                              
User-replaceable conversion program--non-CICS TS for z/OS, Version 2.2 and later, version
Figure 29. DFHUCNV, user-replaceable conversion program for CICS on System/390--CICS Transaction Server for Windows link. This is the version for all CICS on System/390 products other than CICS TS for z/OS, Version 2.2 and later.
*   MODULE NAME = DFHUCNV
* DESCRIPTIVE NAME = C.I.C.S./.......
**       CICS TS for Windows USER CONVERSION SAMPLE PROGRAM
*
* TRANSACTION NAME = Cxxx
**       NOT A TRANSACTION
*
*               5665-403
*
* STATUS = n.n.n
*
* FUNCTION =
*        THIS IS A SAMPLE PROGRAM FOR USER DATA CONVERSION
*        IT IS INVOKED AS A RESULT OF A FUNCTION
*        SHIPPED REQUEST OR RESPONSE VIA THE LU2 REMOTE SERVER
*        OR LU6.2 HOST MIRROR PROGRAM. IT IS ACTUALLY CICS
*        LINKED FROM DFHCCNV TO ALLOW A USER PROGRAM TO
*        CONVERT DATA OF TYPE USERDATA AS DEFINED IN THE
*        CICS TS for Windows CONVERSION MACROS (DFHCNV).
*
*        THIS PROGRAM IS CALLED FOR EACH EXEC CICS REQUEST/RESPONSE
*        FOR WHICH DATA EXISTS FOR CONVERSION FROM ASCII TO EBCDIC.
*        IF A REQUEST DOES NOT CONTAIN ANY SUCH DATA, THIS PROGRAM
*        IS NOT INVOKED. THE PROGRAM IS INVOKED BEFORE THE CICS
*        CONVERSION PROGRAM (DFHCCNV) ATTEMPTS ANY CONVERSION
*        INBOUND FROM CICS TS for Windows (ASCII TO EBCDIC) OR 
*        OUTBOUND FROM CICS TS for Windows (EBCDIC TO ASCII).
*
*        A COMMAREA IS PASSED WITHIN WHICH IS A SERIES OF POINTERS
*        TO INFORMATION THAT CAN BE USED BY THE PROGRAM TO
*        DETERMINE HOW TO CONVERT ANY RELEVANT DATA. THIS PROGRAM
*        SHOULD ONLY CONVERT DATA OF TYPE USERDATA AS INDICATED IN
*        THE CONVERSION TEMPLATES. ANY DATA OF TYPE CHARACTER
*        WILL BE CONVERTED BY THE CICS CONVERSION MODULE DFHCCNV.
*
*        SEE A LATER DESCRIPTION FOR WHAT THE SAMPLE DOES
*
* NOTES :
*    DEPENDENCIES = S/370
*          IN A CICS MVS/XA ENVIRONMENT, THIS PROGRAM SHOULD BE
*          LINKED WITH RMODE(ANY) AND RMODE(31). ALL ADDRESSES SHOULD
*          BE TREATED AS 31 BIT.
*    RESTRICTIONS =
*          NONE
*    REGISTER CONVENTIONS =
*          STANDARD EXEC
*    PATCH LABEL = Via DFHPATCH Macro
*    MODULE TYPE = EXECUTABLE
*    PROCESSOR = ASSEMBLER
*    ATTRIBUTES = READ ONLY, SERIALLY REUSABLE
* ENTRY POINT = DFHUCNV
*
*     PURPOSE =
*         THIS IS THE ONLY ENTRY POINT FOR ALL FUNCTIONS
*
*     LINKAGE =
*         EXEC CICS LINK FROM DFHCCNV IS THE ONLY WAY THIS PROGRAM
*         IS INVOKED
*
*     INPUT =
*         THE PARAMETERS ARE PASSED USING A COMMAREA AND THE
*         DSECT DFHUNVDS DESCRIBES THE STRUCTURE OF THESE PARAMETERS
*         THIS DSECT IS INCLUDED IN THIS PROGRAM BY ISSUING THE
*         DFHCNV TYPE=DSECT MACRO CALL.
*
*     OUTPUT =
*         NO SPECIFIC PARAMETERS ARE RETURNED, AS THE PURPOSE OF
*         THIS PROGRAM IS PERFORM CONVERSION ON USER DATA.
*
*     EXIT-NORMAL =
*         NORMAL RETURN IS VIA AN EXEC CICS RETURN
*
*     EXIT-ERROR =
**        SAME AS EXIT NORMAL
*
*------------------------------------------------------------------ *
*
* EXTERNAL REFERENCES =
*         NONE
*
*     ROUTINES =
*         NONE
*
*     DATA AREAS =
*         NONE
*     CONTROL BLOCKS =
*         THE 2 MAIN CONTROL BLOCKS REFERENCED ARE
*        DFHUNVDS
*         DESCRIBES THE PARAMETER LIST PASSED IN THE COMMAREA FROM
*         DFHCCNV. IT IS BASICALLY CONSISTS OF A LIST OF POINTERS
*         TO INFORMATION OF INTEREST TO THIS USER PROGRAM. THE FIRST
*         PART OF THE LIST IS FIXED, AND THE SECOND PART CONSISTS
*         OF OVERLAYS DEPENDING ON THE RESOURCE TYPE IN QUESTION.
*        DFHCNVDS
*         DESCRIBES THE STRUCTURE OF INDIVIDUAL FIELDS IN THE
*         PASSED TEMPLATE.
*
*     GLOBAL VARIABLES =
*         NONE
*
* TABLES =
*         DATA FROM THE DFHCNV TABLE IS USED BUT THE NECESSARY
*         ADDRESSES ARE OBTAINED BY DFHCCNV AND PASSED IN THE
*         COMMAREA
*
* MACROS =
*         NONE
*
*------------------------------------------------------------------ *
*
* DESCRIPTION
*    WHAT THIS SAMPLE DOES
*
*        DFHUCNV EXECUTES AS AN EXEC CICS PROGRAM.
*        DFHUCNV IS CALLED FOR ALL EXEC CICS REQUESTS/RESPONSES THAT
*        HAVE RESULTED FROM A CICS TS for Windows FUNCTION SHIP REQUEST
*        AND MAY REQUIRE CONVERSION OF USER DATA FROM ASCII TO EBCDIC OR
*        VICE VERSA. THE FIRST THING THAT THE SAMPLE DOES IS TO
*        OBTAIN ADDRESSABILITY TO THE PASSED COMMAREA, AND THEN
*        CHECK THAT THE REQUEST IS A TEMPORARY STORAGE (TS) REQUEST.
*        IF NOT WE JUST RETURN.
*        NEXT WE CHECK IF DFHCCNV MANAGED TO LOCATE A CONVERSION
*        TEMPLATE FOR THE RESOURCE (TS QUEUE) WITH THIS NAME.
*        IF ONE WAS NOT FOUND (UNVDTMP IS ZERO) THIS MEANS THAT
*        NO CONVERSION INFORMATION WAS PROVIDED (USING DFHCNV MACROS)
*        FOR THIS RESOURCE. IN THIS CASE WE WILL NEVER BE ABLE TO
*        LOCATE ANY USERDATA FIELDS, SO WE JUST RETURN.
*        ASSUMING WE DID HAVE A TEMPLATE, WE NOW SCAN DOWN THE
*        TEMPLATE USING THE SUPPLIED TEMPLATE PTR AND LENGTH. THE
*        MAPPING OF THIS IS PROVIDED BY DFHCNVDS WHICH GIVES
*        THE STRUCTURE OF THE CONSTITUENT FIELDS.
*        EACH FIELD IS EXAMINED, AND WHEN ONE OF TYPE USERDATA
*        IS FOUND WE DO SOME FURTHER CHECKS AS FOLLOWS.
*        IT IS POSSIBLE THAT THE CONVERSION TEMPLATE HAS
*        DEFINITIONS FOR OFFSETS (AND OFFSETS PLUS LENGTHS) THAT ARE
*        GREATER THAN THE ACTUAL DATA ON THE EXEC REQUEST/RESPONSE.
*        OBVIOUSLY IT IS VERY IMPORTANT TO DETERMINE THE LESSER OF
*        THE ACTUAL DATA AND THE PARTICULAR TEMPLATE FIELD DEFINITION
*        TO ENSURE WE DO NOT PERFORM CONVERSION OFF THE END OF THE
*        REAL DATA. ONCE THESE CHECKS ARE DONE THE USERDATA FIELD
*        CAN BE TRANSLATED AS APPROPRIATE. PURELY AS AN EXAMPLE,
*        THE SAMPLE PROGRAM CONVERTS THE USERDATA FIELDS AS
*        CHARACTER, BUT IN A REAL PROGRAM, YOU WOULD PERFORM YOUR
*        OWN SPECIAL TESTING AND CONVERSION AT THIS POINT.
*        THIS LAST STEP IS REPEATED FOR EACH FIELD IN THE TEMPLATE
*        OF TYPE USERDATA, UNTIL THE END OF THE TEMPLATE IS FOUND,
*        AT WHICH TIME A RETURN IS MADE TO THE CALLER (DFHCCNV).
*
*        WHEN WRITING A VERSION OF THIS PROGRAM TO EXECUTE IN A
*        CICS MVS/XA ENVIRONMENT, YOU MUST BE PREPARED TO HANDLE
*        ALL ADDRESSES AS POSSIBLY 31 BIT, AS DFHCCNV AND THE
*        DFHCNV TABLE (CONTAINING THE TEMPLATES) WILL BE LOADED
*        ABOVE THE 16M LINE.
*
*------------------------------------------------------------------ *
*
* CHANGE ACTIVITY :
**
*        $MOD(DFHUCNV),COMP(ISC),PROD(CICS/MVS)
*
*     PN= REASON REL YYMMDD HDXIII : REMARKS
*     P0= REASON REL YYMMDD HDXIII : Implicit flag.
*    $01  Reserved for APAR fix
*    $02  Reserved for APAR fix
*    $03  Reserved for APAR fix
*    $D1  Reserved for DCR
*    $D2  Reserved for DCR
*    $D3  Reserved for DCR
*    $H1  Reserved for hardware support
*    $H2  Reserved for hardware support
*    $H3  Reserved for hardware support
*    $L0         210 880722 HD1HSS : CREATE DFHUCNV
*    $L1  Reserved for line item
*    $L2  Reserved for line item
*    $L3  Reserved for line item
*    $P1  Reserved for PTM
*    $P2  Reserved for PTM
*    $P3  Reserved for PTM
*
***********************************************************
         DFHCNV TYPE=DSECT
DFHUCNV  CSECT
         B     IDBYP
         DFHVM UCNV,ENTRY=DFHUCNV
IDBYP    DS    0H
         DFHREGS ,
         OC    EIBCALEN,EIBCALEN   ANY COMMAREA ?
         BZ    RETURN              NO, JUST RETURN
         L     R2,DFHEICAP
         USING DFHUNVDS,R2         ADDRESSABILITY TO COMMAREA
         L     R10,UNVRSTP         ADDRESS THE RESOURCE TYPE
         CLI   0(R10),CNVTS        IS IT A TEMPORARY STORAGE TYPE?
         BNE   RETURN              NO, JUST RETURN
         ICM   R10,B'1111',UNVDTMP IS THERE A CONVERSION TEMPLATE ?
         BZ    RETURN              NO, JUST RETURN
         USING DFHCNVDS,R10        ADDRESSABILITY TO CONVERSION RECS
         L     R4,UNVDLNP
         SR    R5,R5
         LH    R5,0(0,R4)          GET TOTAL TEMPLATE LENGTH
         AR    R5,R10              END OF TEMPLATE
PROCESS  DS    0H
         CR    R10,R5              HAVE WE REACHED END OF TEMPLATE?
         BNL   RETURN              YES
         CLI   CNVRTYPE,CNVTFLD    DOUBLE CHECK ITS A FIELD TYPE REC
         BNE   RETURN              NO, BETTER RETURN
         CLI   CNVDATTY,DTUSRMIN   IN THE USER RANGE ?
         BL    NEXTREC             NO, TOO LOW
         CLI   CNVDATTY,DTUSRMAX   IN THE USER RANGE ?
         BH    NEXTREC             NO, TOO HIGH
         L     R4,UNVDIRP          CHECK THE TYPE OF CONVERSION
         CLI   0(R4),CNVRQATE      ASCII TO EBCDIC REQUEST
         BNE   TRYEBC              NO...
         L     R6,UNVATEP          YES, ADDRESS THE RELEVANT TABLE
         B     CONT1
TRYEBC   DS    0H                  MUST BE EBCDIC TO ASCII
         L     R6,UNVETAP          ADDRESS THE RELEVANT TABLE
CONT1    DS    0H
*
*        GET LOWER VALUE OF ACTUAL LENGTH AND POTENTIAL LENGTH
*        INTO R4
         L     R4,UNVTSLNP
         LH    R4,0(0,R4)          PICK UP ACTUAL TS DATA LENGTH
         LTR   R4,R4               JUST CHECK ITS POSITIVE
         BNP   RETURN              IF NOT RETURN
         LH    R7,CNVDATAO         GET THE OFFSET FROM THE TEMPLATE
         CR    R7,R4               IS THE OFFSET PAST THE DATA
         BNL   NEXTREC             YES, TRY THE NEXT RECORD
         AH    R7,CNVDATAL         ADD IN THE LENGTH(TEMPLATE)
         CR    R7,R4               COMPARE OFFSET+LEN WITH REAL DATA
         BH    LENOK
         LR    R4,R7
LENOK    DS    0H
*        HERE R4 SHOULD BE THE SMALLER OF THE 2 LENGTHS
*        NOW CALCULATE THE  REAL LENGTH FOR CONVERSION
         SH    R4,CNVDATAO         SUBTRACT THE OFFSET
         L     R7,UNVTSDP          ADDRESS ACTUAL DATA
         AH    R7,CNVDATAO         ....PLUS OFFSET
*
*  R7 POINTS AT THE START OF WHERE WE TRANSLATE AND R4
*  INDICATES THE LENGTH (ENSURING WE DON'T GO FURTHER THAN THE
*  ACTUAL DATA)
TRANSMOR DS    0H
         CH    R4,=H'256'          AT LEAST 256 BYTES TO DO
         BL    TRREST              NO
         TR    0(256,R7),0(R6)     TRANSLATE 256 BYTES
         SH    R4,=H'256'          DECREMENT THE COUNT
         AH    R7,=H'256'          INCREMENT THE POINTER
         B     TRANSMOR            DO SOME MORE
TRREST   DS    0H
         LTR   R4,R4               ANY LEFT TO DO ?
         BNP   DONETR              NO
         SH    R4,=H'1'            DECREMENT THE COUNTER FOR THE TR
         EX    R4,TRNSLT
         B     DONETR
TRNSLT   TR    0(0,R7),0(R6)
DONETR   DS    0H                  ALL DATA TRANSLATED
NEXTREC  DS    0H
         SR    R4,R4
         IC    R4,CNVRLEN          GET LENGTH OF THIS RECORD
         AR    R10,R4              AND ADDRESS THE NEXT ONE
         B     PROCESS
RETURN   DS    0H
         EXEC  CICS RETURN
         DFHPATCH
         END   DFHUCNV
 

Study the supplied version of DFHUCNV and its introductory comments. This will enable you to write your own conversion program. If you are running in an XA environment, your program must be able to handle 31-bit addresses.

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
Related tasks
Avoiding data conversion
Resource definition to enable data conversion
Defining the conversion table
Assembling and link-editing the conversion programs
Related reference
Where data conversion takes place
Character data
Defining the conversion table
[[ Contents Previous Page | Next Page Index ]]