User Defined Conversion Codes (U)

 Top  Previous  Next

 

Users may add their own conversion codes to the system by writing a QMBasic subroutine to perform the conversion. Pick style user exits are provided in this way.

 

The format of the conversion code is

 

Usubrname

or

Usubrname.extension

 

where

 

subrnameis the catalogue name of the subroutine to be called. To allow creation of substitutes for Pick user exits, this name may commence with a digit.

 

extensionis optional qualifying information for the conversion code. This can be accessed within the subroutine in the @CONV variable. The separator before the extension may be a period, a comma or a semicolon.

 

 

The subroutine should have four arguments:

 

subrname(result, src, status, oconv)

 

where

 

subrnameis the name of the subroutine. This is the same as the conversion code but with the U prefix removed. If the name is less than four characters and is formed from hexadecimal characters, it is padded with leading zeroes to be four characters.

 

resultshould be set to the result of the conversion.

 

srcis the item to be converted.

 

statusis the value to be set for the STATUS() function. This defaults to 1 if not updated by the subroutine.

 

oconvindicates whether this is an input (0) or output (1) conversion.

 

 

 

User Exits

 

See the U50BB subroutine in the BP file of the QMSYS account for an example of a Pick user exit routine. There are many other user exit functions in this file though it is recommended that their use should be replaced by the equivalent in-line code when migrating an application to QM.

 

 

Handling Undefined Conversion Codes

 

The U conversion code prefix is primarily intended for emulation of the "user exits" found in Pick style systems. QM provides a more generalised mechanism for handling undefined conversion codes. If a conversion is attempted using a conversion code that QM does not recognise, including U codes for which there is no catalogued handler, it will check for the presence of a catalogued function named UNDEFINED.CONV. If this is present, it is called in a similar manner to the user exit handlers described above but with an fifth argument that contains the conversion code.

 

UNDEFINED.CONV(result, src, status, oconv, conv.code)

 

where

 

 

Example

 

The following example subroutine implements a UDT conversion code which converts a combined date/time value as returned by SYSTEM() with key 1005 (SYS$TIMESTAMP) to a text representation or vice versa.

 

SUBROUTINE DT(RESULT, SRC, STATE, IS.OCONV)

  IF SRC = '' THEN

     RESULT = ''

  END ELSE IF IS.OCONV THEN

     D = IDIV(SRC, 86400)

     T = REM(SRC, 86400)

     RESULT = OCONV(D, 'D2/DMY') : ' ' : OCONV(T, 'MTS')

  END ELSE

     D = FIELD(SRC, ' ', 1)

     T = FIELD(SRC, ' ', 2)

     RESULT = ICONV(D, 'D2/DMY') * 86400 + ICONV(T, 'MTS')

  END

  STATE = 0

  RETURN

END