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:

Related Topic:

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

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

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

For further explanations of date and time formats, see also 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.)

For further explanations of date and time formats, see also 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.

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 (see also Date and Time Formats).

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

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

For further explanations of date and time formats, see also 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

§!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

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, Symbol not found appears:

  • 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, Symbol not found appears:

  • 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

§!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

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.