HMASK: Extracting Date-Time Components and Preserving Remaining Components

How to:

Reference:

Available Languages: reporting, Maintain

The HMASK function extracts one or more components from a date-time value and moves them to a target date-time field with all other components of the target field preserved.

Syntax: How to Move Multiple Date-Time Components to a Target Date-Time Field

HMASK(source, 'componentstring', input, length, output)

where:

source

Is the date-time value from which the specified components are extracted.

componentstring

Is a string of codes, in any order, that indicates which components are to be extracted and moved to the output date-time field. The following table shows the valid values. The string is considered to be terminated by any character not in this list:

Code

Description

C

century (the two high-order digits only of the four-digit year)

Y

year (the two low-order digits only of the four-digit year)

YY

Four digit year.

M

month

D

day

H

hour

I

minutes

S

seconds

s

milliseconds (the three high-order digits of the six-digit microseconds value)

u

microseconds (the three low-order digits of the six-digit microseconds value)

m

All six digits of the microseconds value.

n

Low order three digits of nine decimal digits.

input

Is the date-time value that provides all the components for the output that are not specified in the component string.

length

Is the length of the returned date-time value. Valid values are:

  • 8 indicates a time value that includes one to three decimal digits (milliseconds).
  • 10 indicates a time value that includes four to six decimal digits (microseconds).
  • 12 indicates a time value that includes seven to nine decimal digits (nanoseconds).
output

Is the field that contains the result, or the format of the output value enclosed in single quotation marks. This field must be in date-time format (data type H).

Reference: Usage Notes for the HMASK Function

HMASK processing is subject to the DTSTRICT setting. Moving the day (D) component without the month (M) component could lead to an invalid result, which is not permitted if the DTSTRICT setting is ON. Invalid date-time values cause any date-time function to return zeros.

Example: Changing a Date-Time Field Using HMASK

The VIDEOTRK data source has a date-time field named TRANSDATE of format HYYMDI. The following request changes any TRANSDATE value with a time component greater than 11:00 to 8:30 of the following day. First the HEXTR function extracts the hour and minutes portion of the value and compares it to 11:00. If it is greater than 11:00, the HADD function calls HMASK to change the time to 08:30 and adds one day to the date:

DEFINE FILE VIDEOTR2
ORIG_TRANSDATE/HYYMDI = TRANSDATE;
TRANSDATE =
IF HEXTR(TRANSDATE, 'HI', 8, 'HHI') GT DT(12:00)
   THEN HADD (HMASK(DT(08:30), 'HISs', TRANSDATE, 8, 'HYYMDI'), 'DAY',
    1,8, 'HYYMDI')
   ELSE TRANSDATE;
END
 
TABLE FILE VIDEOTR2
PRINT ORIG_TRANSDATE TRANSDATE
BY LASTNAME
BY FIRSTNAME
WHERE ORIG_TRANSDATE NE TRANSDATE
END

The output is

LASTNAME         FIRSTNAME   ORIG_TRANSDATE    TRANSDATE       
--------         ---------   --------------    ---------       
BERTAL           MARCIA      1999/07/29 12:19  1999/07/30 08:30
GARCIA           JOANN       1998/05/08 12:48  1998/05/09 08:30
                             1999/11/30 12:12  1999/12/01 08:30
PARKER           GLENDA      1999/01/06 12:22  1999/01/07 08:30
RATHER           MICHAEL     1998/02/28 12:33  1998/03/01 08:30
WILSON           KELLY       1999/06/26 12:34  1999/06/27 08:30