PMTOPR       PROMPT OPERATOR                       TAAPMTA

 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

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.