DECdocument
Using Doctypes and Related Tags
Volume 2
Previous Contents Index

2.16.2 Sample Output File of the Routine Template

The following is the output from the extended code example in Section 2.16.1, produced using the SOFTWARE.REFERENCE doctype design. Note that your own output may vary, depending on the SOFTWARE design under which you process the SDML file.

$ENQ

This is the brief description section. It contains one or two sentences describing what the routine does.

Syntax

$ENQ [efn], lkmode, lksb, itmlst

RETURNS

VMS usage: cond_value
type: longword integer
access: read only
mechanism: by value in R0

At times, it may be necessary to include a sentence or two here to further describe the nature of the information returned.

ARGUMENTS

efn


VMS usage: cond_value
type: longword integer
access: read only
mechanism: by value

Number of the event flag that is to be set when access is granted to the specified resource. If not specified, the default is event flag number 0.

lkmode


VMS usage: cond_value
type: longword integer
access: read only
mechanism: by descriptor

Name of lock mode requested. May be one of the following:
Name of Lock Mode Description
LCK$K_NLMODE Null lock mode
LCK$K_CRMODE Concurrent read mode
LCK$K_CWMODE Concurrent write mode

lksb


VMS usage: cond_value
type: longword integer
access: write only
mechanism: by value

Address of the lock status block. The lock status block receives the final completion status and lock I.D., and optionally contains a lock value block.

itmlst

Item list specifying the lock information that $GETLKI is to return. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0. 


       31                       15                        0 
       +--------------------------------------------------+ 
       |      item code         |     buffer length       | 
       +------------------------+-------------------------+ 
       |                 buffer address                   | 
       +--------------------------------------------------+ 
       |             return length address                | 
       +--------------------------------------------------+

DESCRIPTION

This section contains the full, detailed description of the routine. It may contain tables and figures. There is no fixed size for this description section.

Return Values

SS$_NORMAL Indicates successful completion.
SS$_ABORT This description contains a full explanation of some of the possible causes for the abortion.
SS$_DEADLOCK This description contains a full explanation of some possible causes for the deadlock situation.

Examples

This section contains an example of the use of the routine. This section can also contain figures and tables.

MTH$xSQRT

The square root procedure returns the square root of the input parameter. The input parameter may have one of four data types: F_Floating, D_Floating, G_Floating, and H_Floating.

Syntax

MTH$SQRT (x)

MTH$DSQRT (x)

MTH$GSQRT (x)

MTH$HSQRT (x)

RETURNS

VMS usage: cond_value
type: F_Floating, D_Floating, or G_Floating
access: write only
mechanism: by value in R0

RETURNS

The square roots of F_Floating, D_Floating, and G_Floating input parameters are returned by immediate value in R0 and R1. The square root of an H_Floating parameter is returned by reference in the output parameter sqrt.

ARGUMENT

x


VMS usage: cond_value
type: F_Floating,D_Floating, G_Floating, or H_Floating
access: read only
mechanism: by reference

The number for which the square root is desired.

sqrt


VMS usage: cond_value
type: H_Floating
access: write only
mechanism: by reference

The square root of the H_Floating parameter.

DESCRIPTION

This is a description of the MTH$xSQRT function.

2.17 Using the Statement Template

Table 2-10 summarizes the tags available in the Statement template, the default headings associated with them, and how they should be used. The table presents the tags in the same order as in the template in directory DOC$TEMPLATES.

Use these tags to create a statement reference section. In most manuals, a statement reference section describes each statement the software offers: its purpose and detailed format, plus examples of its use.

This section also contains a sample input and output file using the Statement template. You may find these sample files useful in understanding how the Statement template tags fit together.

These samples describe the RECORD statement and the MID$ function. They are intended only as samples, and should not be used as a source of reference for these statements and functions.

Table 2-10 Statement Template Tags as Available from DOC$TEMPLATES
Tag Name Default
Heading 		Template Usage
<STATEMENT_SECTION> None Begins a Command section
<SET_TEMPLATE_STATEMENT> None Alters the default format of a Statement section
<SET_TEMPLATE_HEADING> None Alters the default headings in a reference section
<SET_TEMPLATE_PARA> None Creates user-defined tags for the creation of a specially formatted paragraph in a reference section
<SET_TEMPLATE_LIST> None Creates user-defined tags for a specially formatted list in a reference section
<SET_TEMPLATE_TABLE> None Creates user-defined tags for a specially formatted table in a reference section
  • <STATEMENT>¹
  • <FUNCTION>
None Begins each new element to be referenced in the template; this is the default reference element tag in the Statement reference template
<OVERVIEW> None Labels an overview of the reference element
<STATEMENT_FORMAT> Format Labels the format of the reference element's syntax
<FORMAT> Format Labels the format of the reference element's syntax
<DESCRIPTION> Description Labels a reference element description section
<EXAMPLE_SEQUENCE> Examples Begins a sequence of one or more examples

