z/OS ISPF Services Guide
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


VMASK—mask and edit processing

z/OS ISPF Services Guide
SC19-3626-00

The VMASK service associates an edit mask with a dialog variable defined with VDEFINE. The edit mask is a pattern used to validate input into that variable. The mask characters are stripped from the data before it is put into the function pool, or before the data is stored in a table from a TBDISPL. When the masked variable is displayed on a panel, stored in the shared or profile pool, or accessed by VCOPY, the output string contains the mask characters. When specifying the length to receive these variables on the VCOPY call, the length should be as long as the mask, not the defined variable. The length of the mask should also be considered when defining the field in which a masked variable is displayed.

The mask is only associated with the definition of the variable that was active when the VMASK was issued and cannot be used with implicit variables.

For example:
      VDEFINE VAR1         123        A
      VMASK   VAR1        (999)       A
      VDEFINE VAR1         123        B
      VCOPY   VAR1         123        B
      VDELETE VAR1                    B
      VCOPY   VAR1        (123)       A
 

The mask is associated with the A definition of VAR1, not the B definition.

When using a masked variable on a panel, you must issue a VEDIT in the processing section of the panel for that masked variable for the data to be accessible in the function pool. You must issue the VEDIT statement before any other panel statements that reference variables, (such as VPUT or VER). If you don't, the values in the pool will be unpredictable. The VEDIT statement indicates to ISPF that the data entered into the masked variable field should be verified and the mask stripped out. If you don't issue the VEDIT for each masked variable on the panel, the resulting data in the pool will be unpredictable.

The VMASK service is supported for programming languages. The variable must be VDEFINEd with FIXED, PACK, or CHAR formats.

VMASK call invocation

CALL ISPLINK ('VMASK   ',name-list{,'FORMAT  '{,'IDATE   '}    }
                                  {          {,'STDDATE '}    }
                                  {          {,'ITIME   '}    }
                                  {          {,'STDTIME '}    }
                                  {          {,'JDATE   '}    }
                                  {          {,'JSTD    '})   }
                                  {,'USER    ','mask',masklen)}

Parameters

name-list
Specifies the names of one or more dialog variables whose values are to be associated with a mask pattern.
FORMAT|USER
Identifies the type of mask to be associated with the dialog variable. FORMAT indicates that the mask is one of the predefined mask formats. USER indicates the mask will be user defined.
If FORMAT is specified, these keywords are predefined mask patterns that ISPF validates.
IDATE
This specifies a data type for which the format represents a date expressed in a 2-digit year (YY), month (MM), and day (DD).

The IDATE internal format used by the dialog variable contains 6 digits representing YYMMDD. The IDATE display format contains 8 characters, including the national language date delimiter character. For the U.S., the format is YY/MM/DD. For input only, ISPF ensures the resulting IDATE internal format value is a valid date. It ensures that the internal value for YY is 00-99, for MM is 01-12 and for DD is 01-31. Validation is also done to check the date for months with fewer than 31 days and for leap years.

STDDATE
This specifies a data type for which the format represents a date expressed in a 4-digit year (YYYY), month (MM) and day (DD).

The STDDATE internal format used by the dialog variable contains 8 digits representing YYYYMMDD. The STDDATE display format contains 10 characters including the national language date delimiter. For the U.S., the format is YYYY/MM/DD. For input only, ISPF ensures the resulting STDDATE internal value is a valid date. It ensures that the internal value for YYYY is 0000-9999, for MM is 01-12 and for DD is 01-31. Validation is also done to check the date for months with fewer than 31 days and for leap years.

ITIME
This specifies a data type for which the format represents time expressed in hours (HH) and minutes (MM).

The ITIME internal format used by the dialog variable contains 4 digits representing HHMM. The ITIME display format contains 5 characters including the national language time delimiter. For the U.S., the format is HH:MM. Hours are specified using the 24-hour clock. For input only, ISPF ensures the resulting ITIME internal value is a valid time. It ensures that the internal value for HH is 00-23 and for MM is 00-59.

STDTIME
This specifies a data type for which the format represents time expressed in hours (HH), minutes (MM) and seconds (SS).

The STDTIME internal format used by the dialog variable contains 6 digits representing HHMMSS. The STDTIME display format contains 8 characters including the national language time delimiter. For the U.S., the format is HH:MM:SS. Hours are specified using the 24-hour clock. For input only, ISPF ensures the resulting STDTIME internal value is a valid time. It ensures that the internal value for HH is 00-23, for MM is 00-59 and for SS is 00-59.

JDATE
This specifies a data type for which the format represents a date expressed in a 2-digit year (YY) and day of the year (DDD).

The JDATE internal format used by the dialog variable contains 5 digits representing YYDDD. The JDATE display format contains 6 characters in the format YY.DDD. For input only, ISPF ensures the resulting JDATE internal value is a valid date. It ensures that the internal value for YY is 00-99 and for DDD is 365. Validation is also done to check for leap years with 366 days.

JSTD
This specifies a data type for which the format represents a date expressed in a 4-digit year (YYYY) and day of the year (DDD).

The JSTD internal format used by the dialog variable contains 7 digits representing YYYYDDD. The JSTD display format contains 8 characters in the format is YYYY.DDD. For input only, ISPF ensures the resulting JSTD internal value is a valid date. It ensures that the internal value for YYYY is 0000-9999 and for DDD is 365. Validation is also done to check for leap years.

When a user enters a value for a variable with a type of either IDATE or STDDATE, it must be entered using the national language date format. It is a good idea to display an explanation of the expected format to the user so that the value is entered properly. ISPF verifies that the value entered is a valid date, and if no errors are found, the national language date format is converted to the internal format before the value is stored in the variable pool.

If USER is specified, these parameters must be defined:
mask
Identifies the mask pattern associated with the dialog variable.
A mask pattern can consist of 20 characters. These are valid mask symbols:
A
Any alphabetic character (A-Z, a-z)
B
A blank space
9
Any numeric character (0-9)
H
Any hexadecimal digit (0-9, A-F, a-f)
N
Any numeric or alphabetic character (0-9, A-Z, a-z)
V
Location of the assumed decimal point
S
The numeric data is signed
X
Any allowable characters from the character set of the computer
Special characters
( ) - / , .

The data represented by the B, V and special character symbols will be stripped before the data is put into the pool. The specified mask must contain at least one of the symbols A, 9, H, N, or X.

The S symbol must be in the first position to be accepted.

masklen
Specifies the length of the mask in bytes. The maximum length of the mask is 20. This parameter must be specified in a fullword fixed binary integer.

Return codes

These return codes are possible:
 0
Normal completion
 8
Variable not found
20
Severe error.

Example

In this example, a character variable (CVAR) is defined with a user-defined mask for a phone number. A fixed variable (FVAR) with a time format is specified.
 DECLARE
    FVAR   FIXED BIN(31),
    CVAR   CHAR(10),
    LENCHR FIXED BIN(31),
    LENFIX FIXED BIN(31),
    LENMSK FIXED BIN(31);

 LENCHR = 10;
 LENFIX = 4;
 CALL ISPLINK('VDEFINE ','(CVAR )',CVAR,'CHAR    ',LENCHR);
 CALL ISPLINK('VDEFINE ','(FVAR )',FVAR,'FIXED   ',LENFIX);
 LENMSK = 13;
 CALL ISPLINK('VMASK   ','(CVAR )','USER    ','(999)999-9999',LENMSK);
 CALL ISPLINK('VMASK   ','(FVAR )','FORMAT  ','ITIME   ');
 

The VEDIT statement

Use the VEDIT statement to verify mask data.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014