DB2 Server for VM: System Administration

Coding Your Own TRANSPROC Exit

+---------------------General-Use Programming Interface----------------------+

The TRANSPROC exit is a General-Use programming interface. General-Use programming interface is defined in Programming Interface Information.

The TRANSPROC exit is used for DBCS conversion. The database manager converts DBCS characters from one DBCS CCSID to another by using the value specified in the TRANSPROC column of the SYSTEM.SYSSTRINGS catalog table. This conversion can be performed when the CCSID of the source and the target are both mixed or are both graphic; that is, the TRANSTYPE column of SYSTEM.SYSSTRINGS has a value of 'PM', 'MM', or 'GG'.

The TRANSPROC exit is also used

• for EUC conversion, to convert MBCS data to mixed data. In EUC conversions, the TRANSTYPE column is either 'PM', or 'GG'.
• to convert Unicode data to CCSIDs that are supported on the database manager. For Unicode to host conversions, the TRANSTYPE column is one of 'US', 'UM' 'UG', or 'UI'.

If you have created your own DBCS CCSIDs, you must create your own conversion routine. To do so:

1. Compile, link-edit and GENMOD your routine to create a MODULE file, and store the module on the production disk.
2. Insert the name of the phase in the TRANSPROC column of the row for which you want either mixed-to-mixed or graphic-to-graphic conversion. (For example, you could create and run a DBSU job to perform this task.)
3. Stop the application server.
4. Run ARISPROD WRITE to be sure you have write access to the production disk.
5. Run the ARISDBMA EXEC with component CCSID. Copy the three CMS files over to the production minidisk, changing their file type from "FLATFILE" to "MACRO". See the DB2 Server for VM Program Directory for information on the ARISDBMA EXEC.
6. Restart the application server.
7. All users must reaccess the production minidisk.

The interface between the database manager and a DBCS conversion routine supplied by a user must conform to the following:

• Register conventions:
  • Register 0 is undefined.
  • Register 1 contains the address of the control block that contains the parameters.
  • Registers 2--12 are undefined.
  • Register 13 contains the address of a standard register save area.
  • Register 14 contains the return address.
  • Register 15 contains the address of the user routine.

  Registers 2 to 13 must be saved and restored by the routine. If this is not done, the results are unpredictable.

• Parameter list, which is in the following form:
  • Address of the data to be converted (4 bytes)
  • Address of the target for the converted data (4 bytes)
  • Size of the source data (2 bytes)
  • Size of the target area (2 bytes)
  • Return code of the routine (4 bytes).

The TRANSPROC is called in the AMODE that the database manager is running in. If the TRANSPROC does not support 31-bit addressing, the database manager must be started with the AMODE(24) parameter. If the database manager is running in AMODE(24), the load module for the TRANSPROC must be generated with RMODE 24.

The database manager ensures that the size of the target area is at least as large as that of the source data, and that the size of the source data is always an even number. The routine supplied by the user should only convert the source data and put it in the target area. The database manager should do all other operations, such as padding the target area after data conversion is complete. You should also ensure that the routine supplies a nonzero return code if the conversion fails. The routine that you code should not have the same name as any of the defaults supplied by the database manager for the TRANSPROC column. Figure 115 shows the shell for a TRANSPROC routine.

Figure 115. TRANSPROC Shell

TITLE 'DBCSCONV' *********************************************************************** * DBCSCONV USER DBCS CONVERSION ROUTINE * REGISTER ASSUMPTIONS: * R1 -> PARMLIST * R13 -> SAVE AREA * R14 -> RETURN ADDRESS * R15 -> ENTRY POINT * * THIS ROUTINE SHOWS THE INTERFACE TO DB2 Server for VM *********************************************************************** DBCSCONV CSECT , DBCSCONV AMODE 31 DBCSCONV RMODE ANY USING *,R15 ESTABLISH TEMP ADDRESSABILITY B PROLOG BRANCH TO START OF PROGRAM DC C'DBCSCONV' DROP R15 DROP R15 AND USE OWN ADDRESSABILITY PROLOG STM R14,R12,12(R13) SAVE REGS IN CALLER'S AREA LR R12,R15 SAVE BASE REGISTER PSTART EQU DBCSCONV START OF PROGRAM USING PSTART,R12 SET UP BASE REGISTER L R1,0(R1) POINT TO PARAMETER LIST USING PARMLIST,R1 ADDRESSABILITY FOR INPUT PARMS   *********************************************************************** * M A I N L I N E *********************************************************************** MAINLINE DS 0H START OF CODE SPACE *********************************************************************** * HERE YOU PLACE THE CODE THAT CONVERTS THE INPUT DBCS STRING AND * PLACES THE CONVERTED STRING IN THE TARGET AREA. * A NONZERO RETURN CODE INDICATES AN ERROR. *********************************************************************** RETURN DS 0H RETURN POINT L R14,12(,R13) RESTORE R14 LM R0,R12,20(R13) RESTORE REST OF CALLER'S REGS BR R14 RETURN TO CALLER EJECT PARMLIST DSECT , INPUT PARAMETER LIST INPTR DS F POINTER TO INPUT STRING OUTPTR DS F POINTER TO TARGET AREA INLEN DS H LENGTH OF INPUT STRING OUTLEN DS H SIZE OF TARGET AREA RC DS F RETURN CODE EJECT DBCSCONV CSECT , R0 EQU 00 EQUATES FOR REGISTERS 0-15 R1 EQU 01 R2 EQU 02 R3 EQU 03 R4 EQU 04 R5 EQU 05 R6 EQU 06 R7 EQU 07 R8 EQU 08 R9 EQU 09 R10 EQU 10 R11 EQU 11 R12 EQU 12 R13 EQU 13 R14 EQU 14 R15 EQU 15 END DBCSCONV

+------------------End of General-Use Programming Interface------------------+