Functions for Symbol Replacement

#### Search Results

Search

# Functions for Symbol Replacement

A symbol function is used to set a symbol value depending on the parameters provided for the function.

A symbol function is identified by either an exclamation mark (`!`) or a question mark (`?`) that is used as a start value. You can choose either character depending on the current code page used in your Natural environment. The exclamation mark (`!`) can conflict with code page conversion.

You can also perform your own symbol functions with a user exit routine. For details, see User Exits for Symbol Functions in the section User Exits.

The predefined symbol functions provided are explained in this section.

This document covers the following topics:

- Results Returned by a Symbol Function

- Function !D or ?D - Date Calculation and Date Formatting

- Function !E or ?E - Date from Date Calculation

- Functions !MV or ?MV and !MM or ?MM - Access to Multiple-Value Symbols

- Function !TIMN or ?TIMN - Constant Time Values

#### Related Topic:

- User Exits for Symbol Functions

## Results Returned by a Symbol Function

Results of symbol functions are written back to the active job’s symbol table after the first evaluation. The following invocations of the same symbol function with the same parameters do not invoke the symbol function again, but just return the function value.

Symbol functions with activation escape character are written to the active symbol table without escape character.

Symbol functions with submission escape character are written to the active symbol table with the submission escape character.

Notes:

1. The same symbol or symbol function can be used with both the activation escape character and the submission escape character. Both are handled separately and occupy different active symbol table entries. This is especially important if you use any time-dependent symbols or symbol functions.
2. Results of symbol functions are not kept in active symbol tables to enforce recalculation of symbol function values, for example, after the change of a multiple-value symbol.

## Function !D or ?D - Date Calculation and Date Formatting

(This symbol function replaces the obsolete symbol function !W or ?W.)

This symbol function calculates date values and formats them.

This section covers the following topics:

- Syntax

- Examples

- Return Format

- Parameters

- Edit Masks for Date Functions

- Reference Objects

- Output Date Formats

### Syntax

`§!D|?D<type|period|offset[offset-unit][,edit-mask][,calendar]>`

(for all types except `T`)

or

`§!D|?D<T[,edit-mask]>`

or

`§!D|?D<yyyymmdd,edit-mask>`

### Examples

    §!D<AC-1>

Get the date before the current date (yesterday). The date is returned in the default format YYYYMMDD.

    §?D<C20220722+1>

Get the next working day, for the date 2022-07-22. The date is returned in the default format YYYYMMDD.

The result will be 20220725, assuming that Saturday and Sunday are no working days in the related calendar.

    §?D<CW+1,DDMMYY>

Get the first day (Monday) of the current week in the format DDMMYY.

    §!D<T,YYMMDD>

Get the current date in the format YYMMDD.

    §!D<20070629,05>

Get the date 2007-06-29 in the format `05` (DD.MM.YY). See Output Date Formats.

    §!D<A1+1,MM>

Get the previous month in the format `MM` (month only).

    §!D<A1+1,YYYYMMDD>

Get the first day of the previous month.

    §!D<A1-1,YYYYMMDD>

Get the last day of the previous month.

### Return Format

See Output Date Formats.

### Parameters

The parameters are written one after the other without spaces.

Parameter/Syntax Element | Value | Description
--- | --- | ---
`type` | `T` | Today's date. For this type, the parameters `period`, `offset` and `offset-unit` are not required or evaluated.
`A` | All days (365 resp. 366 days a year).
`C` | Calendar days (days defined as working days in the calendar).
`S` | Schedule days.
`period` |  | Not evaluated for the type `T`.
`C` | From current day.
`YYYYMMDD` | From any given day, in format YYYYMMDD. Example: 20220722
`W` | Week.
`M` | Month.
`1` to `9` | One month back...nine months back.
`Q` | Quarter.
`Y` | Year.
`offset` |  | Positive or negative number with prefix.
`offset-unit` |  | Unit for the offset (optional); only evaluated for the type `A`.
`D` | Days (default).
`W` | Weeks.
`M` | Months.
`Q` | Quarters.
`Y` | Years.
`edit-mask` |  | See Edit Masks for Date Functions.
`calendar` |  | See Calendar in Reference Objects.
`yyyymmdd` |  | Date in the format YYYYMMDD.

For further explanations of date and time formats, see Date and Time Formats.

### Edit Masks for Date Functions

The edit mask can be entered either directly or with a format sign. The format sign can be used to shorten the function call.

