DECdocument
Using Doctypes and Related Tags
Volume 2

The first input example shows a statement format in which a function has several forms.

#1

<STATEMENT_FORMAT> <ffunc>(real vbl\=ABS<VARIABLE>((real exp))) <ENDSTATEMENT_FORMAT>

The second input example shows the 3-argument form of the <FFUNC> tag.

#2

<STATEMENT_FORMAT> 
<FFUNC>(status\=AAA$CODE\(arg-one , arg-two ,arg-three ,arg-four ,arg-five 
,arg-six ,arg-seven)) 
<ENDSTATEMENT_FORMAT>

These input examples produce the following output:

Format

real vbl =ABS(real exp)

Format

status =AAA$CODE (arg-one , arg-two ,arg-three ,arg-four ,arg-five ,arg-six ,arg-seven)

<FORMAT>

Begins a section that illustrates the syntax of a routine, command, or tag, including keywords and arguments.

Syntax

<FORMAT> [(alternate heading)]

ARGUMENTS

alternate heading
This is an optional argument. It specifies a heading to override the current default text heading for this use of the <FORMAT> tag. The default heading provided by DECdocument is Format. See the reference description of the <SET_TEMPLATE_HEADING> tag for information on how to modify the default headings for all <FORMAT> tags.

related tags

<FARG>
<FARGS>
<FFUNC>
<FRTN>

required terminator

<ENDFORMAT>

DESCRIPTION

The <FORMAT> tag begins a section that illustrates the syntax of a routine, command, or tag, including keywords and arguments. This tag is a global tag and is not restricted to routine sections. However, in the context of the <ROUTINE_SECTION> and <TAG_SECTION> tags, the <FORMAT> tag enables certain additional tags for specialized format descriptions. These additional tags are not available outside the context of routine or tag sections.
The global <FORMAT> tag enables the <FCMD>, <FPARMS>, and <FPARM> tags, which label specific portions of a format statement. In a routine section, the <FORMAT> tag also enables these additional tags.
You can use the <FORMAT> tag and the tags it enables in a variety of ways to show the syntax of a routine. The following list of code examples show some of the most regularly used format section tag combinations:

<FRTN>(routine keyword) <FARGS>(argument list)
This is the standard form, in which the routine keyword and its argument list are separated by a blank space. If the output argument list is more than a single line, additional lines are aligned at the beginning of the argument list.

<FRTN>(routine keyword\argument list)
Use this form for routine functions, in which a routine and its arguments are not separated by blank spaces.
<FRTN>(return val\routine keyword\argument list)
This form provides three distinct elements for a routine description: the return value, the function name (shown here as the routine keyword), and the argument list.
<FRTN>(keyword part) <FARGS>(argument-1) <FARG>(argument-2)
This form is useful for routines with long argument lists and in which the argument names themselves are either long or need additional information.
<FFUNC>(routine keyword\argument list)
This form does not separate the routine name from its argument list and so is appropriate for function routines.
<FFUNC>(return val\routine keyword\argument list)
This form provides three distinct values: the return value, the function name, and the argument list.

Examples

The following example shows how to use the <FRTN> and <FARGS> tags in the context of the <FORMAT> tag to format a routine name and argument list. In this example, the argument list is null.

#1

<FORMAT> 
<FRTN>(SYS$HIBER) <FARGS>() 
<ENDFORMAT>

The following example shows how to use multiple <FFUNC> tags in a format section.

#2

<FORMAT> 
<ffunc>(MTH$SQRT\(x)) 
<ffunc>(MTH$DSQRT\(x)) 
<ffunc>(MTH$GSQRT\(x)) 
<ffunc>(MTH$HSQRT\(x)) 
<ENDFORMAT>

<FORMAT_SUBHEAD>

Introduces one of a set of multiple formats in a statement template.

Syntax

<FORMAT_SUBHEAD> (heading text)

ARGUMENTS

heading text
Specifies the text of the heading to be used before a specific format presentation.

related tags

<FCMD>
<FPARMS>
<STATEMENT_FORMAT>

restrictions

Valid only in the context of the <STATEMENT_FORMAT> tag if you specify the MULTIPLE keyword as the second argument to the <STATEMENT_FORMAT> tag in the Statement template.

DESCRIPTION

The <STATEMENT_FORMAT> tag introduces one of a set of multiple formats in a statement template.

Example

The following example shows how to use the <FORMAT_SUBHEAD> tag in a series of formats for a single statement.

