This section describes the user-replaceable data conversion program.
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:
where userprogram is the name of the user-supplied conversion program.
.
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.
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:
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:
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:
The overlay section depends on resource type:
TS requests:
TD requests:
IC requests:
PC requests:
FC requests:
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
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.
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.
For CICS TS for z/OS, Version 2.2 and later, a field conversion record has the following layout:
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:
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'.
Note that DFHCNVDS contains EQUATEs that are useful in your conversion program, as follows:
CNVFC FILE CONTROL
CNVTS TEMPORARY STORAGE
CNVTD TRANSIENT DATA
CNVIC INTERVAL CONTROL
CNVPC PROGRAM CONTROL
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
*
* 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
*
* 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
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.
* 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
* 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.