The Add Hexadecimal command adds or subtracts two hexadecimal or
decimal values and returns either or both a hexadecimal or decimal
value. Either unsigned or signed hex values may be entered. Each
type of value can be the same or a different type in each of the two
factors. ADDHEX can be helpful when viewing dumps or user spaces.
See also the WRKADDHEX command for a work display that is an
interactive front-end to ADDHEX.
The following are some examples:
** While intended for factors involving some hex value, the
command may be used as a simple decimal calculator such as:
ADDHEX OP(*ADD) FACTOR1(*DEC 0 12) FACTOR2(*DEC 0 13)
DECOUT(&DECOUT)
The Factor 1 value of decimal 12 would be added to the Factor
2 value of decimal 13 and the result of 25 returned in the
&DECOUT variable. The &DECOUT variable must be defined as
*CHAR LEN(21). The value would be left adjusted. A negative
value would be left adjusted with a preceding minus sign.
** You can use WRKADDHEX to translate hex to decimal or vice
versa by adding 0 such as:
ADDHEX OP(*ADD) FACTOR1(*DEC 0 0) FACTOR2(*HEXU 0A 0)
DECOUT(&DECOUT)
** More typical would be to calculate a hex offset by adding the
offset to the initial hex value: such as:
ADDHEX OP(*ADD) FACTOR1(*HEXU 0A 0) FACTOR2(*DEC 0 13)
HEXOUT(&HEXOUT)
The decimal 13 value would be added to X'0A' (10 in decimal)
and the &HEXOUT value would be X'17'. The '*HEXU' type means
the hex value is unsigned.
** You may also add two hex values and return a hex value such
as:
ADDHEX OP(*ADD) FACTOR1(*HEXU 0A 0) FACTOR2(*HEXU 11 0)
HEXOUT(&HEXOUT)
The &HEXOUT variable must be declared as *CHAR LEN(18). In
this case the X'0A' (10 in decimal) and the the X'11' value
(17 in decimal) are added and X'1B' is returned (27 in
decimal). The actual return value would be
X'00000000000000001B'.
** You may use either signed or unsigned hex values. The *HEXU
(hex unsigned) entry indicates that all hex values entered are
positive. Using *HEXS (signed hex) allows positive hex values
from 0 to 7FFFFFFFFFFFFFFF and negative hex values from
8000000000000000 to FFFFFFFFFFFFFFFF.
** Note than when entering signed (type *HEXS) hexadecimal
values, the sign of the value is determined by the left-most
non-zero hexadecimal digit.
For example, the values x'F', x'0F', and x'00F' are treated as
x'F', which has a decimal of -1.
Note that hex values from 0 to 7FFFFFFFFFFFFFFF are positive
for both *HEXU or *HEXS.
ADDHEX OP(*ADD) FACTOR1(*HEXS A 0) FACTOR2(*HEXS 11 0)
HEXOUT(&HEXOUT)
The return value would also be X'00000000000000001B'.
** Adding a negative hex value could be specified as:
ADDHEX OP(*ADD) FACTOR1(*HEXS A 0)
FACTOR2(*HEXS FC 0)
HEXOUT(&HEXOUT)
The signed hex values A and FC are equal to -6 and -4,
respectively. The sums would be X'FFFFFFFFFFFFFFFFF6' and
-10. See the later discussion of how negative signed hex
values are determined.
You may subtract also such as:
ADDHEX OP(*SUB)
FACTOR1(*HEXU A 0) FACTOR2(*HEXU 2 0)
HEXOUT(&HEXOUT)
The decimal result would be 12. The &HEXOUT value would be
X'00000000000000000C'.
Hexadecimal values
------------------
Hex Signed and Unsigned values are the same for positive values from
0 to 7FFFFFFFFFFFFFFF. The decimal equivalents are 0 to
9223372036854775807
The decimal equivalents of unsigned hex 8000000000000000 to
FFFFFFFFFFFFFFFF are 9223372036854775808 to 18446744073709551615
The decimal equivalents of signed hex 8000000000000000 to
FFFFFFFFFFFFFFFF are -9223372036854775808 to -1.
Negative hex values are difficult to read. So, they can be converted
to their corresponding absolute hexadecimal values using twos'
complements, a two step process. First, the one complement (the
logical NOT operation, also called bitwise negation) is calculated.
Then binary 1 is added to the result.
For example:
Hex Signed Value Decimal Value Notes
------------------ ------------- -------------
FFFFFFFFFFFFFFFFF1 -14 original
00000000000000000D 13 bitwise negation
00000000000000000E 14 add binary 1
8FFFFFFFFFFFFFFFFF -8070450532247928833 original
007000000000000000 8070450532247928832 bitwise negation
007000000000000001 8070450532247928833 add binary 1
Fortunately, you can use ADDHEX to calculate a negative hex
value's twos' complement by subtracting the negative signed
hex value from 0. For example:
ADDHEX OP(*SUB) FACTOR1(*HEXS 0 0)
FACTOR2(*HEXS FFFFFFFFFFFFFFFC 0)
HEXOUT(&HEXOUT)
The &HEXOUT value, X'000000000000000004', is the twos'
complement of X'FFFFFFFFFFFFFFFC'.
ADDHEX escape messages you can monitor for
------------------------------------------
None. Escape messages from based on functions will be re-sent.
ADDHEX Command parameters *CMD
-------------------------
OP The operation to be performed. *ADD is the default
to add Factor 1 and 2.
*SUB may be specified to subtract Factor 2 from
Factor 1. When *SUB is used with unsigned values
where Factor 1 is greater than Factor 2, ADDHEX
returns the correct negative result.
FACTOR1 A 3 part entry must be specified.
The first part is the Type of value to be entered.
The second part allows a hex value and the third
part allows a decimal value.
*HEXU (unsigned hex) is the default). Hex
values may range from X'0' to
'FFFFFFFFFFFFFFFF'
*HEXS (signed hex) may be specified. Positive
values may be entered from X'0' to
'7FFFFFFFFFFFFFFF'. Negative values may be
entered from 8000000000000000 to
FFFFFFFFFFFFFFFF. See the previous section on
Hexadecimal values for examples of negative
signed values.
*DEC (decimal) may be specified for up to 20
decimal digits. The value should be entered as
a left justified character field. A leading
minus or plus sign is permitted. A trailing
sign is not permitted. The decimal input
values must be in a range of
-99999999999999999999 to 99999999999999999999
(each with 20 decimal digits).
Note that a 0 must be in the Hex value if a non-zero
decimal value is entered and vice versa. You cannot
enter both a non-zero hex value and a non-zero
decimal value.
FACTOR2 A 3 part entry must be specified.
The first part is the Type of value to be entered.
The second part allows a hex value and the third
part allows a decimal value.
*HEXU (unsigned hex) is the default). Hex
values may range from X'0' to
'FFFFFFFFFFFFFFFF'
*HEXS (signed hex) may be specified. Positive
values may be entered from X'0' to
'7FFFFFFFFFFFFFFF'. Negative values may be
entered from 8000000000000000 to
FFFFFFFFFFFFFFFF. See the previous section on
Hexadecimal values for examples of negative
signed values.
*DEC (decimal) may be specified for up to 20
decimal digits. The value should be entered as
a left justified character field. A leading
minus or plus sign is permitted. A trailing
sign is not permitted. The decimal input
values must be in a range of
-99999999999999999999 to 99999999999999999999
(each with 20 decimal digits).
Note that a 0 must be in the Hex value if a non-zero
decimal value is entered and vice versa. You cannot
enter both a non-zero hex value and a non-zero
decimal value.
HEXOUT An optional return variable for the result in
hexadecimal. If used, the variable must be declared
as *CHAR LEN(18).
DECOUT An optional return variable for the result in
decimal. If used, the variable must be declared as
*CHAR LEN(21). The value will be left adjusted,
will consist of up 20 decimal digits, and may have a
leading minus sign.
Restrictions
------------
Because ADDHEX returns variables, the command may only be used in an
OPM CL program, or in an ILE program or service program in which
ADDHEX is executed in an ILE CL (CLLE) module.
Prerequisites
-------------
The following TAA Tools must be on your system:
CVTHEX Convert hex
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
ADDHEX *CMD TAACLTZ QATTCMD
TAACLTZC *PGM CLP TAACLTZC QATTCL
TAACLTZR *PGM RPGLE TAACLTZR QATTRPG
TAACLTZP *FILE PF
TAACLTZP is a source file that contains the TAACLTZP source member
with REXX code. The REXX code is interpretively executed at run
time.
|