<statement_format>(\multiple) 
<FORMAT_SUBHEAD>(String Variable To Array) 
<FCMD>(CHANGE) <FPARMS>(str exp <KEYWORD>(TO) num array) 
<FORMAT_SUBHEAD>(Array to String Variable) 
<FCMD>(CHANGE) <FPARMS>(num array <KEYWORD>(TO) str vbl) 
<endstatement_format>

This example produces the following output:

Format

String Variable To Array

CHANGE str exp TO num array

Array to String Variable

CHANGE num array TO str vbl

<FPARM>

Adds a single parameter line to a list of parameters in a command or statement syntax format section.

Syntax

<FPARM> (parameter)

ARGUMENTS

parameter
Adds a single parameter to a parameter list in a command or statement format section.

related tags

<FCMD>
<FPARMS>
<STATEMENT_FORMAT>
<STATEMENT_SECTION>

restrictions

Valid only after an <FCMD> tag and <FPARMS> tag sequence in a format section in the Command and Statement templates.

DESCRIPTION

The <FPARM> tag adds a single parameter line to a list of parameters in a command or statement syntax format section.

Example

The following example shows how to use the <FPARM> tag.

<format> 
<fcmd>(SET TERMINAL) 
<fparms>([device name[:]]) 
<fparm>(/DEVICE_TYPE=<list>(stacked\braces) 
                     <le><keyword>(UNKNOWN) 
                     <le><keyword>(LA34) 
                     <le><keyword>(VT100) 
                     <le><keyword>(PRO_SERIES)<endlist>) 
<fparm>(<list>(stacked\brackets) 
         <le>LINE_EDITING 
         <le>NOLINE_EDITING<endlist>) 
<fparm>(<list>(stacked\brackets) 
         <le>PASSALL 
         <le>NOPASSALL<endlist>) 
<ENDFORMAT>

This example produces the following output:

Syntax

SET TERMINAL [device name[:]]

/DEVICE _TYPE=

UNKNOWN
LA34
VT100
PRO_SERIES

/LINE_EDITING
/NOLINE_EDITING

/PASSALL
/NOPASSALL

<FPARMS>

Specifies the parameters to a command or statement keyword.

Syntax

<FPARMS> (parameter)

ARGUMENTS

parameter
Specifies the parameters to a command or statement keyword in a format section.
Use this command also to explicitly declare that a command or keyword marked with the <FCMD> tag has no parameters, as shown in this example.
<FCMD>(EXIT) <FPARMS>()
Parameters you specify using the <FPARMS> tag are printed differently than parameters specified in the parameter list argument to the <FCMD> tag. See the examples in this tag description for illustrations of the different output styles.

related tags

<COMMAND_SECTION>
<FCMD>
<FORMAT>
<FPARM>
<STATEMENT_FORMAT>

restrictions

Valid only in the context of the Command and Statement templates. The <FPARMS> tag should be used with the <FCMD> tag in the context of the <FORMAT> tag.

DESCRIPTION

The <FPARMS> tag specifies the parameters to a command or statement keyword. The command or keyword is identified with the <FCMD> tag. These tags should only be used in a format section. That is, they should only occur following the <FORMAT> tag and before the <ENDFORMAT> tag.
When you use this tag to define a parameter list that contains multiple words or text strings, include blank spaces between the words and text strings (including punctuation) according to the syntax rules of the command you are describing.
If the text of the parameter list argument will not fit on a single line in the format section, the text formatter selects suitable line breaks based on the presence of spaces in the parameter list text. Hyphenated text does not break across lines.
Use the <FPARM> tag to select explicit line breaks in a parameter list.

Examples

The following two input examples show how to use the <FPARMS> tag. Output from these coding examples appear after the second input example.
The following input example uses the <FPARMS> tag to list additional command keywords in the parameters portion of a command format.

#1

<FCMD>(ON) 
<FPARMS>(condition <keyword>(THEN [$]) command)

The following input example shows how to format a line in which command parameters appear before the command keyword.

#2

<FCMD>()<FPARMS>(input_specifier output_specifier<keyword>(/OVERLAY))

These input examples produce the following output:

Format

ON condition THEN[$] command

Format

input_specifier output_specifier/OVERLAY

<FRTN>

Specifies the routine-keyword portion of a routine syntax statement in the context of the <FORMAT> tag.

Syntax

<FRTN> ([return val\]routine keyword[\argument list])

ARGUMENTS

