Coding a nonstandard data conversion program

CICS® uses the COMMAREA to pass a parameter list to the user-replaceable conversion program that is providing access to the data conversion table and the data that is to be converted. All pointers point to an area in the COMMAREA.

The following lists and describes the parameters. The names shown are those that are used in the CICS-supplied sample header. A C language header file for these parameters is in: 
prodDir/include/cics_fscv.h
The C language source for the supplied version of DFHUCNV is in: 
prodDir/samples/ucnv/cics_fscv.ccs
Signature
This is the eight-character signature (ERZ27CVU) for the parameters that CICS passes to the user-conversion program.
ConvDir
CICS passes this 32-bit parameter to the user conversion program. The parameter indicates in which direction conversion should be performed, and has one of these two values:
  • 0 = Conversion from local to remote
  • 1 = Conversion from remote to local
ResourceName
This is the name of the resource, and is NULL if CICS has not initialized the conversion template.
ResourceNameLength
This is an unsigned 16-bit integer that specifies the length of the resource named. The length is zero if CICS does not initialize the conversion template.
ResourceT
This 32-bit parameter defines the type of resource that the user data conversion function can use as a key for obtaining a conversion template. It has one of these values:
  • 0 = file control
  • 1 = transient data
  • 2 = temporary storage
  • 3 = interval control
  • 4 = NOCHECK interval control
  • 5 = distributed program link (DPL)
UserData
This 32-bit parameter points to the user data for conversion. It might be NULL if no data exists for conversion.
UserDataLength
This is an unsigned 16-bit integer that specifies the length of the user data. The length is zero if no user data exists.
KeyData
This 32-bit parameter points to file control key data for conversion. It might be NULL if no key data exists for conversion.
KeyDataLength
This is an unsigned 16-bit integer that specifies the length of key data. The length is zero if no key data exists.
LocalToRemote
This is a code page descriptor for conversion from the local code page to the remote code page.
RemoteToLocal
This is a code page descriptor for conversion from the remote code page to the local code page.
ByteOrder
The byte ordering of the remote system. (See Numeric data conversion considerations for further details about byte ordering.)
  • 0 = Byte order for IBM® mainframes, , HP-UX

    (Called Network order, or Big Endian order

  • 1 = Byte order for OS/2 and Windows Systems

    (Called Little Endian)

ConvTable
This is a pointer to the root of a linked list that details selected data from the conversion template for the resource. Each element in the list contains the root of a linked list of field data for the conversion template. All elements in the linked lists are for input only and should not be modified. The linked list of data for a conversion template consists of:
Signature
This is the eight-character signature (“ERZ27CVS”) for the structure.
Next
This is a pointer to the next select element in the linked list. It is set to NULL if it is at the end of the list.
SelectType
This 32-bit parameter specifies the type of select. Refer to the following values:
  • 0 = Default. OPTION=DEFAULT has been specified.
  • 1 = Data. Indicates that the data to compare is in character format.
  • 2 = Hex Data. Indicates that the data is to be compared without conversion.
  • 3 = Key. Indicates the start of conversions that are to be applied to file control keys.
CompareOffset
This is an unsigned 16-bit integer that specifies the offset, from the start of the data area, at which the comparison is to begin.
CompareLength
This is an unsigned 16-bit integer that specifies the length of the comparison data.
CompareData
This is a pointer to the data that is to be compared against.
FieldRoot
This is a pointer to the root of a linked list of field data for a conversion template. It describes what to convert if a match was found and is part of a linked list such that several conversions can be made. This field data consists of:
Signature
This is the eight-character signature (“ERZ27CVF”) for the structure.
Next
This is a pointer to the next conversion template element. It contains NULL if it is at the end of the list.
ConversionOffset
This is an unsigned 16-bit integer that specifies the offset, from the start of the data, at which the conversion is to begin.
ConvertType
This 32-bit parameter specifies the type of data to convert, and has one of these seven values:
  • 0 = Data is character. Convert as a character, using the iconv library.
  • 1 = Data is graphic (DBCS string without SOSI characters).
  • 2 = No conversion required.
  • 3 = User data.
  • 4 = Data is 16-bit numeric.
  • 5 = Data is 32-bit numeric.
ConvertLength
This is an unsigned 16-bit integer that specifies the length of the conversion data.
UserEscapeType
This is the user escape type unsigned 16-bit integer that is passed to DFHUCNV.