Format Sign | Format | Example
--- | --- | ---
F1, 1 | DD | 29
F2, 2 | DDMM | 2910
F3, 3 | DDMMYY | 291008
F4, 4 | DDMMYYYY | 29102008
F5, 5 | DD.MM.YY | 29.10.08
F6, 6 | DD.MM.YYYY | 29.10.2008
F7, 7 | DD/MM/YY | 29/10/08
F8, 8 | DD/MM/YYYY | 29/10/2008
F9, 9 | DD-MM-YY | 29-10-08
F10, 10 | DD-MM-YYYY | 29-10-2008
F11, 11 | MM | 10
F12, 12 | MMDD | 1029
F13, 13 | MMYY | 1008
F14, 14 | MM.YY | 10.08
F15, 15 | MMYYYY | 102008
F16, 16 | MM.YYYY | 10.2008
F17, 17 | NN | We (Weekday; language-dependent.)
F18, 18 | O | 4 (Number of the weekday.)
F19, 19 | WW | 44 (Number of the week.)
F20, 20 | YY | 08
F21, 21 | YYJJJ | 08245
F22, 22 | YYMM | 0810
F23, 23 | YYMMDD | 081029
F24, 24 | YYYY | 2008
F25, 25 | YYYYJJJ | 2008245
F26, 26 | YYYYMM | 200810
F27, 27 | YYYYMMDD | 20081029
F28, 28 | YYYY.MM.DD | 2008.10.29
F29, 29 | YYYY/MM/DD | 2008/10/29
F30, 30 | YYYY-MM-DD | 2008-10-29
F31, 31 | YY.MM.DD | 08.10.29
F32, 32 | YY/MM/DD | 08/10/29
F33, 33 | YY-MM-DD | 08-10-29
F34, 34 | QQ | WE (Weekday; language-dependent; in upper case.)
F35, 35 | MMDDYY | 041922
F36, 36 | MM/DD/YY | 04/19/22
F37, 37 | MM-DD-YY | 04-19-22
F38, 38 | JJJ | 109
F39, 39 | JJJYY | 10922
F40, 40 | JJJYYYY | 1092022
F41, 41 | WWYY | 1622
F42, 42 | WWYYYY | 162022
F43, 43 | YYWW | 2216
F44, 44 | YYYYWW | 202216
F45, 45 | YY.MM or YY#MM | 22.04
F46, 46 | YY/JJJ | 22/109
F47, 47 | YYYY/JJJ | 2022/109

For further explanations of date and time formats, see Date and Time Formats.

### Reference Objects

Parameter/Syntax Element | Description
--- | ---
Owner | Owner of the network from which the function was called.
Calendar | If a calendar was specified explicitly, this is used for calendar calculations. This calendar must exist under the current owner. If it is not found there, it is searched for under the owner SYSDBA. Otherwise, the calendar of the current schedule is used. If no calendar has been defined, all days are treated as workdays. If an explicitly specified calendar is not existing for the current year, the JCL generation or the job submission will end with an error and a log message is written. Subnetwork considerations If the symbol function is invoked from within a subnetwork, the schedule or calendar of the top level (main calling network) is used for schedule or calendar calculation. Schedules or calendars defined in the subnetwork are ignored in such calculations. It is not necessary to define schedules or calendars in a network used only as a subnetwork because they are not relevant.

### Output Date Formats

The output date formats described here can be used in the symbol functions `!D` or `?D` and `!W` or `?W`.

The default date output format is YYYYMMDD (see also Date and Time Formats). It will be used if not output date format is specified.

Format | Numeric Equivalent | Example
--- | --- | ---
DD | 01 | 29
DDMM | 02 | 2910
DDMMYY | 03 | 291008
DDMMYYYY | 04 | 29102008
DD.MM.YY DD#MM#YY | 05 | 29.10.08
DD.MM.YYYY DD#MM#YYYY | 06 | 29.10.2008
DD/MM/YY | 07 | 29/10/08
DD/MM/YYYY | 08 | 29/10/2008
DD-MM-YY | 09 | 29-10-08
DD-MM-YYYY | 10 | 29-10-2008
JJJ | 38 | 245
JJJYY | 39 | 24508
JJJYYYY | 40 | 2452008
MM | 11 | 10
MMDD | 12 | 1029
MMDDYY | 35 | 102908
MMYY | 13 | 1008
MM.YY MM#YY | 14 | 10.08
MMYYYY | 15 | 102008
MM.YYYY MM#YYYY | 16 | 10.2008
MM/DD/YY | 36 | 10/29/08
MM-DD-YY | 37 | 10-29-08
NN | 17 | Sa (First two characters of the weekday name. This value depends on the current language setting of the Natural session.)
O | 18 | 6 (Number of the weekday. This value depends on the Natural profile parameter `DTFORM` of the Natural session. Refer to the Natural Parameter Reference documentation.)
QQ | 34 | SA (Like format `NN`, but in upper case.)
WW | 19 | 44 (Number of the week.)
WWYY | 41 | 4408 (Week and year.)
WWYYYY | 42 | 442008 (Week and year.)
YY | 20 | 08
YYJJJ | 21 | 08245
YYMM | 22 | 0810
YYMMDD | 23 | 081029
YYWW | 43 | 0844 (Year and week.)
YYYY | 24 | 2008
YYYYJJJ | 25 | 2008245
YYYYMM | 26 | 200810 (Year and month.)
YYYYMMDD | 27 | 20081029
YYYYWW | 44 | 200844 (Year and week.)
YYYY.MM.DD YYYY#MM#DD | 28 | 2008.10.29
YYYY/MM/DD | 29 | 2008/10/29
YYYY-MM-DD | 30 | 2008-10-29
YY.MM YY#MM | 45 | 08.10
YY.MM.DD YY#MM#DD | 31 | 08.10.29
YY/MM/DD | 32 | 08/10/29
YY-MM-DD | 33 | 08-10-29

