Built-In Functions and Special Fields

Built-In Functions and Special Fields. 1

Introduction. 1

Built-in Functions. 1

$Now, $Today. 1

$Len(reference) 2

$LastKey. 3

Special Fields. 3

Return Code. 3

Planned Functions. 3

$Changed(field), $Same(field) 3

$JString(String field 1, String field 2 [,String field 3]…) 4

$Num(field), $String(field) 5

$Same. 5

$String(Reference to ENUM variable) 5

$String(Generic Reference) 5

$Trim(string field) 5

$Within(String1, String2) 6

 

Introduction

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, for which there are no Jazz $functions. 

 

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 Built-in Functions  ($Functions)

Jazz currently provides a small number of built in functions, all named starting with “$”.  This list will be extended in future Jazz releases. 

$Now, $Today

$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”

$Len(reference)

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.

$Len and tables.

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)

$Len and Redefinitions

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.

$LastKey

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.

$Init, $Null

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.

Special Fields

Return Code

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       

Planned Functions

As these functions are implemented, they’ll be moved above this heading.

$Changed(field), $Same(field)

These are comparison functions, testing “has this value changed?”

 

Returned Data Type: BIT(1)

 

1 argument which can be any field, group, or record. $Changed and $Same are opposites: wherever you use $Changed you could use NOT $Same, and vice versa.

 

These functions are usually used inside a process-block or a do-block to compare the value of a field with its value the last time the IF statement was executed. For example:

Process Record1 where Record1.Balance > 1000

                IF $Changed(Record1.State) THEN

                                PRINT (“First Record for “, Record1.State)

                End if

End Process

compares the value of State now with the value of State the last time this statement was executed.

 

Each use of the function is independent of any other use: $Changed(x) means “Has X changed since the last time that we were at this point in the program”.

 

On the first execution of the function it uses the initialised values:

•           Binary zeroes for character strings.

•           -99999 for INTEGER and SMALLINT.

•           -7.2E7.5 for FLOAT and LONG

•           Low values for numeric fields.

Where possible an “impossible” value is used as initial value: For example, with an ENUM field the initial value will be -1, but an ENUM does not allow defined values to be negative. The intention is to ensure that $Same is false and $Changed is true on the first execution. However Jazz™ can not always guarantee that the data doesn’t actually contain the initial value.

 

You may not use unary conditions in a WHERE or HAVING condition for RDB tables.

$Change, $Same with Arrays

$Change and $Same may refer to a subscripted variable. If the subscript changes between different tests, equal or not equal condition may result without assignment to the array.

 

For example, imagine a table defined

DEFINE (WORK) DATA( A  (3)   SMALLINT);

with values:

WORK.A(1)=1;

WORK.A(2)=2;

WORK.A(3)=3;

A test

IF $Same(WORK.A(Subscript)) THEN ...

 

If none of these values change but the subscript changes, then $Same will return “False” even though none of the values have change. Conversely, if the program executes: -
First test: values as above, subscript = 1

Second test: A(2) set to 1, Subscript = 2

$Same (WORK.A(Subscript)) will now return True, even though A(2) has changed in value.

$Same

See $Changed

$String(Reference to ENUM variable)

See $Num

$String(Generic Reference)

If the Generic Reference is to anything except a TYPE(SQL) file then STRING(File.*) is a reference to the record layout as if it were a single CHAR(??) variable. This allows you to write statements like: -

LastRecord = $String(Input.*)

and

IF @String(Record1) = $String(Record2) THEN

    ….

$Mid(string field, Start, Length)

$Trim(string field)

Returns a character string with the leading and trailing blanks removed. Thus if you had defined Name as CHAR(30), and then assigned

R1.Name = ‘bbbRobert’;

then Name will have value “bbbRobertbbbbbbbbbbbbbbbbbbbbb” (“b” represents a blank). Because Name is a fixed length character string, its length is always 30.

 

$Trim(R1.Name) has value “Robert”, and length 6.

$Within(String1, String2)

Returns True if String2 is found within String1, False if not. For example,

R1.Name = ‘Robert Barnes’

IF $Within(R1.Name, ‘Barn’) THEN

    …

Here ‘Barn’ is within the value of R1.Name, i.e. within ‘Robert Barnes’, and so $Within returns “True”.