Miscellaneous Tools

Go back to main page of project i5/OS Programmer's Toolkit .

Tools and utilities that are hard to be categorised are listed as the following:

The CVTHC Program

The CVTHC Program

Like its MI cousin (the CVTHC (Convert Hex to Charater) instruction), the CVTHC program converts each hex digit (4-bit value) in the source character string to a character (8-bit value) in the receiver character string. It's a tiny OPM MI program which contains only 18 OPM MI instructions. The source of the CVTHC program is cvthc.emi.

The reason of the CVTHC program's birth is quite simple, it is handy for an OPM or ILE HLL program to convert a hexadecimal value to character format. The CVTHC MI instruction cannot be used in a bound program (an ILE program). Also, an OPM HLL program cannot use MI instructions, and hence cannot utilize the CVTHC instruction. Although service program QSYS/QC2UTIL1 exports a procedure, cvthc, that implements the functionality of the CVTHC instruction, the cvthc procedure is really inconvenient to use, since the user must bind to *SRVPGM QSYS/QC2UTIL1 directly or indirectly via the *BNDDIR QSYS/QC2LE. While, using the CVTHC program in a ILE HLL program is convenient, you need to do nothing but an external program call.

The CVTHC program has three parameters:

[out] Receiver character string
[in] Source character string
[in] bin(4). Length in nibbles of source

The following are pieces of HLL programs that utilize the CVTHC program.

An OPM CL program that uses the CVTHC program to convert a 2-byte MI object type/subtype code to a character string.

   DCL        VAR(&MITYP) TYPE(*UINT) LEN(2) VALUE(X'1901')
   DCL        VAR(&MSG) TYPE(*CHAR) LEN(16)
   DCL        VAR(&NIBLEN) TYPE(*UINT) LEN(4) VALUE(4)
   CALL       PGM(CVTHC) PARM(&MSG &MITYP &NIBLEN)

In ILE CL program, cl001.clle, the CVTHC program is used to convert the UUID generated by the GENUUID instruction into character format.

             PGM
             DCL        VAR(&TMPL) TYPE(*CHAR) LEN(32)
             DCL        VAR(&LEN) TYPE(*UINT) LEN(4) VALUE(32)
             DCL        VAR(&BYTESIN) TYPE(*INT) STG(*DEFINED) +
                          LEN(4) DEFVAR(&TMPL)
             DCL        VAR(&BYTESOUT) TYPE(*INT) STG(*DEFINED) +
                          LEN(4) DEFVAR(&TMPL 5)
             DCL        VAR(&UUID) TYPE(*CHAR) STG(*DEFINED) LEN(16) +
                          DEFVAR(&TMPL 17)
             DCL        VAR(&MSG) TYPE(*CHAR) LEN(32)
             DCL        VAR(&NIBLEN) TYPE(*UINT) LEN(4) VALUE(32)

             CALLPRC    PRC('_PROPB') PARM((&TMPL *BYREF) (X'00' +
                          *BYVAL) (&LEN *BYVAL))
             CHGVAR     VAR(&BYTESIN) VALUE(&LEN)
             CALLPRC    PRC('_GENUUID') PARM((&TMPL *BYREF))
             CALL       PGM(CVTHC) PARM(&MSG &UUID &NIBLEN)

             SNDPGMMSG  MSG(&MSG)
             ENDPGM

ILE COBOL program cbl002.cblle does the same thing as ILE CL program cl001.clle.

       process
           NOMONOPRC.

       id division.
       program-id. cbl002.

       environment division.
       configuration section.
       special-names.
           copy mih-lnktyp.

       data division.
       working-storage section.
           copy mih-spt.
       01 result pic x(32).
       01 tmpl   type uuid-t.
       01 uuid-len pic 9(9) usage comp-4 value 32.

       procedure division.
       main-pgm.

           move all x"00" to tmpl.
           move 32 to bytes-in of tmpl.
           call "_GENUUID" using
               by reference tmpl.

           call program "CVTHC" using
               by reference result
               by reference uuid of tmpl
               by reference uuid-len.
           display "UUID generated: " result.

       see-you.
           stop run.