return val
This is an optional argument. It indicates that the routine's format includes the descriptive name of a variable. The routine returns a value to this argument. Note that this argument is optional.
routine keyword
Specifies the name of the first part of the format statement; typically, this is the routine name or an operating system keyword.
argument list
This is an optional argument. It specifies the arguments to be listed in the format statement.
Parameters specified in this argument are different from parameters specified using the <FARGS> tag. The Examples section in this description shows the differences.

related tags

<FARG>
<FARGS>
<FFUNC>

restrictions

If you specify <FRTN> with a null second argument, you should explicitly declare the absence of arguments using the <FARGS> tag as follows:
<FRTN>(KEYWORD PART) <FARGS>()
If you do not specify a second argument and do not specify the <FARGS> tag, DECdocument issues a warning message.

DESCRIPTION

The <FRTN> tag specifies the routine-keyword portion of a routine syntax statement in the context of the <FORMAT> tag.

Examples

The following four input examples show various uses of the <FRTN> tag. Output from these coding examples appears after the last input example.
The following input example shows how to specify a single routine keyword. The <FARGS> tag is explicitly specified as null.

#1

<format>(Syntax) 
<FRTN>($HIBER) <FARGS>() 
<ENDFORMAT>

The following input example specifies the routine keyword and its arguments using both the <FRTN> and <FARGS> tags. Note that blank spaces precede the commas that delimit the arguments. The spacing provides reasonable page-break points for use if the argument list does not fit in a single line of output.

#2

<frtn>($ENQ) <fargs>([efn] ,lkmode ,lksb ,[flags] 
,[resname] ,[parid] ,[astadr])

The following input example shows the output when two arguments are specified to the <FRTN> tag.

#3

<FRTN>(NBR$AAA\(command.rt.dx))

The following input example shows the 3-argument form of the <FRTN> tag.

#4

<FRTN>(status\=AAA$CODE\arg-one , arg-two ,arg-three ,arg-four ,arg-five 
,arg-six ,arg-seven)

These input examples produce the following output:

Syntax

$HIBER

Syntax

$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resname] ,[parid] ,[astadr]

Syntax

NBR$AAA (command.rt.dx)

Syntax

status =AAA$CODE arg-one , arg-two ,arg-three ,arg-four ,arg-five ,arg-six ,arg-seven

<FTAG>

Specifies the name of a tag and its arguments in the context of a <FORMAT> tag.

Syntax

<FTAG> (tag name[\argument list [\OPTIONAL]])

ARGUMENTS

tag name
Is the name of the tag. This name must be a valid tag name.
argument list
This is an optional argument. It lists the arguments, if any. If you do not specify this argument, you indicate that the tag has no arguments.
When you specify arguments, use the <ARG_SEP> tag to denote the argument separator character, the backslash (\).
OPTIONAL
This is an optional keyword argument. When you specify this keyword, the argument list argument is placed in square brackets to indicate that those arguments are optional.

related tags

<ARG_SEP>
<FORMAT>

restrictions

Valid only in a <FORMAT> tag section in the Tag template.

DESCRIPTION

The <FTAG> tag specifies the name of a tag and its arguments in the context of a <FORMAT> tag. This tag uses the <ARG_SEP> tag to create tag separator characters (\) in the argument list argument.
The <ARG_SEP> tag has no other function than to output the tag separator character (the backslash) in a Tag template format section.

Examples

The following four input examples show various uses of the <FTAG> tag. Output from these coding examples appears after the last input example.
The following input example shows how to use the <FTAG> tag to show the syntax of a tag that has no argument list.

#1

<format>(Syntax) 
<ftag>(OVERVIEW) 
<endformat>

The following input example illustrates how to specify the format of a tag that has a single optional argument by using the OPTIONAL keyword.

#2

<format> 
<ftag>(DESCRIPTION\heading text\OPTIONAL) 
<endformat>

The following input example illustrates how to specify a tag that has one required and two optional arguments. Note how the <ARG_SEP> tag separates the arguments.

#3

<format> 
<ftag>(ROUTINE\name[<arg_sep>info-1[<arg_sep>info2]]) 
<endformat>

The following input example shows a tag format in which all of the tag's arguments are optional and positional.

#4

<format> 
<ftag>(ROUTINE_SECTION\[running title]<line> 
[<arg_sep>prefix]<line> 
[<arg_sep>NEWPAGE]\OPTIONAL) 
<endformat>

These input examples produce the following output:

Format

