DECdocument
Using Doctypes and Related Tags
Volume 2

Contents

Index

<DOCUMENT_ATTRIBUTES>

Enables doctype-specific tags that override the default design format of the SOFTWARE doctype.

Syntax

<DOCUMENT_ATTRIBUTES>

ARGUMENTS

None.

required terminator

<ENDDOCUMENT_ATTRIBUTES>

DESCRIPTION

The <DOCUMENT_ATTRIBUTES> tag enables doctype-specific tags that override the default design format of the SOFTWARE doctype. This tag can be used in three doctypes:

ARTICLE
REPORT
SOFTWARE
The <DOCUMENT_ATTRIBUTES> tag enables a group of tags in each of these doctypes that allow you to modify the default format of that doctype. These tags are recognized only in the context of the <DOCUMENT_ATTRIBUTES> tag. If other DECdocument tags occur in this context, they are ignored just as if they had occurred in the context of a <COMMENT> tag.
Typically, use the <DOCUMENT_ATTRIBUTES> tag at the beginning of an input file (or in a file specified using the /INCLUDE qualifier in the DOCUMENT command line) to alter the default format of a doctype for the processing of that entire file.
Table 2-12 summarizes the formatting tags enabled by the <DOCUMENT_ATTRIBUTES> tag in the SOFTWARE doctypes.

Table 2-12 Doctype-specific Tags Enabled by the<DOCUMENT_ATTRIBUTES> Tag
Formatting Tags Description

<SET_RUNNING_TITLES>(BY_HEADONE) The <SET_RUNNING_TITLES> tag specifies that the running title at the top of each page is composed of two lines: the first line is the title of the chapter, and the second line is the heading text of the current <HEAD1> tag. Note that the argument BY_HEADONE is required.
By default, the chapter title is used as a single-line running title.

**Table 2-12 Doctype-specific Tags Enabled by the<DOCUMENT_ATTRIBUTES> Tag**
Formatting Tags	Description
<SET_RUNNING_TITLES>(BY_HEADONE)	The <SET_RUNNING_TITLES> tag specifies that the running title at the top of each page is composed of two lines: the first line is the title of the chapter, and the second line is the heading text of the current <HEAD1> tag. Note that the argument BY_HEADONE is required. By default, the chapter title is used as a single-line running title.

Example

The following example of a file processed with the SOFTWARE doctype shows how you specify a 2-line running title using the <SET_RUNNING_TITLES> tag. This title has the title of the current chapter as the first line, and the heading text of the current <HEAD1> tag as the second line.

<DOCUMENT_ATTRIBUTES> 
<SET_RUNNING_TITLES>(BY_HEADONE) 
<ENDDOCUMENT_ATTRIBUTES>

<EXAMPLE_SEQUENCE>

Begins a numbered sequence of informal examples.

Syntax

<EXAMPLE_SEQUENCE> [(

EXAMPLE
heading text
NOHEAD
\NONUMBER)]

ARGUMENTS

EXAMPLE
This is an optional keyword argument. It causes the singular heading Example to be output. It also suppresses numbering of the example. Use this argument when you supply only one example.
heading text
This is an optional argument. It causes the specified text to be used as a heading rather than the default heading Examples.
NOHEAD
This is an optional keyword argument. It suppresses the output of a heading for the section.
NONUMBER
This is an optional keyword argument. It suppresses numbering of the examples. When EXAMPLE is supplied as the first argument, the NONUMBER argument is unnecessary.

related tags

<EXAMPLES_INTRO>
<EXC>
<EXI>
<EXTEXT>

required terminator

<ENDEXAMPLE_SEQUENCE>

DESCRIPTION

The <EXAMPLE_SEQUENCE> tag begins a numbered sequence of informal examples. Use this tag (and the tags it enables to create the examples) inside or outside the reference templates.
Even though the examples are numbered, they are generally not referred to by these numbers. Instead, explanatory text directly follows each example. The example sections in this chapter provide examples of output from the <EXAMPLE_SEQUENCE> tag.
Following the <EXAMPLE_SEQUENCE> tag, each example begins with either the <EXC> or <EXI> tags. Use the <EXC> tag to present code examples; use the <EXI> tag to present interactive examples. Use the <EXTEXT> tag to terminate an example begun using the <EXI> or <EXC> tags and to begin the text that explains the example.
For some doctypes the <EXC> and <EXI> tags use the full page width, which causes the example to begin on the far left of the page. The <EXTEXT> tag, however, causes the text to be left justified at the normal text margin.