For further explanations of date and time formats, see Date and Time Formats.

## Function !E or ?E - Date from Date Calculation

This symbol function is used to add or subtract a number of days from a given date in the format YYYYMMDD (see also Date and Time Formats).

This section covers the following topics:

- Syntax

- Examples

- Return Format

- Parameters

### Syntax

`§!E|?E<date,offset[,edit-mask]>`

### Examples

    §!E<20081029,+28>

    §!E<20081029,-7,F10>

### Return Format

Date in the format YYYYMMDD (see also Date and Time Formats).

### Parameters

The parameters are separated by a comma (`,`).

Parameter/Syntax Element | Description
--- | ---
`date` | Date in the format YYYYMMDD. See also Date and Time Formats.
`offset` | Positive or negative number with a plus (`+`) or minus (`-`) sign. Unit: days.
`edit-mask` | See Edit Masks for Date Functions.

## Functions !MV or ?MV and !MM or ?MM - Access to Multiple-Value Symbols

These symbol functions allow you to use multiple symbol values.

You can get the maximum index of a multiple-value symbol.

This section covers the following topics:

- Symbol Function !MV or ?MV

- Symbol Function !MM or ?MM

### Symbol Function !MV or ?MV

This symbol function allows you to use one single value of a multiple-value symbol.

> Syntax

>   `§!MV|?MV<symbol,index>`

> Examples

>       §!MV<ARRAY,1>

>       §?MV<ARRAY,§INDEX>

> Return Format

>   Integer value.

> Parameters

>   The parameters are separated by a comma.

>   Parameter/Syntax Element | Description
>   --- | ---
>   `symbol` | Name of the multiple-value symbol.
>   `index` | Index of the symbol value.

> Errors

>   In the following cases, a `Symbol not found` message is returned:

>   - Multiple-value symbol not found,

>   - Index missing,

>   - Index not numeric, and

>   - Index too high.

> Reference Objects

>   Parameter/Syntax Element | Description
>   --- | ---
>   Symbol table | The symbol table of the active job is always used.

### Symbol Function !MM or ?MM

This symbol function allows you to get the maximum index of a multiple-value symbol.

This function accesses single occurrences of a multiple-value symbol.

> Syntax

>   `§!MM|?MM<symbol>`

> Example

>       §!MM<ARRAY>

> Return Format

>   Symbol value.

> Parameters

>   This function has only one parameter.

>   Parameter/Syntax Element | Description
>   --- | ---
>   `symbol` | Name of the multiple-value symbol.

> Errors

>   In the following case, a `Symbol not found` message is returned:

>   - Multiple-value symbol not found.

> Reference Objects

>   Parameter/Syntax Element | Description
>   --- | ---
>   Symbol table | The symbol table of the active job is always used.

## Function !TIMN or ?TIMN - Constant Time Values

This symbol function allows you to use constant time values in multiple timestamp replacements.

This section covers the following topics:

- Syntax

- Examples

- Return Format

- Parameters

- Reference Objects

### Syntax

`§!TIMN|?TIMN<parm>`

### Examples

    §!TIMN<A>

    §?TIMN<B>

### Return Format

A timestamp in the format of the Natural system variable `*TIMN`:

Format: A7.

Content: HHIISST where T = tenths of seconds.

### Parameters

Syntax Element/Parameter | Description
--- | ---
`parm` | The parameter (for example, `A` or `B`) must be specified for syntactical reasons only and has not meaning otherwise. Note All invocations with the same parameter create the same time value (if the same active symbol table is used). The result of each combination of symbol function and parameter(s) is kept in the active symbol table for subsequent replacements. Example:
    //* line 1 - §TIMN<A>
    //* line 2 - §TIMN<B>
    //* line 3 - §TIMN<A>
The example above can be replaced as follows:
    //* line 1 - 1601331
    //* line 2 - 1601332
    //* line 3 - 1601331

### Reference Objects

None.

### On this page

- Results Returned by a Symbol Function
- Function !D or ?D - Date Calculation and Date Formatting
- Function !E or ?E - Date from Date Calculation
- Functions !MV or ?MV and !MM or ?MM - Access to Multiple-Value Symbols
- Function !TIMN or ?TIMN - Constant Time Values