Ask User for Date (ASKDATE)

The Ask User for Date (ASKDATE) command prompts the end-user for a date or date range. Controls are provided that allow the programmer to modify the prompt text for each component on the screen, along with whether one or two dates are prompted. When two dates are prompted, the user is instructed to type in a Date Range, when one date is prompted the user is instructued to type in a valid date.

Restrictions:

This command may be run only within a CL program.

Parameters

Keyword	Description	Choices	Notes
DATFMT	Format of user entered date	JOB, YMD, DMY, MDY, ISO, USA, JIS, MMYYYY, MMYY, YYYYMM, *YYMM	Optional, Positional 1
RTNSEP	DATSEP added to return date(s)	NONE, DATFMT, *DATSEP	Optional, Positional 2
DATE	Date 1	Element list	Optional, Positional 3
	Element 1: Initial value	Date, JOB, SYS, BOM, PREVEOM, EOM, BLANKS
	Element 2: Prompt Text	Character value, *DFT
DATE2	Date 2	Single values: NONE Other values: Element list*	Optional, Positional 4
	Element 1: Initial value	Date, JOB, FROMDATE, SYS, BOM, PREVEOM, EOM, *BLANKS
	Element 2: Prompt text	Character value, *DFT
TITLE	Dialog titles	Element list	Optional, Positional 5
	Element 1: Main Title	Character value, *DFT
	Element 2: Subtitle line 1	Character value, *DFT
	Element 3: Subtitle line 2	Character value, *DFT
	Element 4: Title for "type dates..."	Character value, *DFT
RTNDATE	CL var for returned date	Not restricted	Optional, Positional 6
RTNFMT	Format of returned date	Character value, JOB, JOB0, MDY, MDY0, DMY, DMY0, YMD, YMD0, JUL, MDYY, DMYY, YYMD, CYMD, ISO, USA, EUR, *JIS	Optional, Positional 7
RTNDATE2	CL var for 2nd returned date	Not restricted	Optional, Positional 8
RTNFMT2	Format of 2nd returned date	Character value, FMT1, JOB, JOB0, MDY, MDY0, DMY, DMY0, YMD, YMD0, JUL, MDYY, DMYY, YYMD, CYMD, ISO, USA, EUR, JIS	Optional, Positional 9
RTNMM	CL Var for returned Month	Decimal number	Optional, Positional 10
RTNYY	CL Var for returned Year	Decimal number	Optional, Positional 11
RTNMM2	CL Var for returned Month 2	Decimal number	Optional, Positional 12
RTNYY2	CL Var for returned Year 2	Decimal number	Optional, Positional 13
RTNFKEY	CL Variable for Fn Key pressed	Character value	Optional, Positional 14

Top

Date format (DATFMT)

Specifies format for the date(s) being typed in by the end-user. The date prompt is always 10 positions in length, however the date format controls the validity checking performed on the date entered by the end-user.

*JOB: The date must be entered by the end-user in *JOB format.
*YMD: The date must be entered by the end-user in YYMMDD format.
*MDY: The date must be entered by the end-user in MMDDYY format.
*DMY: The date must be entered by the end-user in DDMMYY format.
*ISO: The date must be entered by the end-user in YYYYMMDD format.
*USA: The date must be entered by the end-user in MMDDYYYY format.
*EUR: The date must be entered by the end-user in DDMMYYYY format.
*JIS: The date must be entered by the end-user in YYYYMMDD format.
*MMYYYY: The date must be entered by the end-user as a 2-digit month and a 2- or 4-digit year.
*MMYY: The date must be entered by the end-user as a 2-digit month and a 2-digit year.

Returned Date Separator (RTNSEP)

Specify an override to the date separator for dates values returned by the command. This parameter is ignored when the CL variable for the returened date is numeric. Use this parameter to override the default date separator character for the specified RTNFMT (Return Date Format). For example, when a value of RTNFMT(*MDY) is specified, the default returned separator is the slash symbol, so a date of MM/DD/YY is returned when a *CHAR CL variable is specified. Specifying a date format of RTNFMT(*MDY0) returns MMDDYY instead. However, when RTNSEP(*NONE) is specified, all date formats are overriden to include a no-separator option. That is the 0 is appended to the date format code.

*NONE: The date format is overriden to return no date separators.
*FMT or *DATSEP: The date format is not overriden. Whatever RTNFMT and RTFMT2 are specified will be used by the command.

Date 1 (DATE)

Specifies value and properties for the first (or only) date value.

Element 1: Initial value

*JOB: The initial date value is set to the job date.
*EOM: The initial date value is set to the end of the month date of the current month.
*PREVEOM: The initial date value is set to the last day of the previous month.
*BOM: The initial date value is set to the 1st of the current month.
*BLANKS: The initial date value is empty ("blanks").
date: Specify the initial date value to be displayd in the first (or only) date field.