Example

The following example shows two short interactive examples, a code example, and their explanatory text. The <S> and <U> tags label the system and user portions of the interaction.

<example_sequence>(Debugging Examples) 
<exi><s>(DBG> )<u>(SCROLL/LEFT) 
<extext>This command scrolls the screen left by 8 spaces or columns. 
<exi><s>(DBG> )<u>(SCROLL/UP:4) 
<extext>This command scrolls 4 lines up through the display. 
<exc>PSL:  CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 
       0   0  0   0  USER   USER   0   0  0  1  0 0 0 0 
                                                  !Display formatted the PSL. 
                                                  !All bits are cleared. 
<extext> 
This shows you the contents of the PSL after issuing the EXAMINE command. 
<endexample_sequence>

This example produces the following output:

Debugging Examples

#1

DBG> SCROLL/LEFT

This command scrolls the screen left by 8 spaces or columns.

#2

DBG> SCROLL/UP:4

This command scrolls 4 lines up through the display.

#3

PSL:  CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 
       0   0  0   0  USER   USER   0   0  0  1  0 0 0 0 
                                                  !Display formatted the PSL. 
                                                  !All bits are cleared.

This shows you the contents of the PSL after issuing the EXAMINE command.

<EXAMPLES_INTRO>

Provides introductory text before an example.

Syntax

<EXAMPLES_INTRO>

ARGUMENTS

None.

related tags

<EXAMPLE_SEQUENCE>
<EXC>
<EXI>
<EXTEXT>

restrictions

Available only in the context of the <EXAMPLE_SEQUENCE> tag.

DESCRIPTION

The <EXAMPLES_INTRO> tag provides introductory text before an example.

Example

The following example shows introductory text to two interactive examples and their explanatory text.

<EXAMPLE_SEQUENCE>(Debugging Examples) 
<EXAMPLES_INTRO> 
The following examples show various uses of the DBG Utility: 
<EXI><S>(DBG>)<U>(SCROLL/LEFT) 
<EXTEXT> 
This command scrolls the screen left by 8 spaces or columns. 
<EXI><S>(DBG>)<U>(SCROLL/UP:4) 
<EXTEXT> 
This command scrolls 4 lines up through the display. 
<ENDEXAMPLE_SEQUENCE>

This example produces the following output:

Debugging Examples

The following examples show various uses of the DBG Utility:

#1

DBG>SCROLL/LEFT

This command scrolls the screen left by 8 spaces or columns.

#2

DBG>SCROLL/UP:4

This command scrolls 4 lines up through the display.

<EXC>

Begins a code example in a series of numbered informal examples.

Syntax

<EXC>

ARGUMENTS

None.

related tags

<EXAMPLE_SEQUENCE>
<EXAMPLES_INTRO>
<EXI>
<EXTEXT>
The global <CODE_EXAMPLE> tag

restrictions

Valid only in the context of the <EXAMPLE_SEQUENCE> tag.
The first line of the code example must be on the same source file line as the <EXC> tag.
Indexing tags such as <X> and <Y> tags are invalid in the context of the code example.

required terminator

<EXTEXT>

DESCRIPTION

The <EXC> tag begins a code example in a series of numbered informal examples. The text following the <EXC> tag is treated as the text of the code example until you terminate that example with the <EXTEXT> tag.
Use the <EXC> and <EXTEXT> tags much like the global <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags, with the exception that when using the <EXC> tag to begin a code example, the first line of the code example text must be on the same source file line as the <EXC> tag. This ensures that the code example formats correctly on the page.

Example

See the example in the <EXAMPLE_SEQUENCE> tag description.

<EXI>

Begins an interactive example in a series of numbered informal examples.

Syntax

<EXI>

ARGUMENTS

None.

related tags

<EXAMPLE_SEQUENCE>
<EXC>
<EXTEXT>
The global <INTERACTIVE> tag
The global <S> tag
The global <U> tag

restrictions

Valid only in the context of the <EXAMPLE_SEQUENCE> tag.
The first line of the interactive example must be on the same source file line as the <EXI> tag.

required terminator

<EXTEXT>

DESCRIPTION

