| Previous | Contents | Index |
Table 2-8 summarizes the tags available in the Command 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 command reference section. In most manuals, a command section is an encyclopedic reference section that describes each command the software system offers: its format, restrictions, prompts, parameters, functional description, command qualifiers, and positional qualifiers, plus examples of its use.
This section also contains a sample input and output file using the Command template. You may find these sample files useful in understanding how the Command template tags fit together.
These samples describe the APPEND command. They are intended only as samples, and should not be used as a source of reference for this command.
| Tag Name | Default Heading |
Template Usage |
|---|---|---|
| <COMMAND_SECTION> | None | Begins a Command section |
| <SET_TEMPLATE_COMMAND> | None | Alters the default format of a Command 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 |
| <COMMAND> | None | Begins each new element to be referenced in the template; this is the default reference element tag in the Command reference template |
| <OVERVIEW> | None | Labels an overview of the reference element |
| <FORMAT> | Format | Labels the format of the reference element's syntax |
| <PARAMDEFLIST> | Parameters | Begins a definition list of the parameters or arguments associated with the reference element |
| <RESTRICTIONS> | Restrictions | Begins a list of zero or more restrictions on the reference element's use |
| <PROMPTS> | Prompts | Begins a list of the prompts associated with the reference element |
| <DESCRIPTION> | Description | Labels a reference element description section |
| <QUALDEFLIST> | Qualifiers | Begins a definition list of zero or more qualifiers associated with the reference element |
| <EXAMPLE_SEQUENCE> | Examples | Begins a sequence of one or more examples |
| <SUBCOMMAND_SECTION> | None | Begins a section of subcommands in a Command section |
| <SUBCOMMAND_SECTION_HEAD> | None | Specifies the heading for introductory text that precedes a subcommand section |
| <SET_TEMPLATE_SUBCOMMAND> | None | Alters the name of the <SUBCOMMAND> tag, and optionally lets you specify that each use of that tag should not begin output on a new page |
| <SUBCOMMAND> | None | Begins a new subcommand element to be described in a subcommand section |
2.15.1 Sample SDML File of the Command Template
The following is an extended code example showing a DECdocument SDML
file that uses the Command template:
<COMMAND_SECTION>(Using the SOFTWARE Doctype\\NEWPAGE) <SET_TEMPLATE_COMMAND>(DCL_COMMAND) <DCL_COMMAND>(APPEND) <OVERVIEW> Adds the contents of one or more specified input files to the end of the specified output file. <ENDOVERVIEW> <format>(Syntax) <fCMD>(APPEND) <FPARMS>(input file spec[,<hellipsis>] output file spec) <QUAL_LIST>(Command Qualifiers) <QPAIR>(/BACKUP\/CREATED) <QPAIR>(/BEFORE[=time]\/BEFORE=TODAY) <ENDQUAL_LIST> <QUAL_LIST>(Positional Qualifiers) <QPAIR>(/ALLOCATION=n\See text.) <QPAIR>(/[NO]CONTIGUOUS\None.) <ENDQUAL_LIST> <ENDFORMAT> <RESTRICTIONS>(NONE) <PROMPTS> <PROMPT>(From:\input file spec[,<hellipsis>]) <PROMPT>(To:\output file spec) <ENDPROMPTS> <PARAMDEFLIST> <PARAMITEM>(input file spec[,<hellipsis>]) <PARAMDEF>Specifies the names of one or more input files to be appended. <P> If you specify more than one input file, separate the specifications with either commas (,) or plus signs (+). Commas and plus signs are equivalent. All input files are appended, in the order specified, to the end of the output file. <P> You can use wildcard characters in the file specification(s). <PARAMITEM>(output file spec) <PARAMDEF> Specifies the name of the file to which the input files will be appended. <P> You must include at least one field in the output file specification. If you do not specify a device and/or directory, the APPEND command uses the current default device and directory. For other fields that you do not specify, the APPEND command uses the corresponding field of the input file specification. <P> If you use the asterisk wildcard character in any field(s) of the output file specification, the APPEND command uses the corresponding field of the input file specification. If you are appending more than one input file, APPEND uses the corresponding fields from the first input file. <ENDPARAMDEFLIST> <DESCRIPTION> The APPEND command is similar in syntax and function to the COPY command. Normally, the APPEND command adds the contents of one or more files to the end of an existing file without incrementing the version number. The /NEW_VERSION qualifier causes the APPEND command to create a new output file if no file with that name exists. <ENDDESCRIPTION> <QUALDEFLIST>(Command Qualifiers) <QUALITEM>(/BACKUP) <QUALDEF> Selects files according to the dates of their most recent backup. This qualifier is relevant only when used with the /BEFORE or /SINCE qualifier. Use of the /BACKUP qualifier is incompatible with /CREATED, /EXPIRED, and /MODIFIED. The default is /CREATED. <QUALITEM>(/BEFORE[=time]) <QUALDEF> Selects only those files that are dated before the specified time. <P> You can specify either an absolute time or a combination of absolute and delta times. <comment> See Section <reference>(time_sec) for complete information on specifying time values. <endcomment> You can also use the keywords TODAY, TOMORROW, and YESTERDAY. If no time is specified, TODAY is assumed. <ENDQUALDEFLIST> <QUALDEFLIST>(Positional Qualifiers) <QUALITEM>(/ALLOCATION=n\) <QUALDEF> Forces the initial allocation of the output file to the number of 512-byte blocks specified as n. <P> This qualifier is valid in conjunction with the /NEW_VERSION qualifier. The allocation size is applied only if a new file is actually created. If you create a new file and you do not specify /ALLOCATION, the initial allocation of the output file is determined by the size of the input file(s). <QUALITEM>(/CONTIGUOUS\/NOCONTIGUOUS) <QUALDEF> Indicates whether the output file is contiguous, that is, whether the file must occupy consecutive physical disk blocks. <P> By default, the APPEND command creates an output file in the same format as the corresponding input file. If an input file is contiguous, the APPEND command attempts to create a contiguous output file, but does not report an error if there is not enough space. If you append multiple input files of different formats, the output file might or might not be contiguous. Use the /CONTIGUOUS qualifier to ensure that the output file is contiguous. <ENDQUALDEFLIST> <EXAMPLE_SEQUENCE> <EXI><S>($) <U>(APPEND TEST.DAT NEWTEST.DAT) <EXTEXT> The APPEND command appends the contents of the file TEST.DAT from the default disk and directory to the file NEWTEST.DAT also located on the default disk and directory. <EXI>(WIDE)<S>($) <U>(APPEND/NEW_VERSION/LOG *.TXT T.SUM) <S>(%APPEND-I-CREATED, D1$:[MAL]T.SUM;1 created) <S>(%APPEND-S-COPIED, D1$:[MAL]A.TXT;2 copied to D1$:[MAL]T.SUM;1 (1 block)) <S>(%APPEND-S-APPENDED, D1$:[MAL]B.TXT;3 appended to D1$:[MAL]T.SUM;1 (3 records)) <S>(%APPEND-S-APPENDED, D1$:[MAL]G.TXT;7 appended to D1$:[MAL]T.SUM;1 (51 records)) <S>(%APPEND-S-NEWFILES, 1 file created) <EXTEXT> The APPEND command appends all files with file types of TXT to a file named T.SUM. The /LOG qualifier requests a display of the specifications of each input file appended. If the file T.SUM does not exist, the APPEND command creates it, as the output shows. The number of blocks or records shown in the output refers to the SDML file and not to the target file total. <ENDEXAMPLE_SEQUENCE> <ENDCOMMAND_SECTION> |
The following is the output from the extended code example in Section 2.15.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.
Adds the contents of one or more specified input files to the end of the specified output file.
APPEND input file spec[,...] output file spec
Command Qualifiers Defaults /BACKUP /CREATED /BEFORE[=time] /BEFORE=TODAY
Positional Qualifiers Defaults /ALLOCATION=n See text. /[NO]CONTIGUOUS None.
None.
| From: | input file spec[,...] |
| To: | output file spec |
input file spec[,...]
Specifies the names of one or more input files to be appended.If you specify more than one input file, separate the specifications with either commas (,) or plus signs (+). Commas and plus signs are equivalent. All input files are appended, in the order specified, to the end of the output file.
You can use wildcard characters in the file specification(s).
output file spec
Specifies the name of the file to which the input files will be appended.You must include at least one field in the output file specification. If you do not specify a device and/or directory, the APPEND command uses the current default device and directory. For other fields that you do not specify, the APPEND command uses the corresponding field of the input file specification.
If you use the asterisk wildcard character in any field(s) of the output file specification, the APPEND command uses the corresponding field of the input file specification. If you are appending more than one input file, APPEND uses the corresponding fields from the first input file.
The APPEND command is similar in syntax and function to the COPY command. Normally, the APPEND command adds the contents of one or more files to the end of an existing file without incrementing the version number. The /NEW_VERSION qualifier causes the APPEND command to create a new output file if no file with that name exists.
/BACKUP
Selects files according to the dates of their most recent backup. This qualifier is relevant only when used with the /BEFORE or /SINCE qualifier. Use of the /BACKUP qualifier is incompatible with /CREATED, /EXPIRED, and /MODIFIED. The default is /CREATED./BEFORE[=time]
Selects only those files that are dated before the specified time.You can specify either an absolute time or a combination of absolute and delta times. You can also use the keywords TODAY, TOMORROW, and YESTERDAY. If no time is specified, TODAY is assumed.
/ALLOCATION=n
Forces the initial allocation of the output file to the number of 512-byte blocks specified as n.This qualifier is valid in conjunction with the /NEW_VERSION qualifier. The allocation size is applied only if a new file is actually created. If you create a new file and you do not specify /ALLOCATION, the initial allocation of the output file is determined by the size of the input file(s).
/CONTIGUOUS
/NOCONTIGUOUS
Indicates whether the output file is contiguous, that is, whether the file must occupy consecutive physical disk blocks.By default, the APPEND command creates an output file in the same format as the corresponding input file. If an input file is contiguous, the APPEND command attempts to create a contiguous output file, but does not report an error if there is not enough space. If you append multiple input files of different formats, the output file might or might not be contiguous. Use the /CONTIGUOUS qualifier to ensure that the output file is contiguous.
| #1 |
|---|
$ APPEND TEST.DAT NEWTEST.DAT |
The APPEND command appends the contents of the file TEST.DAT from the default disk and directory to the file NEWTEST.DAT also located on the default disk and directory.
| #2 |
|---|
$ APPEND/NEW_VERSION/LOG *.TXT T.SUM %APPEND-I-CREATED, D1$:[MAL]T.SUM;1 created %APPEND-S-COPIED, D1$:[MAL]A.TXT;2 copied to D1$:[MAL]T.SUM;1 (1 block) %APPEND-S-APPENDED, D1$:[MAL]B.TXT;3 appended to D1$:[MAL]T.SUM;1 (3 records) %APPEND-S-APPENDED, D1$:[MAL]G.TXT;7 appended to D1$:[MAL]T.SUM;1 (51 records) %APPEND-S-NEWFILES, 1 file created |
The APPEND command appends all files with file types of TXT to a file named T.SUM. The /LOG qualifier requests a display of the specifications of each input file appended. If the file T.SUM does not exist, the APPEND command creates it, as the output shows. The number of blocks or records shown in the output refers to the SDML file and not to the target file total.
2.16 Using the Routine Template
Table 2-9 summarizes the tags available in the Routine 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 routine reference
section. In most manuals, a routine reference section describes each
routine the software offers: the routine's format, returns, arguments,
full routine description (perhaps with figures and tables), return
values, and shows examples of its use.
This section also contains a sample input and output file using the Routine template. You may find these sample files useful in understanding how the Routine template tags fit together.
These samples describe the $ENQ and MTH$xSORT routines. They are intended only as samples, and should not be used as a source of reference for these routines.
| Tag Name | Default Heading |
Template Usage |
|---|---|---|
| <ROUTINE_SECTION> | None | Begins a Routine section |
| <SET_TEMPLATE_ROUTINE> | None | Alters the default format of a Routine 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 |
| <ROUTINE> | None | Begins each new element to be referenced in the template; this is the default reference element tag in the Routine reference template |
| <OVERVIEW> | None | Labels an overview of the reference element |
| <FORMAT> | Format | Labels the format of the reference element's syntax |
| <RETURNS> | Returns | Provides specific information about the attributes of the value returned by the routine |
| <RETTEXT> | None | Provides general information about the attributes of the value returned by the routine |
| <ARGDEFLIST> | Arguments | Begins a definition list of the arguments associated with the reference element |
| <DESCRIPTION> | Description | Labels a reference element description section |
| <RSDEFLIST> | Return Values | Begins a definition list of zero or more routine return status codes and their meanings |
| <EXAMPLE_SEQUENCE> | Examples | Begins a sequence of one or more examples |
2.16.1 Sample SDML File of the Routine Template
The following is an extended code example showing a DECdocument SDML
file that uses the Routine template:
<routine_section>(Using the SOFTWARE Doctype\\NEWPAGE)
<set_template_routine>(VMS_ROUTINE\doublerunningheads)
<VMS_ROUTINE>($ENQ\Enqueue Resource)
<OVERVIEW>This is the brief description section. It contains one or
two sentences describing what the routine does.
<ENDOVERVIEW>
<format>(Syntax)
<frtn>($ENQ) <fargs>([efn], lkmode, lksb, itmlst)
<ENDFORMAT>
<RETURNS>(cond_value\longword integer\read only\by value in R0)
<RETTEXT>At times, it may be necessary to include a sentence or two
here to further describe the nature of the information returned.
<ENDRETTEXT>
<ARGDEFLIST>
<ARGITEM>(efn\cond_value\longword integer\read only\by value)
<ARGDEF>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.
<ARGITEM>(lkmode\cond_value\longword integer\read only\by descriptor\varying string
array descriptor)
<ARGDEF>Name of lock mode requested. May be one of the following:
<TABLE>
<TABLE_SETUP>(2\17)
<TABLE_HEADS>(Name of Lock Mode\Description)
<TABLE_ROW>(LCK$K_NLMODE\Null lock mode)
<TABLE_ROW>(LCK$K_CRMODE\Concurrent read mode)
<TABLE_ROW>(LCK$K_CWMODE\Concurrent write mode)
<ENDTABLE>
<ARGITEM>(lksb\cond_value\longword integer\write only\by value)
<ARGDEF>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.
<ARGITEM>(itmlst)
<ARGDEF>
Item list specifying the lock information that $GETLKI is to return. The
<variable>(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.
<line_art>
31 15 0
+--------------------------------------------------+
| item code | buffer length |
+------------------------+-------------------------+
| buffer address |
+--------------------------------------------------+
| return length address |
+--------------------------------------------------+
<endline_art>
<endargdeflist>
<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.
<ENDDESCRIPTION>
<RSDEFLIST>
<RSITEM>(SS$_NORMAL\Indicates successful completion)
<RSITEM>(SS$_ABORT\This description contains a full explanation of some of
the possible causes for the abortion)
<RSITEM>(SS$_DEADLOCK\This description contains a full explanation of
some possible causes for the deadlock situation.)
<ENDRSDEFLIST>
<EXAMPLE_SEQUENCE>
<examples_intro>
This section contains an example of the use of the routine.
This section can also contain figures and tables.
<ENDEXAMPLE_SEQUENCE>
<VMS_ROUTINE>(MTH$xSQRT)
<OVERVIEW>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.
<ENDOVERVIEW>
<format>(Syntax)
<ffunc>(MTH$SQRT\(x))
<ffunc>(MTH$DSQRT\(x))
<ffunc>(MTH$GSQRT\(x))
<ffunc>(MTH$HSQRT\(x))
<ENDFORMAT>
<RETURNS>(cond_value\F_Floating, D_Floating, or G_Floating
\write only\by value in R0)
<RETURNS>(headonly)
<RETTEXT>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 <VARIABLE>(sqrt).
<ENDRETTEXT>
<ARGDEFLIST>(Argument)
<ARGITEM>(x\cond_value\F_Floating,D_Floating, G_Floating, or H_Floating
\read only\by reference)
<ARGDEF>The number for which the square root is desired.
<ARGITEM>(sqrt\cond_value\H_Floating\write only\by reference)
<ARGDEF>The square root of the H_Floating parameter.
<ENDARGDEFLIST>
<DESCRIPTION>
This is a description of the MTH$xSQRT function.
<ENDDESCRIPTION>
<ENDROUTINE_SECTION>
|
| Previous | Next | Contents | Index |