A symbol function is used to replace symbols through the JCL of a job based on the conditions defined with the function. The same JCL can be used for different purposes, such as, changing the standard layout and output of symbols, job input conditions or end-of-job actions.

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 from Today Calculation

• 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

• Function !W or ?W - Date Calculation with Reference Calendar

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 submit escape character are written to the active symbol table with the submit escape character.

Notes:

1. The same symbol or symbol function can be used with both the activation escape character and the submit 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 from Today Calculation

This symbol function calculates date values from the current date.

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<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.

Syntax Element	Parameter	Explanation
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.
	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.

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)

Reference Objects

Syntax Element	Meaning
Owner	The 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 working days. 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.

If this parameter is missing or if an unknown format has been used, the date is returned in the format YYYYMMDD (example: 20070629).

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 (example: 20081029).

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 2 characters of name of weekday. This value depends on the current language setting of the Natural session.)
O	18	6 (Number of 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 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

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.

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.

Parameters

The parameters are separated by a comma.

Syntax Element	Description
date	Date in the format YYYYMMDD.
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.

Syntax Element	Description
symbol	Name of the multiple-value symbol.
index	Index of the symbol value.

Errors

In the following cases, Symbol not found appears:

• Multiple symbol not found,

• Index missing,

• Index not numeric, and

• Index too high.

Reference Objects

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.

Syntax Element	Description
symbol	Name of the multiple-value symbol.

Errors

In the following case, Symbol not found appears:

• Multiple symbol not found.

Reference Objects

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 time stamp in the format of the Natural system variable *TIMN:

Format: A7,

Content: HHIISST where T = tenths of seconds.

Parameters

Parameter	Explanation
parm	The parameter is a dummy. But note that all invocations with the same parameter create the same time value (if the same active symbol table is used).

Reference Objects

None.

Function !W or ?W - Date Calculation with Reference Calendar

This symbol function allows you to use date calculations relative to a calendar.

This section covers the following topics:

• Main Syntax

• Parameter

• Return Format

Main Syntax

§!W|?W< formula>

[,<edit-mask>]

[,<owner>]

[,<calendar>]

Symbol containing four arguments as values. This symbol itself can be composed of symbols. The activation or submission escape character of the invoking active job is in effect.

Syntax of formula:

<date><period>

<point><just-in-period><offset>

<unit><point>

<just-in-unit>

Syntax of edit-mask:

<date-format>

<number-unit><period><supression><just>

<name-unit><language><character><length>

Parameter

Syntax Element	Possible Values
formula
date	Reference date in the valid Natural date format: YYYYMMDD, YYMMDD, DDMMYYYY or DDMMYY. MM, DD, [YY]YY can be separated by a slash (/), a dash (-) or a period (.). Note: To avoid ambiguous date format interpretations, it is highly recommended to use a 4-digit year format. If a 6-digit date cannot be interpreted uniquely, the symbol function returns with an error message like: 040107A / MM is ambiguous.
period	A	Days.
	C	Working days.
	W	Week.
	M	Month.
	Q	Quarter.
	S	Semester.
	Y	Year.
	The limits of the date period are only left if <offset>*<unit> is longer (or equal to) the period. If <offset>*<unit> is shorter than the period, but would not match the beginning or end of the period, the first or the last (working) day of the period is returned.
point	F	First day in period or unit.
	L	Last day in period or unit.
	S	Calculated date in period or unit.
just-in-period	B	If holiday, before.
	A	If holiday, after.
offset	Integer preceded by sign.
unit	Like period.
just-in-unit
edit-mask
date-format	Date in the format D. See also Output Date Formats described for the symbol function !D or ?D.
number-unit	Number in the format N. Number of the unit in the period. This implies that the specified period must be larger than the unit. Same values as for period.
period	Same values as for period.
suppression	Z for suppression of leading zeroes.
just	R	Right justified.
	L	Left justified.
name-format	Name in the format C.
name-unit	D	Day.
	M	Month.
language	1	English.
	2	German.
	nn	Valid Natural language code.
character	U	Name only in upper-case letters.
	L	Only first character in upper case.
length	Display length.
owner	Owner of the reference calendar.
calendar	Reference calendar for date calculation. If the formula contains a calendar reference such as C for working day, B for working day before holiday or working day after holiday, the specification of a reference calendar is mandatory.

Return Format

See Output Date Formats described for the symbol function !D or ?D.