The ASSERT statement asserts whether a
condition is true or false, compares two values and determines if
they are equal, or asserts whether a statement should be executed
or not.
>>-ASSERT-------------------------------------------------------> >--+-TRUE--(--test-expression--)----------------------+-+--------------------------------+->< +-FALSE--(--test-expression--)---------------------+ '-TEXT--(--display-expression--)-' +-COMPARE--(--actual_exp--,expected_exp--+----+--)-+ | '-,z-' | '-UNREACHABLE--------------------------------------'
- TRUE(test-expression)
- Asserts that test-expression is true when one or more bits in test-expression have the value '1'B.
- FALSE(test-expression)
- Asserts that test-expression is false when all the bits in test-expression have the value '0'B.
- COMPARE(actual_exp,expected_exp,z)
- Asserts that the value of actual_exp is equal
to the value of expected_exp. z is an optional
argument which names an operator.
- TEXT(display-expression)
- Passes the display-expression to the assertion routine if the assert fails.
- UNREACHABLE
- Asserts that the statement cannot be reached, because it is bypassed by a proceeding statement, such as a GOTO, RETURN, or SIGNAL statement.
- display-expression
- A scalar CHARACTER expression.
- test-expression
- A computational scalar expression that is to be, if necessary, converted to BIT.
- actual_exp
- A computational expression that is evaluated and possibly converted.
It must be a scalar expression and must have the same type as expected_exp.
- expected_exp
- A computational expression that is evaluated and possibly converted.
It must be a scalar expression and must have the same type as actual_exp.
- z
- A CHAR(2) constant. When uppercased, the constant must have one
of these values: EQ, LE, LT, GT, GE, or NE. If you do not specify z,
EQ is the default value.
- EQ
- Equal to
- LE
- Less than or equal to
- LT
- Less than
- GT
- Greater than
- GE
- Greater than or equal to
- NE
- Not equal to
If the assertion fails, compiled code calls routine
IBMPASU for the ASSERT UNREACHABLE statement, IBMPAST for the ASSERT
TRUE and FALSE statements, and IBMPASC for the ASSERT COMPARE statement.
These routines must use the OPTLINK linkage. Note:
- Under the ASSERT(CONDITION) compiler option, the ASSERTION condition will be raised.
- The compiled code calls the routines IBMPASU/IBMPAST/IBMPASC, if ASSERT(ENTRY) compiler option is used.
Compiled code calls the IBMPASU and IBMPAST routines
with the following BYVALUE parameters:- A POINTER holding the address of a buffer that contains the PACKAGENAME value as a varying character string.
- A POINTER holding the address of a buffer that contains the PROCNAME value as a varying character string.
- A FIXED BIN(31) holding the SOURCELINE value.
- A POINTER holding the ADDRDATA of the TEXT value. If the TEXT clause is omitted, the value passed is SYSNULL.
- A FIXED BIN(31) holding the LENGTH of the TEXT value. If the TEXT clause is omitted, the value passed is 0.
Compiled code calls the IBMPASC routine for the
ASSERT COMPARE statement with the following BYVALUE parameters:- A POINTER holding the address of a buffer that contains the PACKAGENAME value as a varying character string.
- A POINTER holding the address of a buffer that contains the PROCNAME value as a varying character string.
- A FIXED BIN(31) holding the SOURCELINE value.
- A POINTER holding the ADDRDATA of the actual_exp value. The clause must not be omitted.
- A FIXED BIN(31) holding the LENGTH of the actual_exp value.
- A POINTER holding the ADDRDATA of the expected_exp value. The clause must not be omitted.
- A FIXED BIN(31) holding the LENGTH of the expected_exp value.
- A POINTER holding the ADDRDATA of the TEXT value. If the TEXT clause is omitted, the value passed is SYSNULL.
- A FIXED BIN(31) holding the LENGTH of the TEXT value. If the TEXT clause is omitted, the value passed is 0.
The strings representing the actual and expected
expressions depend on the type of those expressions. If the commands
have:- Computational types other than GRAPHIC or WIDECHAR, then the strings will be the value of the expressions converted to CHARACTER.
- POINTERs or HANDLEs, then the strings will be their HEX values.
- ORDINALs, then the strings will be their ORDINALNAME values.
- Any other type, then the strings will be null strings.
Example: The usage of the ASSERT TRUE, ASSERT FALSE and ASSERT UNREACHABLE statements
The following
example shows the usage of the ASSERT TRUE, ASSERT FALSE and ASSERT
UNREACHABLE statements. You must code the routines that are used in
this example.
asserts: package;
main: proc options(main);
dcl n fixed bin;
n = 1;
assert true( n> 0 );
assert true( n= 2 ) text('n not equal to 2');
assert unreachable;
end;
ibmpasu:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( '_IBMPASU')
options( byvalue linkage(optlink) );
dcl packagename_ptr pointer;
dcl procname_ptr pointer;
dcl assert_sourceline fixed bin(31);
dcl text_addr pointer;
dcl text_length fixed bin(31);
dcl assert_packagename char(100) var based(packagename_ptr);
dcl assert_procname char(100) var based(procname_ptr);
dcl assert_text char(text_length) based(text_addr);
put skip edit( 'unreachable code hit on line ',
trim(assert_sourceline),
' in ',
assert_packagename,
':', assert_procname )
( a );
if text_length = 0 then;
else
put skip list( assert_text );
end;
ibmpast:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( '_IBMPAST')
options( byvalue linkage(optlink) );
dcl packagename_ptr pointer;
dcl procname_ptr pointer;
dcl assert_sourceline fixed bin(31);
dcl text_addr pointer;
dcl text_length fixed bin(31);
dcl assert_packagename char(100) var based(packagename_ptr);
dcl assert_procname char(100) var based(procname_ptr);
dcl assert_text char(text_length) based(text_addr);
put skip edit( 'conditional assertion failed on line ',
trim(assert_sourceline),
' in ',
assert_packagename,
':', assert_procname )
( a );
if text_length = 0 then;
else
put skip list( assert_text );
end;The following example shows the usage of the ASSERT
COMPARE statement. You must code the routines that are used in this
example.
Example: The usage of the ASSERT COMPARE statement
asserts: package;
main: proc options(main);
dcl n fixed bin;
n = 1;
assert compare(n,1);
assert compare(n,2) text("n not equal to 2");
assert unreachable;
end;
ibmpasc:
proc( packagename_ptr, procname_ptr, assert_sourceline,
actual_addr, actual_length,
expected_addr, expected_length,
text_addr, text_length )
ext( '_IBMPASC')
options( byvalue linkage(optlink) );
dcl packagename_ptr pointer;
dcl procname_ptr pointer;
dcl assert_sourceline fixed bin(31);
dcl actual_addr pointer;
dcl actual_length fixed bin(31);
dcl expected_addr pointer;
dcl expected_length fixed bin(31);
dcl text_addr pointer;
dcl text_length fixed bin(31);
dcl assert_packagename char(100) var based(packagename_ptr);
dcl assert_procname char(100) var based(procname_ptr);
dcl assert_text char(text_length) based(text_addr);
dcl actual_text char(actual_length) based(actual_addr);
dcl expected_text char(expected_length)
based(expected_addr);
put skip edit( 'compare code hit on line ',
trim(assert_sourceline),
' in ',
assert_packagename,
':', assert_procname )
( a );
if text_length = 0 then;
else
put skip list( assert_text );
if actual_length = 0 then;
else
put skip list( actual_text );
if expected_length = 0 then;
else
put skip list( expected_text );
end; - The ONPACKAGE built-in function will provide the name of the PACKAGE in which an ASSERTION condition is raised.
- The ONTEXT built-in function will provide the value of the TEXT string when an ASSERT statement fails (and if the statement has no TEXT option, it will return a null string).
- The ONACTUAL and ONEXPECTED built-in functions will provide strings specifying the actual and expected values respectively when an ASSERT COMPARE statement fails.
- ONPROCEDURE and ONPROC will now be supported.
Note:
- The ASSERTION condition is always enabled.
- The implicit action for the ASSERTION condition is that a message is printed and the ERROR condition is raised.
- The normal return for the ASSERTION condition is that execution continues with the next statement.
- The ONCODEs associated with the ASSERTION condition are:
Condition code Meaning 430 SIGNAL ASSERTION 431 An ASSERT TRUE/FALSE statement without a TEXT clause failed 432 An ASSERT TRUE/FALSE statement with a TEXT clause failed 433 An ASSERT UNREACHABLE statement without a TEXT clause failed 434 An ASSERT UNREACHABLE statement with a TEXT clause failed 435 An ASSERT COMPARE statement without a TEXT clause failed 436 An ASSERT COMPARE statement with a TEXT clause failed