Built-In
Functions and Special Fields
$JString(String
field 1, String field 2 [,String field 3]…)
$String(Reference
to ENUM variable)
A function is a calculated value that you can use in an
expression as if it were a field. For example
Master.DateOfTransaction = $Today;
Jazz provides a range of special functions built into the language, all named starting with “$” such as $Now and $Today. Jazz also allows you to use COBOL intrinsic functions, for example SQRT.
Special Fields are names of fields in the generated COBOL
program or messages (e.g. to/from web services) that are set to particular
values: for example “Return Code” will be a field named (for example) “JZ-Custf-ReturnCode” that will have
a value depending on an I/O operation on file Custf. These are named starting with “JZ” ($ is
usually invalid in these contexts).
Jazz currently provides a small number of built in
functions, all named starting with “$”.
This list will be extended in future Jazz releases.
$Now
returns the date and time when $Now is executed. $Today returns the date
and the time at which the program started.
Example
DEFINE
R DATA(
TimeOfTransaction
CHAR(21));
R.Timeoftransaction
= $Now;
In contrast to $Now, $Today returns the time at which the program was invoked.
R.Timeoftransaction = $Today;
For a
long-running program, such as a batch file copy, every use of $Today
will return the same date and time even if the program runs through
midnight. In contrast, each use of $Now gets the system time at that
instant, and successive uses of $Now may differ by a few milliseconds.
In CICS programs there will be effectively no difference between $Now
and $Today.
With either
function you can give an argument to specify which part of the result you want.
Thus you can give a value like $Today(Date)
or $Now(Time) to get part of the DateTime value. Arguments are: -
DateTime. This returns a DATETIME
value.
Date This returns
a Date value, with format yyyymmdd where yyyy is the year (e.g. 2013), mm is the month(e.g.
05 for May), dd is the day. If assigned to a DateTime
value, the date portion will be zeros (Midnight at the start of the day).
Time. This returns a Time value, with format hhmmssmm where hh is the hour (0
to 24), mm is the minutes within the hour, ss is seconds, and mm is fractions
of a second.
Year. Returns a number, which is the current year,
i.e. 2013.
Month. A number, 1-12, representing the month. E.g. 5 = May.
Day. A number, 1 to 31, representing the day
within the month.
Hour. A number,
0 to 24, representing the hour with a 24-hour clock, i.e. 3 is 3AM, 15 is 3 PM.
Minute . A number, 0 to 60, representing the minute
within the hour
Seconds, A
decimal, 0 to 60 with two decimal places, representing the second and
milliseconds within the minute.
Milliseconds are only reported within 10 milliseconds.
GMTDIFF. A signed number representing the
difference between your local time and GMT (“Standard time”, or “Zulu”).
If no argument
is given then the date and time is returned in the format used for reports,
i.e. a CHAR(21) value like
“24 Jul 2013,
12:40:56”
Returns the
length of a field or group(generic reference). Data
type SMALLINT.
For a
fixed-length character string, the value returned is the declared length of the
string.
For a
varying length character string, the value returned is the current length of
the string.
Example
DEFINE R1 DATA(
C1 CHAR(20),
C2 VARCHAR(20),
LC1 SMALLINT,
LC2 SMALLINT);
R1.C1 = 'Robert';
R1.C2 = 'Robert';
R1.LC1 = $Len(R1.C1);
R1.LC2 = $Len(R1.C2);
R1.LC1
becomes 20, but R1.LC2 becomes 6.
For other field
types the value returned is the length required for storage, i.e. SMALLINT
returns 2, INTEGER returns 4, BIGINT returns 8, and so on.
For a reference
to the length of a group or record, the length is calculated to include the
full length of VARCHAR fields plus the extra two bytes of the length indicator. Thus $Len(R1.*) would return 46 (20 + 22 + 2 +
2) even though R1.C2 has a current length of
6.
If a record
contains a table, then the record length is calculated by multiplying the field
(or group) by the number of occurrences.
Thus
DEFINE R1 DATA(
C1 (5) CHAR(20),
C2 VARCHAR(20),
LR1 SMALLINT);
R1.LR1 = $Len(R1.*);
Sets R1.LR1 to 124 (5 * 20 + 20 + 2)
REDEFINES fields
are ignored. When you write
DEFINE R1 DATA(
C1 CHAR(20),
C1R CHAR(5) REDEFINES R1.C1,
…);
the
redefinition (C1R)
can’t use any storage that hasn’t already been counted, so it will be ignored
by $Len. It would have been an error had R1.C1R been longer than R1.C1.
This is
used qualified by a file name. For
example
CustF.Account =
custf.$LastKey +
1;
where Custf is defined
DEFINE
CustF VSAM DATA(
Account PIC '999999' HEADING 'Account Number'
KEY,
…
For a
reference to $LastKey to be valid,
1.
The
program must not be a BATCH program;
it must be either a classical CICS program or a web service.
2.
The
file must have type VSAM or SQL.
A statement such as
CustF.Account
=$Init;
sets the field to its initial value. This is the value defined in the field’s VALUE property if there is one, otherwise the default initial value will be SPACES for CHAR and VARCHAR fields, and ZERO for numeric fields. If the field has property OPTIONAL then the indicator fields are set to “Absent”.
If $Init is used in
an arithmetic expression, e.g.
R.Number
= R.Number
+ $Init;
then a value of 0 (ZERO) is used.
If $Init is used in a string expression, e.g.
W.CHAR20
= 'A string'
&& $Init
&& 'Some
more';
then a value of '', i.e. a zero-length string, is used.
$Null and $Init are identical except that with
an assignment
CustF.Account
=$Null;
I-level message 433 will be produced if the target field does not have the OPTIONAL property.
Jazz will include one or more return codes in an output message if the message contains a suitable field. ReturnCode fields are: -
1. Named JZ[-Filename]-ReturnCode, i.e. a ReturnCode named JZ-Orders-ReturnCode contains return codes relating to the Orders file. JZ-ReturnCode relates to unspecific messages, such as: an error has been found by ACCEPT validation.
2. ReturnCode values may be one of the following
a. ‘D’ A browse operation – either GET with an ambiguous operation (example: Name) or PROCESS – has reached the end of the qualifying records – “Endfile”
b. ‘E’ A CHECKSUM or CHECKSAVE error has been detected on I/O
c. ‘N’ GET or PROCESS has found no record(s) – Not Found.
d. ‘V’ ACCEPT validation has found one or more errors. This is associated with the general ReturnCode field, JZ-ReturnCode