¹The use of braces indicates that the enclosed tag names are used interchangeably. DECdocument provides two such names to improve the readability of your SDML file.

2.17.1 Sample SDML File of the Statement Template

The following is an extended code example showing a DECdocument SDML file that uses the Statement template: 


 
<STATEMENT_SECTION>(Using the SOFTWARE Doctype\\NEWPAGE) 
<STATEMENT>(RECORD) 
 
<OVERVIEW> 
The RECORD statement lets you name and define data structures in a 
BASIC program and provides the BASIC interface to the VAX Common Data 
Dictionary (CDD).  You can use the defined RECORD name anywhere a 
BASIC data-type keyword is valid. 
<ENDOVERVIEW> 
 
<STATEMENT_FORMAT> 
<FCMD>(RECORD) 
<FPARMS>(rec nam) 
<STATEMENT_LINE>(rec component) 
<ELLIPSIS> 
<FCMD>(END RECORD) 
<FPARMS>([ rec nam ]) 
<construct_list>(rec component:) 
<construct>(rec component:)<list>(stacked\braces) 
                   <le>data type rec item [ , [ data type ] rec item ] 
                   <le>group clause 
                   <le>variant clause<endlist> 
<construct>(rec item:)<list>(stacked\braces) 
                       <le>unsubs vbl [ = int const ] 
                       <le>array ( int const,...) [ = int const ] 
                       <le><keyword>(FILL) [ ( int const ) ] [ = int const ]<endlist> 
<construct>(group clause:) 
    <keyword>(GROUP) group nam [ ( int const,... ) ] 
    <statement_line>(rec component\indent) 
    <ellipsis> 
    <statement_line>(<keyword>(END GROUP) [ group nam ]) 
<construct>(variant clause:) 
     <keyword>(VARIANT) 
     <statement_line>(case clause\indent) 
     <ellipsis> 
     <statement_line>(<keyword>(END VARIANT)) 
<construct>(case clause:) 
     <keyword>(CASE) 
     <statement_line>([ rec component ]\indent) 
<endconstruct_list> 
 
<ENDSTATEMENT_FORMAT> 
 
<function>(MID$) 
 
<OVERVIEW> 
The MID$ function extracts a specified substring from the middle of a 
string, leaving the main string unchanged. 
<ENDOVERVIEW> 
 
<STATEMENT_FORMAT> 
<fcmd>()<fparms>(str vbl =<list>(stacked\braces) 
        <le>MID 
        <le>MID$ <endlist> <keyword>((str exp, int exp1, int exp2))) 
<ENDSTATEMENT_FORMAT> 
 
<ENDSTATEMENT_SECTION>

2.17.2 Sample Output File of the Statement Template

The following is the output from the extended code example in Section 2.17.1, produced using the SOFTWARE.REFERENCE doctype design. Note that your own output may vary, depending on the SOFTWARE design under which you process the SDML file.

RECORD

The RECORD statement lets you name and define data structures in a BASIC program and provides the BASIC interface to the VAX Common Data Dictionary (CDD). You can use the defined RECORD name anywhere a BASIC data-type keyword is valid.

Format

RECORD rec nam


rec component
.
.
.

END RECORD [ rec nam ]

rec component: rec item: group clause: GROUP group nam [ ( int const,...)]
rec component
.
.
.
END GROUP [ group nam ] variant clause: VARIANT
case clause
.
.
.
END VARIANT case clause: CASE
[ rec component ]

MID$

The MID$ function extracts a specified substring from the middle of a string, leaving the main string unchanged.

Format

str vbl = (str exp, int exp1, int exp2)

2.18 Using the Tag Template

Table 2-11 summarizes the tags available in the Tag template, the default headings associated with them, and how they should be used. The table presents the tags in the same order as in the template in directory DOC$TEMPLATES.

Use these tags to create a tag reference section, such as the one at the end of this chapter. In most manuals, a tag reference section describes each tag the software offers: each tag's format, syntax, arguments, related tags, restrictions, required terminators, and functional description, plus examples of its use.

This section also contains a sample input and output file using the Tag template. You may find these sample files useful in understanding how the Tag template tags fit together.

This sample describes the <SYNTAX> tag. It is intended only as a sample, and should not be used as a source of reference for this tag.

Table 2-11 Tag Template Tags as Available from DOC$TEMPLATES
Tag Name Default
Heading 		Template Usage
<TAG_SECTION> None Begins a Tag section
<SET_TEMPLATE_TAG> None Alters the default format of a Tag section
<SET_TEMPLATE_HEADING> None Alters the default headings in a reference section
<SET_TEMPLATE_PARA> None Creates user-defined tags for a specially formatted paragraph in a reference section
<SET_TEMPLATE_LIST> None Creates user-defined tags for a specially formatted list in a reference section
<SET_TEMPLATE_TABLE> None Creates user-defined tags for a specially formatted table in a reference section
<SDML_TAG> None Begins each new element to be referenced in the template; this is the default reference element tag in the Tag reference template
<OVERVIEW> None Labels an overview of the reference element
<FORMAT> Format Labels the format of the reference element's syntax
<PARAMDEFLIST> Arguments Begins a definition list of the arguments associated with the reference element
<RELATED_TAGS> Related Tags Begins a list of zero or more tags related to the tag being described
<TERMINATING_TAG> Required Terminator Labels the tag that terminates the tag being described
<RESTRICTIONS> Restrictions Begins a list of zero or more restrictions on the reference element's use
<DESCRIPTION> Description Labels a reference element description section
<EXAMPLE_SEQUENCE> Examples Begins a sequence of one or more examples

