The Build Check Amount tool is designed to print words for the amount
on a check such as 'Four hundred dollars and 03 cents'. A program is
supplied to convert a decimal value to a string of text. An
externally described data structure is used to pass the amount,
return the string of text, and provide for various options. A
demonstration of the function and options exists.
To see the demonstration, enter:
DMOCHKAMT
The display allows you to enter a value, try various options, and see
the result.
The return value may have a maximum of 100 bytes. You may specify a
smaller length maximum return value (the default is 80). It is
possible to generate a string of text that will exceed the maximum
size provided. By default, if an overflow occurs, numbers are used
for the whole dollars and a value such as '888,888 dollars and 00
cents' is returned.
If any errors occur, the string of text will contain all asterisks
and a return code and error text are provided. See the later
discussion on Maximum Length and Overflow.
The program that performs the translation from numbers to words is
TAARPHCR.
To see how to interface to the TAARPHCR program, a working program
(TAARPHCR3) is provided. Instructions are included in the source for
TAARPHCR3 for how to use the function. The program prints one amount
to the QPRINT printer file. You may try the program with:
CALL PGM(TAARPHCR3)
A simple spooled file is created.
To understand the TAARPHCR3 interface program, use CPYTAA:
CPYTAA TAAARCMBR(TAARPHCR3)
This copies the source to member TAARPHCR3 in file QATTRPG in library
TAATOOL. You may then browse or copy the code to your own member and
modify it according to the instructions within the source.
Fields in the TAARPHCP Externally described DS
----------------------------------------------
Field Length Description
----- ------ -----------
CKLR 4 Set LR. *NO is the default to allow a fast
re-execution. Use *YES when ending
immediately.
CKINP 11 Input amount. A character field is used with
2 decimal positions assumed. The value
should be right adjusted in the field
(such as MOVE op code).
CKRTNV 100 The returned string of text. All asterisks
will exist if an error has occurred.
The value is always returned as 100 bytes.
The value is left or right adjusted
according to the CKADJ field.
CKALW0 4 Whether to allow a zero amount. *NO is
the default. If *YES is specified and
a zero amount exists, a value such as
'Zero dollars and 00 cents' will be
returned.
CKCNTO 6 The 'cent option' to be used. *TEXT is the
default and causes 'cents' or 'cent'
to be used such as 'One dollar and
15 cents'. If you have different text,
see the CKCEN and CKCENT fields.
*100 may be specified to cause a value
such as 'One and 15/100 dollars'.
*NONE may be specified if you have a
currency that does not use cents.
You must add two zeros to your
input amount before moving the
value to the CKINP field.
CKADJ 4 Adjust the answer. The default is *LFT for
a left adjusted value. *RGT may be
specified for a right adjusted value.
CKASTP 4 Asterisk protection. The default is *NO
meaning the string of text does not
include protecting asterisks.
*YES may be specified to cause asterisks
in the remaining spaces of the return value.
CKDOLS 15 The word for 'dollars'. The default is
'dollars'. Left adjust the value.
CKDOL 15 The word for 'dollar'. The default is
'dollar'. Left adjust the value.
CKCENS 15 The word for 'cents'. The default is
'cents'. Left adjust the value.
CKCENT 15 The word for 'cent'. The default is
'cent'. Left adjust the value.
CKOFLW 4 Allow for numbers on overflow. The default
is *YES to return numbers if the words
exceed the maximum length (CKMAXL field).
*NO causes an error if overflow occurs.
See the section on maximum length and
overflow.
CKMAXL 3 Maximum length of answer. The maximum
string that will be returned. The
default is 80. The value must be
between 35 and 100.
CKRTNL 3 Return length. A return field which will
contain the actual length of the string
of words without considering asterisk
protection.
CKRTNO 1 Return overflow. A 'Y' is returned if
the string of text overflowed and
CKOFLW = *YES was used to return
numbers for the dollar amount.
If overflow did not occur, the field
will be blank.
CKERRC 3 Return error code. If an error has
occurred, the return value will be all
asterisks and the error code will identify
the specific error. The CKERRT field
will contain the text of the error. If
no error occurred, the field will be blank.
CKERRT 70 Return error text. The text description
of the error code. If no error occurred,
the field will be blank.
CKRSVD 50 Reserved space.
Maximum Length and Overflow
---------------------------
The CKINP field to hold the amount is 11 bytes in length and assumes
2 decimal positions. This allows for a value of xxx,xxx,xxx.00.
The default for CKOFLW is *YES which means that if the string of text
exceeds the specified maximum length, the dollar amount is changed to
numbers.
A value such as '1,888,888.00' requires 96 bytes when printed as a
string of text. If your maximum length is less than 96, either an
error will be returned or you may request that numbers be returned
for the whole amount.
If the default is used and the string of text exceeds the specified
maximum length, the dollar amount is changed to numbers with
appropriate editing. For example, the return value would be
'1,888,888 dollars and 00 cents'.
If CKOFLW = *NO and an overflow occurs, the return value is all
asterisks and a specific error code is returned.
For the following comments, the CKCNTX = *CENTS option was used.
CKCNTX = *100 causes 2 bytes less in the answer.
** The largest XX,XXX,XXX.00 value (77,777,777.00) requires 105
bytes and cannot be printed as words. However, a value such
as 35,205,345.00 will fit in a length of 100 bytes.
** All X,XXX,XXX.00 values fit in 98 bytes.
** All XXX,XXX.00 values fit in 84 bytes.
** All XX,XXX.00 values fit in 70 bytes.
Changing the constants such as 'one' to 'uno'
---------------------------------------------
The words used such as 'thousands', 'seventy', are all placed in the
WRK array at the end of the TAARPHCR program. Each word may be up to
15 characters in length. You may change the words for different
languages. You may also change the defaults for 'dollars', 'dollar',
'cents', and 'cent' instead of specifying them in the data structure.
Using a currency that does not have cents
-----------------------------------------
If you have a currency that does not have cents, you must add two
digits to your input amount before moving the data to CKINP (or you
concatenate two zeros on the end when you move your data). Then
specify CKCNTO(*NONE). This will cause the 'and' and cents text to
be dropped.
DMOCHKAMT command *CMD
-----------------
No parameters exist.
Restrictions
------------
See the previous discussion on maximum length and overflow.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR2 Edit variable 2
RTVSYSVAL3 Retrieve system value 3
Implementation
--------------
None, the tool is ready to use, but you must supply an interface
program as described previously.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
DMOCHKAMT *CMD TAARPHC2 QATTCMD
TAARPHCR *PGM RPG TAARPHCR QATTRPG
TAARPHCR2 *PGM RPG TAARPHCR2 QATTRPG
TAARPHCR3 *PGM RPG TAARPHCR3 QATTRPG
TAARPHCD *FILE DSPF TAARPHCD QATTDDS
TAARPHCP *FILE PF TAARPHCP QATTDDS
Structure
---------
DMOCHKAMT Cmd
TAARPHCR2 RPG pgm
TAARPHCD Display file
TAARPHCR Build check amount program
TAARPHCR3 Sample interface program
|
