📄 cgml.htm
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
<META NAME="GENERATOR" Content="Visual Page 1.0 for Windows">
<TITLE>PL/Generator Template Language</TITLE>
</HEAD>
<BODY BACKGROUND="bar_products.gif" BGCOLOR="white">
<UL>
<UL>
<IMG SRC="cgml.gif" WIDTH="431" HEIGHT="92" ALIGN="BOTTOM" BORDER="0">
<HR ALIGN="CENTER">
<P><FONT SIZE="5">Table of Contents</FONT></P>
<P><A NAME="Top"></A></P>
<UL>
<LI><FONT SIZE="4"><B>Welcome to CGML™</B></FONT><P>
<UL>
<LI><A HREF="#beta"><B>Note on Documentation</B></A><P>
<LI><A HREF="#introduction"><B>Introduction</B></A><P>
<LI><A HREF="#restrictions"><B>CGML Trial Version Restrictions</B></A><P>
<LI><A HREF="#working"><B>Working with CGML</B></A><P>
</UL>
<LI><A HREF="#troubleshooting"><FONT SIZE="4"><B>Troubleshooting</B></FONT></A><P>
<LI><A HREF="syntax.htm"><FONT SIZE="4"><B>CGML Syntax Reference</B></FONT></A><P>
</UL>
<HR ALIGN="CENTER">
<P><A NAME="beta"></A><FONT SIZE="5" FACE="Arial"><B> Note on Documentation</B></FONT></P>
<P>CGML documentation remains under construction; you will, as a result, occasionally encounter sections that only
say:</P>
<DIR>
<P>TO BE COMPLETED</P>
</DIR>
<P>We apologize for that and hope to complete all aspects of CGML documentation very soon.</P>
<P>In the meantime, we very much look forward to your feedback. Let us know how we can make CGML easier to use
and understand. Please also share with us any examples that you develop in your testing so that we can expand the
set offered to all of our customers.</P>
<HR ALIGN="CENTER">
<P><A NAME="introduction"></A><FONT SIZE="5" FACE="Arial"><B>INTRODUCTION</B></FONT></P>
<P>CGML is a "mark-up" language designed by Quest Software to be used to generate text (usually computer source
code in one or another language). Its focus is a bit different from HTML and XML, which offer extensive formatting
capabilities. Instead, CGML is designed to interact with and generate text (usually code in one or another programming
language) from objects defined in the Oracle data dictionary.</P>
<P>CGML is currently used by PL/Generator to generate encapsulation packages (PL/SQL APIs) for Oracle table structures.
PL/Generator comes with one or more "drivers". Each driver consists of one or more files that use the
CGML language to define a "template" or generic structure of the code you want generated. The PL/Generator
engine then applies this template to the specified data dictionary objects (or other elements you define, as discussed
later in this document) and generates code.</P>
<P>You will find that CGML offers an ideal solution when you need to write code that follows a general pattern,
but must be applied to specific objects and structures within your application environment.</P>
<P>Use this document to learn the syntax of CGML and then:</P>
<OL Type="a">
<LI>Customize the PL/Generator drivers provided by Quest Software. You can customize these drivers without using CGML,
but CGML will allow you to define customizations that can applied generically across multiple objects in your schema.<P>
<LI>Construct your own drivers to generate any sort of code or text you desire. This is a more complicated process,
but can be very rewarding. If you are using Oracle8.1, for example, you can create a driver that will generate
code or text for each file found in a particular directory. In other words, you don't have to work only with structures
defined in the Oracle data dictionary.<P>
</OL>
<P><A HREF="#Top"><B>Return To Top</B></A></P>
<HR ALIGN="CENTER">
<P><A NAME="restrictions"></A><FONT SIZE="5" FACE="Arial"><B> CGML Trial Version Restrictions</B></FONT></P>
<P>If you are using a trial version of CGML (either stand-alone or through a trial copy of PL/Generator), the following
restriction applies to your construction of and generation from CGML scripts:</P>
<UL>
<LI>Maximum length of CGML script is 50 lines of text.<P>
<LI>Maximum number of lines of CGML text that will be generated: 100 lines.<P> </UL>
<HR ALIGN="CENTER">
<P><A NAME="working"></A><FONT SIZE="5" FACE="Arial"><B> WORKING WITH CGML</B></FONT></P>
<P>
<UL>
<LI><A HREF="#structures"><B>Create Test Data Structures</B></A><P>
<LI><A HREF="#directory"><B>Set the PL/Generator Directory</B></A><P>
<LI><A HREF="#genfile"><B>Use the PLGCGML.genFile Procedure</B></A><P>
<LI><A HREF="#genstring"><B>Use the PLGCGML.genString Procedure</B></A><P>
</UL>
<P>This is a new technology, newly made available for public use. Don抰 proceed headlong with a long, complex driver
development effort until you have tried out individual CGML statements and have become comfortable with the language.</P>
<P>In order to make it easier for you to work with your CGML driver files and customizations in an incremental
and efficient fashion, Quest Software provides a set of scripts to perform various tasks. These files are listed in
the table below; they are explained in more detail in the appropriate sections. These files may be found in the
plgenerator\CGML subdirectory</P>
<TABLE BORDER="0" CELLPADDING="7" CELLSPACING="1" FRAME="BORDER" BORDERCOLOR="#000000">
<TR>
<TD WIDTH="22%" VALIGN="TOP" BGCOLOR="#000000"><FONT COLOR="#FFFFFF">File Name</FONT></TD>
<TD WIDTH="78%" VALIGN="TOP" BGCOLOR="#000000"><FONT COLOR="#FFFFFF"><B> Description</B></FONT></TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> *.gdr</B></TD>
<TD WIDTH="78%" VALIGN="TOP">A variety of Generator DRiver files (hence, the "gdr" extension) that solve the problems posed in the
Examples section.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> CGML.tst</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Default output file as specified in the testCGML.gdr [STOREIN] statement. You can change this.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> demo.drp</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Drops the demonstration data structures.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> demo.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Creates the demonstration data structures.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> setdir.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Allows you to set the default directory containing your CGML text files and the generated output files. Call as
follows:<BR>
<BR>
SQL> exec setdir c:\temp</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showalias.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the list of alias tags defined for the Table Encapsulation driver that are like the specified string.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showaliastags.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the list of alias tags defined for the Table Encapsulation driver.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showarrays.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the list of arrays defined for the Table Encapsulation driver.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showdir.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the directories from which CGML text files will be read and to which generated text will be written (these
values are set by the setdir.sql script).</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showobj.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the list of object tags defined for the Table Encapsulation driver that are like the specified string.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> showobjtags.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Shows the list of object tags defined for the Table Encapsulation driver.</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> ssoo.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">Executes this command for you:<BR>
<BR>
SET SERVEROUTPUT ON SIZE 1000000</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> test.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">
<P>One stop shopping test script. It contains these two lines:</P>
<P>SET SERVEROUTPUT ON SIZE 1000000</P>
<P>exec PLGCGML.genfile ('employee', 'testCGML.gdr', show=> true);</P>
<P>allowing you to easily try out your CGML text in the standard testCGML.gdr file against the employee table.
</TD>
</TR>
<TR>
<TD WIDTH="22%" VALIGN="TOP"><B> genstring.sql</B></TD>
<TD WIDTH="78%" VALIGN="TOP">One stop shopping test script that uses the PLGCGML.genstring program.</TD>
</TR>
</TABLE>
<P><A HREF="#Top"><B>Return To Top</B></A></P>
<HR ALIGN="CENTER">
<P><A NAME="structures"></A><FONT SIZE="5" FACE="Arial"><I><B> Create Test Data Structures</B></I></FONT></P>
<P><B>Note:</B> You only have to do this the first time you test your CGML drivers.</P>
<P>You can run the demo.sql to install a set of fairly standard Oracle demonstration tables (employee, department,
etc.) enhanced with check constraints, primary and foreign keys and PL/Generator Object Information Repository
settings. See the PL/Generator Installation Guide for more details on the demonstration schema.</P>
<P>Of course, you certainly do not have to rely on the demonstration tables to test your use of CGML. You will
undoubtedly want to work with your own data structures. These demo tables simply streamline your use of the examples
to get the hang of CGML.</P>
<P><A HREF="#Top"><B>Return To Top</B></A></P>
<HR ALIGN="CENTER">
<P><A NAME="directory"></A><FONT SIZE="5" FACE="Arial"><I><B>Set the PL/Generator Directory</B></I></FONT></P>
<P>Before you can use PL/Generator to generate text from CGML, you must define the directory that will hold your
test drivers and generated files.</P>
<P><B>Note 1:</B> Take this step the first time you test your CGML drivers; after that, you will only have to do it again
if you change the directory in which your files are located.</P>
<P><B>Note 2:</B> You must have enabled UTL_FILE access to this directory for the testCGML procedure to write its text
out to a file. See the PL/Generator Installation Guide HTML document for more information on setting up UTL_FILE.</P>
<P>To set the directory, run the setdir.sql script, passing as its single argument the directory specification.
Here are two examples:</P>
<DIR>
<PRE>
@setdir d:\plgenerator\CGML
@setdir /tmp </PRE></DIR>
<P><A HREF="#Top"><B>Return To Top</B></A></P>
<HR ALIGN="CENTER">
<P><A NAME="genfile"></A><FONT SIZE="5" FACE="Arial"><I> <B>Use the PLGCGML.genFile Procedure</B></I></FONT></P>
<P>The PLGCGML.genFile procedure takes all of the steps necessary to load your driver file and run the PL/Generator
engine to create your text and deposit it in the file specified in your driver file with the [STOREIN] command.
Use PLGCGML.genFile if you have UTL_FILE configured in your database and you want to send output directly to files.</P>
<P>Here is the header for this procedure*:</P>
<PRE>PROCEDURE PLGCGML.genFile (
obj IN VARCHAR2,
file IN VARCHAR2,
show IN BOOLEAN :=FALSE,
cleardriver IN BOOLEAN :=TRUE,
sch IN VARCHAR2 :=NULL ,
drvr IN VARCHAR2 :=NULL,
delarray IN BOOLEAN :=TRUE,
single_pass IN BOOLEAN :=FALSE
); </PRE>
<P>where the arguments have the following meaning:</P>
<TABLE BORDER="0" CELLPADDING="7" CELLSPACING="1" WIDTH="625" FRAME="BORDER">
<TR>
<TD WIDTH="11%" VALIGN="TOP">obj</TD>
<TD WIDTH="89%" VALIGN="TOP">The name of the table or view against which you will run your CGML file.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">file</TD>
<TD WIDTH="89%" VALIGN="TOP">The name of the file containing your test CGML.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">show</TD>
<TD WIDTH="89%" VALIGN="TOP">A Boolean flag indicating whether or not you want to show the text that is generated from your CGML file.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">cleardriver</TD>
<TD WIDTH="89%" VALIGN="TOP">A Boolean flag indicating whether or not you want to the existing driver definition to be cleared. Default is TRUE
and you should stick with the default unless you are defining your own arrays.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">sch</TD>
<TD WIDTH="89%" VALIGN="TOP">The schema that contains the table or view; the default is the currently-connected user.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">drvr</TD>
<TD WIDTH="89%" VALIGN="TOP">The name of the driver which will be created for this execution. Default is TEST. You should keep it that way until
you start building your own drivers.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">delarray</TD>
<TD WIDTH="89%" VALIGN="TOP">Pass TRUE if you want to delete any arrays defined for this schema. FALSE will preserve arrays previously defined.</TD>
</TR>
<TR>
<TD WIDTH="11%" VALIGN="TOP">single_pass</TD>
<TD WIDTH="89%" VALIGN="TOP">A value of TRUE means that the generator engine will only run once for your CGML text, regardless of how many objects
are defined in the DBOBJECT array. This is useful when your CGML text is iterating through the DBOBJECT array itself.</TD>
</TR>
</TABLE>
<P>*<B>Note:</B> there is an overloaded version of PLGCGML.genFile that does not require passing an object name. This
will be used for generation using your own custom-defined arrays.</P>
<P>You can call PLGCGML.genFile by writing a full execution call or by running the test script. Here is the contents
of test.sql:</P>
<P>
<DIR>
<PRE>exec PLGCGML.genFile ('employee', 'testCGML.gdr', show=> true);</PRE>
</DIR></P>
<P>As you can see, it is very "specialized". It assumes that you want to work with the employee table
and that your driver text is in testCGML.gdr. You can take that approach or, of course, call testCGML yourself
as shown below.</P>
<P>Suppose that I created a file named showcols.gdr in the c:\temp directory. I could then generate a file (whose
name is specified in the showcols.gdr file itself) in the loc directory against the 'chart_of_accounts' table as
follows:</P>
<P>
<DIR>
<PRE>SQL> exec PLGCGML.genFile ('chart_of_accounts', 'c:\temp', 'showcols.gdr');
</PRE>
</DIR></P>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -