A CORRELATIVES

A codes provide many powerful features. These include arithmetic, relational, logical, and concatenation operators, the ability to reference fields by name or FMC, the capability to use other data definition records as functions that return a value, and the ability to modify report data by using format codes.

The A code also allows you to handle the data recursively, or "nest" one A code expression inside another.

SYNTAX SUMMARY

The A code function uses an algebraic format. There are two forms of the A code:

• A uses only the integer parts of stored numbers unless a scaling factor is included.
• AE handles extended numbers. Uses both integer and fractional parts of stored numbers.

SYNTAX

A{n}{;expression}
AE;expression

SYNTAX ELEMENTS

n is a number from 1 to 6 that specifies the required scaling factor.

expression comprises operands, operators, conditional statements, and special functions.

NOTES

The A code replaces and enhances the functionality of the F code. You will find A codes much easier to work with than F codes.

A;EXPRESSION FORMAT

Performs the functions specified in expression on values stored without an embedded decimal point.

AN FORMAT: EMBEDDED DECIMALS

The An format converts a value stored with an embedded decimal point to a scaled integer. The stored value's explicit or implied decimal point is moved n digits to the right with zeros added if necessary. Only the integer portion is returned.

Field 2 of the data definition record must contain the FMC of the field that contains the data to be processed.

AN;EXPRESSION FORMAT

The An;expression format performs the functions specified in expression on values stored with an embedded decimal point. The resulting value is then converted to a scaled integer.

AE;EXPRESSION FORMAT

The AE format uses both the integer and fractional parts of stored numbers. Scaling of output must be done with format codes.

EXAMPLES OF NUMERIC RESULTS

INPUT CONVERSION

Input conversion is not allowed.

FORMAT CODES

You can format the result of any A code operation by following the expression with a value mark, and then the required format code, like this:

An;expression]format

Format codes can also be included within the expression. See Format Codes for more information.

SUMMARY OF OPERANDS

Operands that you can use in A code expressions include: FMCs (field numbers), field names, literals, operands that return system parameters, and special functions.

You can format any operand by following it with one or more format codes enclosed in parentheses, and separated by value marks, (ctrl ]), like this:

operand(format-code{]format-code}...)

See Format Codes for more information.

FIELD NUMBER (FMC) OPERAND

The field number operand returns the content of a specified field in the data record:

field-number{R{R}}

The first R specifies that any non-existent multivalues should use the previous non-null multivalue. When the second R is specified, this means that any non-existent subvalues should use the previous non-null subvalue.

FIELD NAME OPERAND

The field name operand returns the content of a specified field in the data record:

N(field-name){R{R}}

LITERAL OPERAND

The literal operand supplies a literal text string or numeric value:

"literal"

SYSTEM PARAMETER OPERANDS

Several A code operands return the value of system parameters. They are:

SPECIAL OPERANDS

Some operands allow you to use special functions. They are:

SUMMARY OF OPERATORS

Operators used in A code expressions include arithmetic, relational and logical operators, the concatenation operator, and the IF statement.

ARITHMETIC OPERATORS

Arithmetic operators are:

RELATIONAL OPERATORS

Relational operators specify relational operations so that any two expressions can treated as operands and evaluated as returning true (1) or false (0). Relational operators are:

LOGICAL OPERATORS

The logical operators test two expressions for true or false and return a value of true or false. Logical operators are:

CONCATENATION OPERATOR

The concatenation operator is a colon (:)

IF STATEMENT

The IF operator gives the A code its conditional capabilities. An IF statement looks like this:

IF expression THEN statement ELSE statement

FIELD NUMBER (FMC) OPERAND

Specifies a field which contains the value to be used.

SYNTAX

field-number{R{R}}

SYNTAX ELEMENTS

field-number is the number of the field (FMC) which contains the required value.

R specifies that the value obtained from this field is to be applied repeatedly for each multivalue not present in a corresponding part of the calculation.

RR specifies that the value obtained from this field is to be applied repeatedly for each subvalue not present in a corresponding part of the calculation.

NOTES

The following field numbers have special meanings:

EXAMPLE 1

A;2

Returns the value stored in field 2 of the record.

EXAMPLE 2

A;9999

Returns the size of the record in bytes.

EXAMPLE 3

A;2 + 3R

For each multivalue in field 2 the system also obtains the (first) value in field 3 and adds it. If field 2 contains 1]7 and field 3 contains 5 the result would be two values of 6 and 12 respectively. Where 3 does not have a corresponding multivalue, the last non-null multivalue in 3 will be used.

EXAMPLE 4

A;2 + 3RR

For each subvalue in field 2 the system also obtains the corresponding subvalue in field 3 and adds it. If field 2 contains 1\2\3]7 and field 3 contains 5\4 the result would be five values of 6, 6, 7, 12 and 4 respectively.

N (FIELD NAME) OPERAND

References another field defined by name in the same dictionary or found in one of the default dictionaries.

SYNTAX

N(field-name){R{R}}

SYNTAX ELEMENTS

field-name is the name of another field defined in the same dictionary or found in the list of default dictionaries (see the JBCDEFDICTS environment variable).

R specifies that the value obtained from this field is to be applied repeatedly for each multivalue not present in a corresponding part of the calculation.

RR specifies that the value obtained from this field is to be applied repeatedly for each subvalue not present in a corresponding part of the calculation.

NOTES

If the data definition record of the specified field contains field 8 pre-process conversion codes, these are applied before the value(s) are returned.

Any pre-process conversion codes in the specified field-name, including any further N(field-name) constructs are processed as part of the conversion code.

N(field-name) constructs can be nested to 30 levels. The number of levels is restricted to prevent infinite processing loops. For example:

TEST1
008 A;N(TEST2)

TEST2
008 A;N(TEST1)

EXAMPLE 1

A;N(S.CODE)

Returns the value stored in the field defined by S.CODE.

EXAMPLE 2

A;N(A.VALUE) + N(B.VALUE)R

For each multivalue in the field defined by A.VALUE the system also obtains the corresponding value in B.VALUE and adds it. If A.VALUE returns 1]7 and B.VALUE returns 5, the result would be two values of 6 and 12 respectively.

EXAMPLE 3

A;N(A.VALUE) + N(B.VALUE)RR

For each subvalue in the field defined by A.VALUE the system also obtains the corresponding value in B.VALUE and adds it. If A.VALUE returns 1\2\3]7 and B.VALUE returns 5 the result would be four values of 6, 7, 8 and 12 respectively.

LITERAL OPERAND

Specifies a literal string or numeric constant enclosed in double quotes.

SYNTAX

"literal"

SYNTAX ELEMENTS

literal is a text string or a numeric constant.

NOTES

A number not enclosed in double quotes is assumed to be a field number (FMC).

EXAMPLE 1

A;N(S.CODE) + "100"

Adds 100 to each value (subvalue) in the field defined by S.CODE.

EXAMPLE 2

A;N(S.CODE):"SUFFIX"

Concatenates the string "SUFFIX" to each value (subvalue) returned by S.CODE.

SYSTEM PARAMETER OPERANDS

Reference system parameters like date, time, the current break level, or the number of the current record.

SYNTAX

system-operand

SYNTAX ELEMENTS

system-operand can be any of the following:

SPECIAL OPERANDS

INTEGER FUNCTION

The Integer Function I(expression) returns the integer portion of expression.

EXAMPLE

AE;I(N(COST) * N(QTY))

Returns the integer portion of the result of the calculation.

REMAINDER FUNCTION

The Remainder Function R(exp1, exp2) takes two expressions as operands and returns the remainder when the first expression is divided by the second.

EXAMPLE

A;R(N(HOURS) / "24")

Returns the remainder when HOURS is divided by 24.

SUMMATION FUNCTION

The Summation Function S(expression) evaluates an expression and then adds together all the values.

EXAMPLE

A;S(N(HOURS) * N(RATE)R)

Each value in the HOURS field is multiplied by the value of RATE. The multivalued list of results is then totalled.

SUBSTRING FUNCTION

The substring function [start-char-no, len] extracts the specified number of characters from a string, starting at a specified character.

SYNTAX ELEMENTS

