PQL Procedures

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

PQL Procedures

XML SAVE FILE

XML SAVE FILE
  FILENAME = filename
  [BOOLEAN = (logical expression)]
  [MISSCHAR = character]
  [SHOWMISS]
  [SAMPLE   = fraction ]
  [SORT    = [(n)]  variable [(A)|(D)] ,  ....]

  [ROOT       = 'string']
   BREAK      = break_variable (TAG = 'string',
                               ATTRIBUTES = (varname (format) ),...),
                               ELEMENTS   = (varname (format) ),...)),
               break_variable ..........
  [DTD        [= filename]]
  [SCHEMA     [= filename]]

The XML SAVE FILE procedure produces a text file which is an Extensible Markup Language, abbreviated XML, document. The XML File is a text file and consists of an hierarchical set of tags which enclose lower levels of tags and, at some point, enclose data. It resembles HTML, only it uses tags defined by users. Many products can now deal with XML based files. (Note. Statements in this document do not purport to describe XML or make comprehensive statements about the language but some explanation is necessary to describe the clauses on the procedure command. There are published standards for XML for those interested.)

An example bit of XML from within a document might be:

<company>
   <person>
       <name>John D Jones</name>
       <salary>2150</salary>
       <birthday>1986</birthday>
   </person>
   <person>
       <name>James A Arblaster</name>
       <salary>1500</salary>
       <birthday>1981</birthday>
   </person>
</company>

XML has its own standard for names (which is different to SIR/XS) and any names that are generated by this procedure should meet this standard. XML names begin with alphabetic character (or underscore _) and should not start with XML. They are case sensitive and allow letters, numbers plus some special characters but no spaces.

FILENAME Specify the filename created by the procedure. If you do not supply a file extension, then .xml is added to the filename as a suffix.
BOOLEAN Specifies which procedure table records are used by the procedure. The procedure table records for which the logical expression is true are used by the procedure. If this option is not specified, all procedure table records are used.

MISSCHAR Specifies the character used as the Missing or Undefined value indicator. The default is a blank. For example, to have all missing values represented by asterisks, specify:

MISSCHAR = *

SAMPLE Specifies that a random sample of the procedure table records are used by the procedure.
The fraction specifies the percent of records used and is specified as a positive decimal number less than or equal to 1 (one). .25, for example specifies that a 25% sample be used.

SHOWMISS Specifies that a variable's original missing values are printed for fields containing missing values. The default character is blank. Missing values are always excluded from totals - this option only affects printing.
SORT Specifies the sequence of the output. n is an integer that specifies the maximum number of records to be sorted. The default is either the number of records in the database or the value specified in the sortn parameter and need only be specified if the number of records in the procedure table is greater than the default. The procedure table is sorted by the specified variables in variable list order. A variable name followed by (A) or (D) specifies that for that variable the sort is in Ascending order (the default) or in Descending order.

ROOT The XML file consists of a well formed hierarchy and the ROOT is the top-level outermost component of this. This defaults to SIR_XS_ROOT if not specified. Specify a valid XML name as the root that the processing application expects.

BREAK The BREAK clause determines the hierarchy of the XML document. Each variable listed on the clause means one further level of nesting. The first variable is the outer level. By default the variable name is used as the tag. Specify a TAG = to override this.
There are two ways in which data can be included in an hierarchical level. There can be a number of individual data ELEMENTS or a set of ATTRIBUTES can be specified. Both of these name data variables but they appear in a different way in the output. Elements appear as individually tagged items whereas attributes appear within the start tag. For example, if there are three data variables for a person Name, Salary, Birthday then using elements, the output looks like:
<person> <NAME>John D Jones</NAME> <SALARY>2150</SALARY> <BIRTHDAY>01 15 78</BIRTHDAY> </person> <person> <NAME>James A Arblaster</NAME> <SALARY>2650</SALARY> <BIRTHDAY>12 07 82</BIRTHDAY> </person>
Using attributes the output looks like:
<person NAME="John D Jones" SALARY="2150" BIRTHDAY="01 15 78"> </person> <person NAME="James A Arblaster" SALARY="2650" BIRTHDAY="12 07 82"> </person>
If designing an XML application from scratch, this may be a matter of style and choice. If supplying a file to an existing application, then it is a matter of matching a specification.
The name of the element or attribute is the variable name. If this does not match the tag required, you can alter this as per the standard method for specifying variable lists in procedures (e.g. S(1) AS SALARY or S(1) 'SALARY'). Specify any formatting to be applied to the data as per the normal formats specified on a WRITE command.

DTD Additional files may be produced which describe the XML file written. You can specify a DocumentType Definition or DTD. XML provides an application independent way of sharing data. With a DTD, independent groups of people can agree to use a common DTD for interchanging data. Your application can use a standard DTD to verify that data that you receive from the outside world is valid. If you specify the DTD keyword, the default filename is the name of the main XML file produced with the extension .dtd