<OVERVIEW>

Format

<DESCRIPTION> [(heading text)]

Format

<ROUTINE> (name[\info-1[\info2]])

Format

<ROUTINE_SECTION> [([running title]
[\prefix]
[\NEWPAGE])]

<FUNCTION>

Begins a new function description.

Syntax

<FUNCTION> (function name)

ARGUMENTS

function name
Specifies the name of the function to be described.

related tags

<SET_TEMPLATE_STATEMENT>
<STATEMENT>
<STATEMENT_SECTION>

DESCRIPTION

The <FUNCTION> tag begins a new function description. This description is for a single function in the context of the <STATEMENT_SECTION> tag. This tag has the following default format:

Each <FUNCTION> tag begins a new page of output.
Each output page carries a single running title, which is the current function name.
Use the <SET_TEMPLATE_STATEMENT> tag to replace the <FUNCTION> tag with a tag specific to your task (for example, <ABC_FUNCTION>), or to change the default attributes of the <FUNCTION> tag. See the description of the <SET_TEMPLATE_STATEMENT> tag in this chapter for more information.
Note that the <FUNCTION> and the <STATEMENT> tags work in exactly the same manner. The two tag names are provided so that you may encode your source file more generically.

Example

In the following example, the <STATEMENT_SECTION> tag enables the tags for a function description. The description of the function OPEN will, by default, have the following attributes:

The function description begins on a new page.
If the function carries for more than a page, the name OPEN is carried as a running top title on each page.
<STATEMENT_SECTION> <FUNCTION>(OPEN) <OVERVIEW>
<GRAPHIC>

Displays terminal graphics characters.

Syntax

<GRAPHIC> (char-1\char-2)

ARGUMENTS

char-1
Specifies the character to be used as the top portion of the graphics character.
char-2
Specifies the character to be used as the bottom portion of the graphics character.

related tags

<KEY>

DESCRIPTION

The <GRAPHIC> tag displays terminal graphics characters. It creates a single graphics terminal character (such as the linefeed or formfeed characters) by combining the two characters you specify as arguments. The second character you specify appears lower and adjacent to the first character.

Example

The following example shows how to use the <GRAPHIC> tag to create the linefeed and formfeed characters that can appear on a computer terminal.
<P> The <GRAPHIC>(F\F) and the <GRAPHIC>(L\F) are two characters that the terminal displays.
This example produces the following output:
The FF and the LF are two characters that the terminal displays.

Previous Next Contents Index

DECdocumentUsing Doctypes and Related Tags Volume 2

Format

real vbl =ABS(real exp)

Format

status =AAA$CODE (arg-one , arg-two ,arg-three ,arg-four ,arg-five ,arg-six ,arg-seven)

<FORMAT>

Syntax

<FORMAT> [(alternate heading)]

ARGUMENTS

alternate heading

related tags

required terminator

DESCRIPTION

Examples

<FORMAT_SUBHEAD>

Syntax

<FORMAT_SUBHEAD> (heading text)

ARGUMENTS

heading text

related tags

restrictions

DESCRIPTION

Example

Format

CHANGE str exp TO num array

CHANGE num array TO str vbl

<FPARM>

Syntax

<FPARM> (parameter)

ARGUMENTS

parameter

related tags

restrictions

DESCRIPTION

Example

Syntax

SET TERMINAL [device name[:]]

<FPARMS>

Syntax

<FPARMS> (parameter)

ARGUMENTS

parameter

related tags

restrictions

DESCRIPTION

Examples

Format

ON condition THEN[$] command

Format

input_specifier output_specifier/OVERLAY

<FRTN>

Syntax

<FRTN> ([return val\]routine keyword[\argument list])

ARGUMENTS

return val

routine keyword

argument list

related tags

restrictions

DESCRIPTION

Examples

Syntax

$HIBER

Syntax

$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resname] ,[parid] ,[astadr]

Syntax

NBR$AAA (command.rt.dx)

Syntax

status =AAA$CODE arg-one , arg-two ,arg-three ,arg-four ,arg-five ,arg-six ,arg-seven

<FTAG>

Syntax

<FTAG> (tag name[\argument list [\OPTIONAL]])

ARGUMENTS

tag name

argument list

OPTIONAL

related tags

restrictions

DESCRIPTION

Examples

DECdocument
Using Doctypes and Related Tags
Volume 2

<ROUTINE_SECTION> [([running title]
[\prefix]
[\NEWPAGE])]