2.18.1 Sample SDML File of the Tag Template

The following is an extended code example showing a DECdocument SDML file that uses the Tag template: 


 
<TAG_SECTION>(Using the SOFTWARE Doctype\\NEWPAGE) 
<SDML_TAG>(SYNTAX) 
 
<OVERVIEW> 
Lets you use special characters to describe language 
syntaxes. 
<ENDOVERVIEW> 
 
<format>(Syntax) 
<FTAG>(SYNTAX\<LIST>(STACKED\braces) 
              <LE>heading text [<ARG_SEP>WIDE] 
              <LE>WIDE<ENDLIST>\OPTIONAL) 
<ENDFORMAT> 
 
<PARAMDEFLIST> 
 <PARAMITEM>(heading text) 
 <PARAMDEF>Specifies a heading.  The doctype controls the font used to 
display the heading. By default, this tag has no heading. You may want to create 
a heading using the <TAG>(SYNTAX_DEFAULT_HEAD) tag. 
 
       <PARAMITEM>(WIDE) 
       <PARAMDEF>Specifies that the syntax statement may exceed the normal right 
margin of the text. If you are using doctype designs that indent 
the text body, a wide syntax example will extend into the left margin. 
<ENDPARAMDEFLIST> 
 
<RELATED_TAGS> 
<RELATED_TAG>(display) 
<RELATED_TAG>(syntax_default_head) 
<RELATED_ITEM>The global <TAG>(CODE_EXAMPLE) tag 
<RELATED_ITEM>The global <TAG>(FORMAT) tag 
<ENDRELATED_TAGS> 
 
<RESTRICTIONS> 
You cannot use tab characters, 
index tags (such as the <TAG>(x) and <TAG>(Y) tags), 
or text element tags (such as <TAG>(p), <TAG>(list), or <TAG>(note)) 
in this type of example. 
<ENDRESTRICTIONS> 
 
<TERMINATING_TAG>(ENDSYNTAX) 
 
<DESCRIPTION> 
The <TAG>(SYNTAX) tag lets you accurately describe language 
syntax.  Languages can include programming languages, command 
languages, application defined languages, and so forth.  This tag also 
separates the syntax example from the remaining text, retains blank 
spaces and open lines, and labels the example (if you specified one) 
using a doctype-specific font different from the current text font. 
<ENDDESCRIPTION> 
 
<EXAMPLE_SEQUENCE>(EXAMPLE) 
<EXC><LITERAL><P>The COPY command has the following syntax: 
<SYNTAX> 
              COPY input_file output_file 
<ENDSYNTAX> 
 
 
<ENDLITERAL> 
<EXTEXT> 
This example produces the following output: 
<P> 
The COPY command has the following syntax: 
<SYNTAX> 
              COPY input_file output_file 
<ENDSYNTAX> 
<ENDEXAMPLE_SEQUENCE>

2.18.2 Sample Output File of the Tag Template

The following is the output from the extended code example in Section 2.18.1, produced using the SOFTWARE.REFERENCE doctype design. Note that your own output may vary, depending on the SOFTWARE design under which you process the SDML file.

<SYNTAX>

Lets you use special characters to describe language syntaxes.

Syntax

<SYNTAX> [(
  • heading text [\WIDE]
  • WIDE
)]

ARGUMENTS

heading text

Specifies a heading. The doctype controls the font used to display the heading. By default, this tag has no heading. You may want to create a heading using the <SYNTAX_DEFAULT_HEAD> tag.

WIDE

Specifies that the syntax statement may exceed the normal right margin of the text. If you are using doctype designs that indent the text body, a wide syntax example will extend into the left margin.

related tags

restrictions

You cannot use tab characters, index tags (such as the <X> and <Y> tags, or text element tags (such as <P>, <LIST>, or <NOTE>) in this type of example.

required terminator

<ENDSYNTAX>

DESCRIPTION

The <SYNTAX> tag lets you accurately describe language syntax. Languages can include programming languages, command languages, application defined languages, and so forth. This tag also separates the syntax example from the remaining text, retains blank spaces and open lines, and labels the example (if you specified one) using a doctype-specific font different from the current text font.

Example


<P>The COPY command has the following syntax: 
<SYNTAX> 
              COPY input_file output_file 
<ENDSYNTAX>

This example produces the following output:

The COPY command has the following syntax: 


              COPY input_file output_file

Previous Next Contents Index