Quick guide to F$FAO()

From VSI OpenVMS Wiki
Jump to: navigation, search

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