Quick guide to F$FAO()

F$FAO() can be used to create good-looking formatted output including tables, dividers, numeric conversion, and more. The full list of F$FAO() control strings can be found in the main article.

Choosing a control string

You need to insert...	Directive to use	Example	Result
a string	!AS	f$fao("Welcome back, !AS","John")	Welcome back, John
a singular/plural (more below	!%S	f$fao("I have !ZL apple!%S",5") f$fao("I have !ZL apple!%S",1")	I have 5 apples I have 1 apple
a number	!SL	f$fao("!SL",-112)	-112
the current time	!%T	f$fao("It's !%T now",0)	It's 12:14:55.90 now
the current date/time	!%D	f$fao("It's !%D now",0)	It's 16-AUG-2018 12:15:02.28 now
a new line	!/	f$fao("hello !/ goodbye")	$ write sys$output f$fao("hello !/goodbye")<br>hello<br>goodbye
a line of dashes/asterisks	!n*-	f$fao("!25*-!/")	-------------------------
put it in a field	!nDD	f$fao("Total: !20SL",73)	Total: 73

• To insert an actual exclamation point, use two exclamation points:

$ write sys$output f$fao("Hello!!")
Hello!

• Watch your argument types. If you use a wrong type of argument, such as an integer for !AS, you will get %SYSTEM-F-ACCVIO, access violation message.

Dealing with plurals

There is a special directive for English plurals (that are normally just -s): !%S. It inserts an "s" if the most recently converted number is not 1:

$ write sys$output f$fao("I have !SL apple!%S",5)
I have 5 apples
$ write sys$output f$fao("I have !SL apple!%S",1)
I have 1 apple

There is also a different directive that lets you use other endings. For example, if you have the word "child", the regular "s" will not work there. Here's what you can use:

• !n%Cyour_ending inserts a character string (your_ending) when the most recently evaluated argument has the value n
• !%Eyour_ending inserts a character string (your_ending) when the most recently evaluated argument does not match any of the preceding !n%C directives.
• When you are done defining the forms of that single word, use the !%F directive to mark the end of the plurals statement.**

So, for the case with child, you need the system to use no ending if the number is 1 and the ending "ren" if the number is anything but one:

$ write sys$output f$fao("I have !SL child!1%C !%Eren !%F",1)
I have 1 child
$ write sys$output f$fao("I have !SL child!1%C !%Eren !%F",5)
I have 5 children

Another example is offered by the online help on F$FAO:

REPORT = F$FAO("There !0UL!1%Cis!%Eare!%F !-!UL !-!0UL!1%Cchild!%Echildren!%F here",OFFSPRING)

Here's how this works for languages with multiple number forms. For example, let's count cats in Polish:

$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",1)
1 kot
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",2)
2 koty
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",3)
3 koty
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",4)
4 koty
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",5)
5 kotow
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",6)
6 kotow
$ write sys$output f$fao("!SB kot!1%C !2%Cy !3%Cy !4%Cy !%Eow !%F",7)
7 kotow