The <EXI> tag begins an interactive example in a series of numbered informal examples. The text following the <EXI> tag is taken as the text of the interactive example until that example is terminated by the <EXTEXT> tag. Use the global <U> and <S> tags in the context of the <EXI> tag in the same way they are used in the context of the global <INTERACTIVE> tag.
The <EXI> and <EXTEXT> tags can be used just like the <INTERACTIVE> and <ENDINTERACTIVE> tags, with the exception that when using the <EXI> tag to begin an interactive example, the first line of the interactive example text must be on the same source file line as the <EXI> tag. This ensures that the interactive example formats correctly on the page.

Example

The following example shows how to use the <EXI> tag in the context of the <EXAMPLE_SEQUENCE> tag to begin an interactive example.
To produce a space between the DCL prompt and the user-entered command, include the space in the argument to the <S> tag.

<EXAMPLE_SEQUENCE>(DCL Examples) 
<EXI><S>($ )<U>(SHOW TIME) 
<S>(16-APR-1994 15:18:44) 
<EXTEXT>This example shows how to use the DCL command SHOW TIME to 
request a display of the date and time. 
<ENDEXAMPLE_SEQUENCE>

This example produces the following output:

$ SHOW TIME
16-APR-1994 15:18:44

This example shows how to use the DCL command SHOW TIME to request a display of the date and time.

<EXTEXT>

Terminates an example and begins an explanation in a sequence of numbered examples.

Syntax

<EXTEXT>

ARGUMENTS

None.

related tags

<EXAMPLES_INTRO>
<EXC>
<EXI>

restrictions

Required in the context of an <EXAMPLE_SEQUENCE> tag.

DESCRIPTION

The <EXTEXT> tag terminates an example and begins an explanation in a sequence of numbered examples. In an <EXAMPLE_SEQUENCE> tag section, each numbered example begins with either the <EXC> or <EXI> tag, depending on whether you want a code example or an interactive example. You terminate both kinds of examples with the <EXTEXT> tag, which labels the beginning of the text that explains the previous example.
Use the <EXAMPLES_INTRO> tag to place explanatory text before the first example in the example sequence. See the description of the <EXAMPLES_INTRO> tag for more information.

Example

See the examples in the <EXAMPLE_SEQUENCE> and <EXI> tag descriptions.

<FARG>

Adds a single argument line to a list of arguments in a routine syntax format section.

Syntax

<FARG> (argument name)

ARGUMENTS

argument name
Specifies a single-line item to be formatted for a routine's argument list.

related tags

<FARGS>
<FFUNC>
<FORMAT>
<FRTN>
<ROUTINE_SECTION>

restrictions

Valid only in the context of the <FORMAT> tag following an <FRTN> tag and an <FARGS> tag sequence.

DESCRIPTION

The <FARG> tag adds a single argument line to a list of arguments in a routine syntax format section.

Example

The following example shows how to use the <FARG> tag to format a routine that allows a number of keyword arguments, each of which may specify several values.

<format> 
<frtn>($FAB)<fargs>(ALQ = allocation quantity,) 
<farg>(BKS = bucket size,) 
<farg>(DEQ = extension quantity,) 
<farg>(DNA = default filespec address,) 
<farg>(FNA = filespec string address,) 
<farg>(ORG = <list>(stacked\braces) 
              <le>REL 
              <le>SEQ 
              <le>IDX<endlist>,) 
<farg>(RAT = <list>(stacked\braces) 
              <le>CR 
              <le><BLK FTN> 
              <le>PRN<endlist>,) 
<farg>(RTV = window size,) 
<farg>(SHR = <list>(stacked) 
              <le><PUT GET DEL 
              <le>UPD NIL MSE UPI><endlist>,) 
<farg>(XAB = xab address) 
<endformat>

This example produces the following output:

Format Sample

$FAB ALQ = allocation quantity,

BKS = bucket size,
DEQ = extension quantity,
DNA = default filespec address,
FNA = filespec string address,
ORG =

REL
SEQ
IDX
,
RAT =

CR
<BLK FTN>
PRN
,
RTV = window size,
SHR =

<PUT GET DEL
UPD NIL MSE UPI>
,
XAB = xab address

<FARGS>

Provides the argument portion of a routine syntax statement in the context of the <FORMAT> tag.

Syntax

<FARGS> (argument list[\STACK])

ARGUMENTS