Element 2: Prompt Text

*DFT: The text that appears to the left of the date field is set to the system default prompt text.
character-value: Specify the user-specified text that appears to the left of the first (or only) date value.

Date 2 (DATE2)

Specifies the properties of the second date when a date range is requested.

Single values

*NONE: No second date is requested. The single date is prompted.

Element 1: Initial value

*JOB: Then job date is used as the initial value for the second ("TO") date and a date range is prompted.
*EOM: Then end of month date of the current month is used as the initial value for the second ("TO") date and a date range is prompted.
*BLANKS: The second ("TO") date is initially blank and a date range is prompted.
*FROMDATE: The same value as the first date is used as the initial value for the second ("TO") date and a date range is prompted.
date: Specify the initial date value for the second ("TO") date. When a date is specified, a date range is prompted.

Element 2: Prompt text

*DFT: The text that appears to the left of the date field is set to the system default prompt text.
character-value: Specify the text that appears to the left of the date field.

Dialog titles (TITLE)

Specifies the title and subtitle text that appears in the popup window for the date prompter.

Element 1: Main Title

*DFT: The default dialog prompt text appears in the Title bar of the popup window.
character-value: Specify the title text that appears in the Title bar of the popup window.

Element 2: Subtitle line 1

*DFT: The system default text appears on the first line of the window body. This is used as a Subtitle.
character-value: The text that appears on the first subtitle line of the window body. This is used as a Subtitle.

Element 3: Subtitle line 2

*DFT: The system default text (blanks) appears on the second subtitle line.
character-value: Specify the text that appears on the second subtitle line.

CL Variable for Date 1 (RTNDATE2)

Specify a CL variable that receives the 2nd date that was typed into the prompt by the end-user. If no 2nd date is prompted, no value is returned to this parameter.

CL variable: Specify a CL variable that receives the first (or only) date from the prompt. The date is returned in the format specified on the RTNFMT2 parameter.

Return Date Format (RTNFMT2)

Specify the format for the date value returned on the RTNDATE parameter.

Date Format: Specify any valid date format for the returned date value (returned to the RTNDATE parameter. The default *FMT, indicates that the format is the same as that specified on the RTNFMT parameter. *FMT *JOB *MDY *DMY *YMD *JUL *MDYY *DMYY *YYMD *CYMD *ISO *USA *EUR *JIS

CL Variable for Month (RTNMM)

Specify a CL variable with a LEN(2 0) TYPE(*DEC) that receives the month from the Date. If *MMYY or *MMYYYY are specified as the date format, the month returned is the month portion. If another date format is requested, the month returned to this variable is extracted from the Date entered by the User.

character-value: Specify the CL variable TYPE(*DEC) Len(2 0) to receive the month.

CL Variable for Year (RTNYY)

Specify a CL variable with a LEN(4 0) TYPE(*DEC) that receives the Year from the Date. If *MMYY or *MMYYYY are specified as the date format, the Year returned is the Year portion. If another date format is requested, the Year returned to this variable is extracted from the Date entered by the User. If the return format is *MMYY the returned value is a 2-digit year. Other other date formats return a 4-digit year.

character-value: Specify the CL variable TYPE(*DEC) Len(4 0) to receive the Year.

CL Variable for Fn Key pressed (RTNFKEY)

Specify a CL variable Type(*CHAR) Len(1) that receives the Attention Identification Byte (Fkey) used to return from the ASKDATE prompt. This value is also set in the IBM Function Key Area and may be retrieved using the COZTOOLS RTVEXITKEY command.

character-value: Specify the TYPE(*CHAR) LEN(1) CL variable to receive the Fn Key used to return control from the ASKDATE application. The possible return values are: F3=X'3C' F12=X'33' Enter=X'F1'

Examples for ASKDATE

Example 1: Simple Command Example

ASKDATE  KWD1(PARMVAL1)

This command <...>

Example 2: More Complex Command Example

ASKDATE   KWD1(PARMVAL1)  KWD2(PARMVAL2)
          KWD3(PARMVAL3)

This command <...>

Error messages for ASKDATE

*ESCAPE Messages

CPF9801: Object &2 in library &3 not found.
CPF9802: Not authorized to object &2 in &3.
CPF9803: Cannot allocate object &2 in library &3.
CPF9807: One or more libraries in library list deleted.
CPF9808: Cannot allocate one or more libraries on library list.
CPF9810: Library &1 not found.
CPF9811: Program &1 in library &2 not found.
CPF9812: File &1 in library &2 not found.
CPF9820: Not authorized to use library &1.
CPF9830: Cannot assign library &1.
CPF9899: Error occurred during processing of command.