|
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.
|