argument list
Lists the routine arguments. If there are no arguments, specify the argument list as null in the following way:
<FRTN>($HIBER) <FARGS>()
Parameters specified in this argument differ on output from parameters specified using the second argument to the <FRTN> tag. For distinctions between these output differences, see the Examples section in the <FRTN> tag description.
STACK
This is an optional keyword argument. It specifies that the routine's argument list is not formatted on the same line as the routine name, but placed on the next line. This keyword is required only for long routine names in certain doctypes. See if the output looks wrong before you use this argument.

related tags

<FARG>
<FFUNC>
<FRTN>

restrictions

Use the <FARGS> tag with the <FRTN> tag in the context of the <FORMAT> tag in the Routine template.

DESCRIPTION

The <FARGS> tag provides the argument portion of a routine syntax statement in the context of the <FORMAT> tag.
When you use this tag to contain an argument list with multiple words or text strings, enter blank spaces between the words and text strings (including punctuation) according to the syntax rule of the routine you are describing. If the parameter list argument text does not fit on one line, suitable line breaks are chosen based on the presence of spaces. Hyphenated text is not broken across lines.
Select explicit line breaks in an argument list by using the <FARG> tag.

Examples

The following examples show how to use the <FARG> tag to code a format argument list in the context of a <FORMAT> tag in a routine section.
In the first example, the <FARGS> tag specifies a long argument list. By convention, if routine arguments are normally delimited by commas, you should place blank spaces in your SDML file preceding the commas. This allows suitable page breaks to be chosen during page composition.

#1

<FRTN>(LIB$CRF_OUTPUT) <FARGS>(ctl tbl ,width ,pag1 
,pag2 ,mode ind ,del sav ind)

This example produces the following output:

Syntax

LIB$CRF_OUTPUT ctl tbl ,width ,pag1 ,pag2 ,mode ind ,del sav ind

The following example shows how to position an argument list when a routine name is very long. You will want to use this form only if examination of your output indicates a formatting problem.

#2

<FRTN>(SMG$BEGIN_PASTEBOARD_UPDATE) 
<FARGS>(pasteboard id\stack)

This example produces the following output:

Syntax

SMG$BEGIN_PASTEBOARD_UPDATE

pasteboard id

<FCMD>

Specifies a statement or function keyword and an optional parameter list in the context of the <STATEMENT_FORMAT> tag.

Syntax

<FCMD> (statement keyword[\parameter list])

ARGUMENTS

statement keyword
Specifies the name of the first part of the format statement; typically, this is the principal statement name or the function name. This text outputs in the left portion of the format description.
parameter list
This is an optional argument. It specifies one or more parameters of the statement or function keyword. This text outputs to the right of the statement or function in the format description with no space between the statement keyword and the parameter list text.
Parameters you specify using the parameter list argument are output differently than parameters specified using the <FPARMS> tag. See the examples in this tag description for illustrations of these differences.

related tags

<COMMAND_SECTION>
<FORMAT>
<FPARMS>
<STATEMENT_FORMAT>

restrictions

Valid only in the context of the <FORMAT> or <STATEMENT_FORMAT> tags in the Statement template.
If you do not provide a second argument to the <FCMD> tag, you should explicitly declare the absence of parameters by using the <FPARMS> tag as follows:
<FCMD>(STATEMENT KEYWORD) <FPARMS>()
If you do not specify a second argument to the <FCMD> tag and the <FPARMS> tag is not specified, DECdocument issues a warning message.

DESCRIPTION

The <FCMD> tag specifies a statement or function keyword and an optional parameter list in the context of the <STATEMENT_FORMAT> tag. Use the parameter list argument to this tag to create a list of one or more parameters that format with no space between the statement or function keyword and the parameter list.
Use the <FPARMS> tag in conjunction with the <FCMD> tag to create a statement format with the statement or function keyword and the one or more parameters separated by a space.
If the text of the parameter list argument does not fit on a single line in the statement format section, the text formatter selects suitable line breaks based on the presence of spaces in the parameter list text. Hyphenated text is not broken across lines.

Examples

The following are five examples of various uses of the <FCMD> tag in the context of the <STATEMENT_FORMAT> tag. Output from these coding examples appear after the last input example.
The first input example specifies a statement keyword with no parameters. Use the <FPARMS> after the <FCMD> to explicitly specify the absence of any parameters.

#1

<STATEMENT_FORMAT> 
<FCMD>(EXIT) <FPARMS>() 
<ENDSTATEMENT_FORMAT>