SCHEMA XML Schema is an XML based alternative to DTD. You can produce an XSD file which describes the XML. If you specify the SCHEMA keyword, the default filename is the name of the main XML file produced with the extension .xsd.
Specifying either Schema or DTD changes the header information written to the main XML file and so informs other processes that a descriptive file exists. You may find other applications that process the XML need a certain style of descriptive file.

Example

RETRIEVAL /PROGRESS
. PROCESS CASES ALL
.   get vars id
.   PROCESS RECORD EMPLOYEE
.     GET VARS NAME BIRTHDAY SALARY
.     PERFORM PROCS
.   END PROCESS RECORD
. END PROCESS CASES
XML  SAVE FILE
     FILENAME = "c:\sirxs\alpha\XML2.XML"
     ROOT = 'company'
     BREAK = ID (TAG = 'person' ATTRIBUTES = (name salary birthday))
     SORT  = ID
     schema

END RETRIEVAL

`FILENAME`	Specify the filename created by the procedure. If you do not supply a file extension, then .xml is added to the filename as a suffix.
`BOOLEAN`	Specifies which procedure table records are used by the procedure. The procedure table records for which the logical expression is true are used by the procedure. If this option is not specified, all procedure table records are used.
`MISSCHAR`	Specifies the character used as the Missing or Undefined value indicator. The default is a blank. For example, to have all missing values represented by asterisks, specify: MISSCHAR = *
`SAMPLE`	Specifies that a random sample of the procedure table records are used by the procedure. The fraction specifies the percent of records used and is specified as a positive decimal number less than or equal to 1 (one). .25, for example specifies that a 25% sample be used.
`SHOWMISS`	Specifies that a variable's original missing values are printed for fields containing missing values. The default character is blank. Missing values are always excluded from totals - this option only affects printing.
`SORT`	Specifies the sequence of the output. n is an integer that specifies the maximum number of records to be sorted. The default is either the number of records in the database or the value specified in the sortn parameter and need only be specified if the number of records in the procedure table is greater than the default. The procedure table is sorted by the specified variables in variable list order. A variable name followed by (A) or (D) specifies that for that variable the sort is in Ascending order (the default) or in Descending order.
`ROOT`	The XML file consists of a well formed hierarchy and the `ROOT` is the top-level outermost component of this. This defaults to `SIR_XS_ROOT` if not specified. Specify a valid XML name as the root that the processing application expects.
`BREAK`	The `BREAK` clause determines the hierarchy of the XML document. Each variable listed on the clause means one further level of nesting. The first variable is the outer level. By default the variable name is used as the tag. Specify a `TAG =` to override this. There are two ways in which data can be included in an hierarchical level. There can be a number of individual data `ELEMENTS` or a set of `ATTRIBUTES` can be specified. Both of these name data variables but they appear in a different way in the output. Elements appear as individually tagged items whereas attributes appear within the start tag. For example, if there are three data variables for a person `Name, Salary, Birthday` then using elements, the output looks like: <person> <NAME>John D Jones</NAME> <SALARY>2150</SALARY> <BIRTHDAY>01 15 78</BIRTHDAY> </person> <person> <NAME>James A Arblaster</NAME> <SALARY>2650</SALARY> <BIRTHDAY>12 07 82</BIRTHDAY> </person> Using attributes the output looks like: <person NAME="John D Jones" SALARY="2150" BIRTHDAY="01 15 78"> </person> <person NAME="James A Arblaster" SALARY="2650" BIRTHDAY="12 07 82"> </person> If designing an XML application from scratch, this may be a matter of style and choice. If supplying a file to an existing application, then it is a matter of matching a specification. The name of the element or attribute is the variable name. If this does not match the tag required, you can alter this as per the standard method for specifying variable lists in procedures (e.g. `S(1) AS SALARY` or `S(1) 'SALARY'`). Specify any formatting to be applied to the data as per the normal formats specified on a `WRITE` command.
`DTD`	Additional files may be produced which describe the XML file written. You can specify a DocumentType Definition or DTD. XML provides an application independent way of sharing data. With a DTD, independent groups of people can agree to use a common DTD for interchanging data. Your application can use a standard DTD to verify that data that you receive from the outside world is valid. If you specify the `DTD` keyword, the default filename is the name of the main XML file produced with the extension .dtd
`SCHEMA`	XML Schema is an XML based alternative to DTD. You can produce an XSD file which describes the XML. If you specify the `SCHEMA` keyword, the default filename is the name of the main XML file produced with the extension .xsd. Specifying either Schema or DTD changes the header information written to the main XML file and so informs other processes that a descriptive file exists. You may find other applications that process the XML need a certain style of descriptive file.