FMT

Retrieves Data Name from String

This string function returns the value of a data name in a formatted string.

Syntax

FMT(str-val[,elem-num[,occ-num]][,ERR=line-ref|,ERC=error-code])
[:fmt-mask]

str-val

is any string, which contains the name of a format or data name.

elem-num

is a positive integer that specifies the data element to be referenced. The element number must be 0 if a data name is specified.

occ-num

is a positive integer that specifies the occurrence of a data element.

fmt-mask

is a string value that serves as the mask to be used in formatting the function's result or one of the following:

"DNM"

default no comma mask

"DCM"

default comma mask

" "

do not mask

line-ref

is the program line number or label to branch to in the event of an error.

error-code

is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

The retrieved value will be converted from storage according to the fixed attributes of the specified data element.

When the fmt-mask “DNM” is specified, the data name’s value is formatted with the mask returned from option 25 of the ATR( ) function.

When the fmt-mask “DCM” is specified, the data name’s value is formatted with the mask returned from option 26 of the ATR( ) function.

For data elements with date types 1, 2, 3, or 5 and length 4 (INFORMIX SQL), when no fmt-mask is specified, the format of the value retrieved will be in the following system date formats:

Date format	Input format
M	“MMDDYY”
D	“DDMMYY”
Y	“YYMMDD”

When either “DNM” or “DCM” is specified for the fmt-mask, the format of the value retrieved will be in system date format with the system date delimiter as follows:

Date format	Input format
M	“MM?DD?YY”
D	“DD?MM?YY”
Y	“YY?MM?DD”

? represents the system date delimiter.

For data elements with date type 5 and length 6 (normal SQL), when no fmt-mask is specified, the format of the value retrieved will be in system date format plus the time value, if non-zero as follows:

Date format	Input format
M	“MMDDYY”[+“HHMISS”]
D	“DDMMYY”[+“HHMISS”]
Y	“YYMMDD”[+“HHMISS”]

When either “DNM” or “DCM” is specified for the fmt-mask, the format of the value retrieved will be in system date format plus the time value, if non-zero, with the system date delimiter as follows:

Date format	Input format
M	“MM?DD?YY”[+” HH:MI:SS”]
D	“DD?MM?YY”[+” HH:MI:SS”]
Y	“YY?MM?DD”[+” HH:MI:SS”]

? represents the system date delimiter.

An attempt to reference an invalid format/data name results in an ERR=17.

An attempt to reference a format name without a data element number results in an ERR=17.

An attempt to reference a data name with a data element number results in an ERR=17.

An attempt to reference a format name that the data dictionary or current program does not recognize results in an ERR=161.

An attempt to reference a data name that does not exist in the format’s data element table, either by name or by element number, results in an ERR=163.

An attempt to reference an occurrence number of an element that is defined without multiple occurrences will result in an ERR=164.

An attempt to reference an invalid occurrence number of an element that is defined with multiple occurrences will result in an ERR=165.

Examples

The following examples assume that a format named “DNFFMT” has been successfully INCLUDEd and the format data area has been populated. The format consists of the following data elements:

ElemNum

Name Length NumType Date Type

1. DN-STRING 20 - -
2. DN-BINNUM 8.4 3 -
3. DN-STR-OCC 10*4 - -
4. DN-IEEE-OCC 8.4 9 -
5. DN-SQLDATE 6 - 5

READ(channel) #DNFFMT
FMT$="#DNFFMT"
STR$=FMT(FMT$,1)

stores the value of #DNFFMT.DN-STRING into STR$.

PRINT FMT(FMT$,2):"DNM"

prints the value of #DNFFMT.DN-BINNUM, masked via the default no-comma mask.

OCCURS=NUM(ATR(FMT$,3,18));
DIM STR$[1:OCCURS];
FOR OCC=1 TO OCCURS;
      STR$[OCC]=FMT(FMT$,3,OCC);
NEXT OCC

stores the values of the first, second, third, and fourth occurrences of
#DNFFMT.DN-STR-OCC into the elements of the string array STR$[ ].

DNM$=FMT$+"."+ATR(FMT$,4,21);
FOR OCC=1 TO NUM(ATR(DNM$,0,18));
      PRINT FMT(DNM$,0,OCC):"DCM";
NEXT OCC

prints the values of the first, second, third, and fourth occurrences of #DNFFMT.DN-IEEE-OCC, masked via the default comma mask.

DNM$=FMT$+"."+ATR(FMT$,5,21);
DATE$=FMT(DNM$):"DNM"

stores the value of #DNFFMT.DN-SQLDATE into DATE$. The retrieved value will be in system date format plus time value and will not contain the system date or time delimiters.

See also

LET FMT directive
ATR function

From the Thoroughbred Basic Language Reference, Volume II: F–Q, version 8.9.1. Open this page in the PDF