The PMTOPR command places a prompt on the users display and allows
validity checking of the response. This is useful in some
environments where a specific input value is needed before proceeding
into some further processing (e.g. some System System Operator
functions). The prompt is always made to the requester (the command
must occur from an interactive program).
The advantage of this command is::
** PMTOPR can simplify the amount of code needed to validate the
entry of a parameter. The coding required to properly use
SNDUSRMSG includes checking for a blank entry, additional
processing for simple validations and looping back on an error
etc. is not simple.
** PMTOPR can provide a standard means of communicating with the
operator when a single value is needed.
For a simpler version, see the PMTOPR2 tool.
For example, the programmer could specify in a CL Program:
DCL &RTNVAR *CHAR LEN(16)
.
.
PMTOPR RTNVAR(&RTNVAR) +
LEN(10) +
PROMPT('Enter the file name to be processed +
by the BILLING function') +
TYPE(*NAME)
OVRDBF INPUT TOFILE(&RTNVAR)
CALL ....
The following shows the prompt which would appear to the operator
********************************************************************
* *
* Prompt Operator 3/17/09 *
* *
* Enter the file name to be processed by the BILLING function *
* *
* *
* __________ *
* *
* Validation performed *
* *
* Must be a valid name *
* *
* *
* Required entry (cannot be all blank) *
* *
********************************************************************
Note that in the CL program, the return variable is described as
*CHAR LEN(16). This is a requirement for the standard return
variable, but the input area shown on the display is length 10 as
described by the LEN parameter of the PMTOPR command. The operator
can only enter 10 positions.
The PMTOPR command would ensure that an entry was made, that it was a
valid name (e.g. did not start with a digit) and that it did not
exceed 10 characters. If an invalid entry is made, an appropriate
error message is displayed. The operator must enter a valid name
(i.e. a command key or a blank value will be rejected).
Note that the operator must respond. The default is that F3=Exit is
not allowed.
It would also be possible to enter a list of values that the operator
can enter and/or a default. For example, the command could have been
entered as:
PMTOPR RTNVAR(&RTNVAR) +
LEN(10) +
PROMPT('Enter the file name to be processed +
by the BILLING function') +
TYPE(*NAME) +
DFT(NEWORDER) +
VALUES(NEWORDER OLDORDER PREBILL BACKORDER)
The display would appear as follows:
********************************************************************
* *
* Prompt Operator 3/17/09 *
* *
* Enter the file name to be processed by the BILLING function *
* *
* *
* NEWORDER *
* -------- *
* *
* *
* Validation performed *
* *
* Must be a valid name *
* Values *
* *
* NEWORDER OLDORDER PREBILL *
* BACKORDER *
* *
********************************************************************
The operator must enter one of the names in the list. If enter is
pressed, the default is accepted.
All letters entered by the operator appear in upper case (i.e. the
DDS CHECK(LC) specification is not used).
It would also be possible to enter a list of values along with a
description of the choices. For example, the command could have been
entered as:
PMTOPR RTNVAR(&RTNVAR) +
LEN(1) +
PROMPT('Do you need to go on vacation?')
LINE1('Y Yes, immediately') +
LINE2('N No, not right now') +
LINE3('L No, I love it here') +
TYPE(*CHAR) +
VALUES(Y N L)
The display would appear as follows:
********************************************************************
* *
* Prompt Operator 3/17/09 *
* *
* Do you need to go on vacation? *
* *
* Y Yes, immediately *
* N No, not right now *
* L No, I love it here *
* *
* - *
* *
* *
* Validation performed *
* *
* *
* Values *
* *
* Y N L *
* *
********************************************************************
*
The display describes the validity checking that will be used so the
operator can better understand what is to be keyed. If values are
specified, each of the values appears on the display.
Command parameters *CMD
------------------
RTNVAR The return variable which is passed back to your
program which contains the data the operator
entered. The variable must be defined as *CHAR
LEN(16). The actual type and length are determined
by the TYPE and LEN parameters.
LEN The length of the prompted field. Even though the
field is returned to your program as 16 bytes, you
determine the length of the prompted field (i.e.
the length of the input field is from 1 to 16
positions).
PROMPT The prompt line which appears on the display. You
may enter up to 235 bytes.
FMTPROMPT Whether the PROMPT text should be formatted. *NO is
the default in which case your string of text may
split a word at the end of the workstation line.
*YES causes the FMTLIN TAA Tool to be used so that
no word is split at the end of the workstation line.
Excess blanks are squeezed out of the text.
*FMTCHAR may be specified to use the function
supported on FMTLIN to have formatting characters
within the text.
LINE1 The first of four indented lines that appears after
the PROMPT value. This is intended for an
explanation of the response values. The length can
be up to 70 bytes.
LINE2 The second indented explanation line.
LINE3 The third indented explanation line.
LINE4 The fourth indented explanation line.
TYPE The type of field to be entered. The following
entries are supported:
*CHAR Any data can be entered.
*NAME Only a valid name (restricted set of values)
can be entered. A period ('.') is not valid.
The 3 special characters ('$' '#' '@') are
valid. An underscore is valid.
*DEC Only digits (without a decimal point) can be
entered.
*DATE Only a 6 digit date in job format can be
entered. Note the other parameters (DAYHIRNG
DAYLORNG CURYEAR) which allow additional
validity checking on the date.
DFT An optional entry to allow a default to appear on
the display. It will be validity checked when the
operator presses enter. Up to 16 bytes can be
entered but the LEN parameter will determine how
many will be displayed.
RQD A *YES/*NO entry that determines if the operator
must make an entry. The default is *YES. Entering
blanks or not entering anything is not considered an
entry.
FILL A *YES/*NO entry that determines if the operator
must completely fill the input field (i.e. no
leading, embedded or trailing blanks). The default
is *NO allowing blanks.
ALARM A *YES/*NO entry that determines if the DDS ALARM
keyword will be used. *NO is the default meaning no
alarm is used.
*YES may be specified to cause the alarm (the 'beep'
sound).
ALWCNL A *YES/*NO entry that determines if the F3 key is
valid. The default is *NO meaning the operator must
enter a value.
If *YES is entered, F3 is valid to exit and TAA9893
is sent as an escape message if F3 is used.
RELOPR A relational operator to allow a comparison against
the input field. The default is *NO. The valid
entries are *GT *GE *NE *LT *LE. The comparison is
made against the next parameter value.
RELVAL The value to be used to compare with the RELOPR
parameter. Up to 16 bytes may be entered. If the
TYPE is defined as *DEC, the fields are converted to
decimal before the comparison is made.
LOWRNG The lower portion of a range check. Up to 16 bytes
may be entered. If the TYPE is defined as *DEC, the
fields are converted to decimal before the
comparison is made.
HIRNG The higher portion of a range check. Up to 16 bytes
may be entered. If the TYPE is defined as *DEC, the
fields are converted to decimal before the
comparison is made.
VALUES A list of entries that will be used to ensure that
the input must match. Up to 12 entries may appear
in the list each being 16 bytes long.
DAYLORNG This parameter and DAYHIRNG are used to provide some
additional checking if TYPE(*DATE) is specified.
You may enter a value that will be used to check the
input so it must be within a range of the days you
describe added to the current date. For example, if
the operator should not be allowed to enter a date
in the past, enter 0. The default is -365 days.
You may enter a plus value signifying the operator
cannot enter a date that is current plus N days.
DAYHIRNG This parameter and DAYLORNG are used to provide some
additional checking if TYPE(*DATE) is specified.
The default is +365 days. If the operator is not
allowed to enter a date in the future enter 0. A
minus value may also be entered.
CURYEAR This parameter provides additional checking for
TYPE(*DATE). It is a *YES/*NO value with *NO as the
default. If *YES is entered the operator cannot
enter a date that is other than the current year.
ERRTXT An optional parameter that allows you to do some
added checking in your CL program and if the input
fails, you may specify some text in this field which
will appear on the display in a highlighted form.
The parameter defaults to *NONE. After the command
is executed, the value is reset to *NONE. This
avoids you having to reset the parameter in your
program. You may enter up to 150 bytes.
The following PMTOPR command requests a date (6 digits) in job format
which must be within the last week of the current system date:
PMTOPR RTNVAR(&RTNVAR) LEN(6) PROMPT('Enter the +
date of the WEEK SUMMARY report') +
TYPE(*DATE) DAYLORNG(-7) DAYHIRNG(0)
The following PMTOPR command requests a one character value which
must be Y or N. A value of Y is shown as the default.
PMTOPR RTNVAR(&RTNVAR) LEN(1) PROMPT('Should the off +
site sales be included in the WEEK SALES +
report?') TYPE(*CHAR) DFT(Y) VALUES(Y N)
The following PMTOPR command requests a 5 digit value that is 100 or
greater.
PMTOPR RTNVAR(&RTNVAR) LEN(5) PROMPT('Enter the +
number of boxes to ship') TYPE(*DEC) +
RELOPR(*GE) RELVAL(100)
The following PMTOPR command requests a 7 character field and
performs validity checking within the CL program to check the value.
If it fails, an error message is displayed and the command is
re-executed. Note that if an error exists, the return variable is
moved to the DFT parameter so the incorrect value is re-displayed.
DCL &DFT *CHAR LEN(7)
DCL &ERRTXT *CHAR LEN(150) VALUE(*NONE)
LOOP: PMTOPR RTNVAR(&RTNVAR) LEN(7) PROMPT('Enter the warp +
factor') TYPE(*CHAR) DFT(&DFT) +
ERRTXT(&ERRTXT)
IF (&RTNVAR *EQ '...') DO /* Bad warp factor */
CHGVAR &DFT &RTNVAR
CHGVAR &ERRTXT ('This is a bad warp factor')
GOTO LOOP
ENDDO /* Bad warp factor */
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKDAT Check date
FMTLIN Format line
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ----- --------- ---------- -----------
PMTOPR *CMD TAAPMTA QATTCMD
TAAPMTAD *FILE DSPF TAAPMTAD QATTDDS
TAAPMTAC *PGM CLP TAAPMTAC QATTCL
|
