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. 

 

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