The second input example also specifies a statement keyword with no parameters. This coding, however, specifies a null second argument to the <FCMD> tag rather than using the <FPARMS> tag to explicitly specify the absence of any parameters.

#2

<STATEMENT_FORMAT> 
<FCMD>(EXIT\ ) 
<ENDSTATEMENT_FORMAT>

The third input example specifies both the statement keyword and the parameter list arguments to the <FCMD> tag. Note in the output sample how these two arguments format together with no intervening spaces.

#3

<STATEMENT_FORMAT> 
<FCMD>(RETURN\ident_field, numeric_field) 
<ENDSTATEMENT_FORMAT>

The fourth input example specifies a statement keyword with a single parameter using the <FCMD> and <FPARMS> tags. Note that coding the parameters using the <FPARMS> tag outputs a space between the command keyword and the parameter.

#4

<STATEMENT_FORMAT> 
<FCMD>(RECORD) <FPARMS>(rec nam) 
<ENDSTATEMENT_FORMAT>

The fifth input example specifies the <FCMD> tag using the global <KEYWORD> tag as part of the parameter list argument text. Note how the global <KEYWORD> tag alters the output.

#5

<STATEMENT_FORMAT> 
<FCMD>(RETURN\ident_field, numeric_field,<keyword>([/LENGTH])) 
<ENDSTATEMENT_FORMAT>

These input examples produce the following outputs:

Format

EXIT

Format

RETURN ident_field, numeric_field

Format

RECORD rec nam

Format

RETURN ident_field, numeric_field,[/LENGTH]

<FFUNC>

Labels a function in the context of a <FORMAT> or <STATEMENT_FORMAT> tag section.

Syntax

<FFUNC> (

function name[\arg list]
return value\function name[\arg list]
)

ARGUMENTS

function name
Specifies the name of the function.
arg list
This is an optional argument. It specifies the function's argument list.
return val
This is an optional argument. It specifies a variable name to which a function returns its value.

related tags

<STATEMENT_FORMAT>

restrictions

Valid only in the context of the <STATEMENT_FORMAT> tag in the Statement template.

DESCRIPTION

The <FFUNC> tag labels a function in the context of a <FORMAT> or <STATEMENT_FORMAT> tag section. The <FFUNC> tag lets you create a syntax that includes the following:

The name of the function
The return value of the function
Any arguments that the function may require

Examples

The following two input examples show various uses of the <FCMD> tag in the context of the <STATEMENT_FORMAT> tag. Output from these coding examples appear after the second input example.

Previous Next Contents Index

DECdocumentUsing Doctypes and Related Tags Volume 2

<DOCUMENT_ATTRIBUTES>

Syntax

<DOCUMENT_ATTRIBUTES>

ARGUMENTS

required terminator

DESCRIPTION

Example

<EXAMPLE_SEQUENCE>

Syntax

<EXAMPLE_SEQUENCE> [( EXAMPLE heading text NOHEAD \NONUMBER)]

ARGUMENTS

EXAMPLE

heading text

NOHEAD

NONUMBER

related tags

required terminator

DESCRIPTION

Example

Debugging Examples

<EXAMPLES_INTRO>

Syntax

<EXAMPLES_INTRO>

ARGUMENTS

related tags

restrictions

DESCRIPTION

Example

Debugging Examples

<EXC>

Syntax

<EXC>

ARGUMENTS

related tags

restrictions

required terminator

DESCRIPTION

Example

<EXI>

Syntax

<EXI>

ARGUMENTS

related tags

restrictions

required terminator

DESCRIPTION

Example

<EXTEXT>

Syntax

<EXTEXT>

ARGUMENTS

related tags

restrictions

DESCRIPTION

Example

<FARG>

Syntax

<FARG> (argument name)

ARGUMENTS

argument name

related tags

restrictions

DESCRIPTION

Example

Format Sample

$FAB ALQ = allocation quantity,

<FARGS>

Syntax

<FARGS> (argument list[\STACK])

ARGUMENTS

argument list

STACK

related tags

restrictions

DESCRIPTION

Examples

Syntax

LIB$CRF_OUTPUT ctl tbl ,width ,pag1 ,pag2 ,mode ind ,del sav ind

Syntax

DECdocument
Using Doctypes and Related Tags
Volume 2

<EXAMPLE_SEQUENCE> [(

EXAMPLE
heading text
NOHEAD
\NONUMBER)]

<FFUNC> (

function name[\arg list]
return value\function name[\arg list]
)