start-char-no is an expression that evaluates to the position of the first character of the substring.

len is an expression that evaluates to the number of characters required in the substring. Use - len (minus prefix) to specify the end point of the substring. For example, [1, -2] will return all but the last character and [-3, 3] will return the last three characters.

EXAMPLE 1

A;N(S.CODE)["2", "3"]

Extracts a sub-string from the S.CODE field, starting at character position 2 and continuing for 3 characters.

EXAMPLE 2

A;N(S.CODE)[2, N(SUB.CODE.LEN)]

Extracts a sub-string from the S.CODE field, starting at the character position defined by field 2 and continuing for the number of characters defined by SUB.CODE.LEN.

FORMAT CODES

Specifies a format code to be applied to the result of the A code or an operand.

SYNTAX

a-code{]format-code...}
a-operand(format-code{]format-code}...)

SYNTAX ELEMENTS

a-code is a complete A Code expression.

a-operand is one of the A Code operands.

format-code is one of the codes described later - G(roup), D(ate) or M(ask).

] represents a value mark that must be used to separate each format-code.

NOTES

You can format the result of the complete A code operation by following the expression with a value mark and then the required format
code(s). (This is actually a standard feature of the data definition records.)

Format codes can also be included within A code expressions. In this case, they must be enclosed in parentheses, and separated with a value mark if more than one format code is used.

All format codes will convert values from an internal format to an output format.

EXAMPLE 1

A;N(COST)(MD2]G0.1) * ...

Shows two format code applied within an expression. Obtains the COST value and applies an MD2 format code. Then applies a group extract to acquire the integer portion of the formatted value. The integer portion can then be used in the rest of the calculation. Could also have been achieved like this:

A;I(N(COST)(MD2)) * ...

EXAMPLE 2

A;N(COST) * N(QTY)]MD2

Shows the MD2 format code applied outside the A code expression. COST is multiplied by QTY and the result formatted by the MD2 format code.

OPERATORS

Operators used in A code expressions include arithmetic, relational and logical operators, the concatenation operator, and the IF statement.

ARITHMETIC OPERATORS

Arithmetic operators are:

RELATIONAL OPERATORS

Relational operators specify relational operations so that any two expressions can treated as operands and evaluated as returning true (1)
or false (0). Relational operators are:

LOGICAL OPERATORS

The logical operators test two expressions for true (1) or false (0) and return a value of true or false. Logical operators are:

AND|Returns true if both expressions are true.
OR|Returns true if any expressions is true.

The words AND and OR must be followed by at least one space. The AND operator takes precedence over the OR unless you specify a different order by means of parentheses. OR is the default operation.

CONCATENATION OPERATOR

A colon (:) is used to concatenate the results of two expressions.

For example, the following expression concatenates the character "Z" with the result of adding together fields 2 and 3:

A;"Z":2 + 3

IF STATEMENT

The IF statement gives the A code conditional capabilities.

SYNTAX

IF expression THEN statement ELSE statement

SYNTAX ELEMENTS

expression must evaluate to true or false. If true, executes the THEN statement. If false, executes the ELSE statement.

statement is a string or numeric value.

NOTES

Each IF statement must have a THEN clause and a corresponding ELSE clause.

IF statements can be nested but the result of the statement must evaluate to a single value.

The words IF, THEN and ELSE must be followed by at least one space.

EXAMPLE 1

A;IF N(QTY) < 100 THEN N(QTY) ELSE ERROR!

Tests the QTY value to see if it is less than 100. If it is, output the QTY field. Otherwise, output the text "ERROR!".

EXAMPLE 2

A;IF N(QTY) < 100 AND N(COST) < 1000 THEN N(QTY) ELSE ERROR!

Same as example 1 except that QTY will only be output if it is less than 100 and the cost value is less than 1000.

EXAMPLE 3

A;IF 1 THEN IF 2 THEN 3 ELSE 4 ELSE 5

If field 1 is zero or null, follow else and use field 5. Otherwise test field 2. If field 2 is zero or null, follow else and use field 4. Otherwise use field 3. Field 3 is only used if both fields 1 and 2 contain a value.

jQL