GETFILE (XFILE)

9.0D

 

The GETFILE instruction retrieves information from a file variable. The instruction uses the following format:

 

 

[label]

GETFILE

{xfile},{keyword}={value}[,{keyword}={value}...]

 

Where:

label

Optional. A Program Execution Label.

xfile

Required. A previously defined XFILE variable.

keyword

Required. One of the valid keywords defined below.

value

Required. A previously defined Character String Variable or Numeric Variable in which the value is returned.

Flags Affected: ZERO, EOS, OVER

Note the following:

  1. If the file specified is not open, the ZERO flag is cleared and the variables remain unchanged. If the file is open, the ZERO flag is set.

  2. If the value returned to a string variable is longer than the variable, the EOS flag is set. When using the XMLDATA keyword, an 'I83 subcode 310' error is generated when the XML data is too large to be stored into the string variable without being truncated.

  3. If the value returned to a numeric variable overflows the variable, the OVER flag is set.

  4. All requests that return a numeric variable will return a value of zero (0) for an invalid request.

  5. The following keywords may be used:

    6.  

    Keyword

    Returns the ...

    CURFIELDS={svar}

    field tag names for the current record in a recordset once read. (9.1)

    FIELDS={svar}

    accumulated union of all of the field names for all of the records accessed in a recordset.

    FILENAME={svar}

    name of the physical XML file.

    FILTERNOCASE={nvar}

    whether the filtered READ instructions for a XFILE are to be executed in a case-sensitive manner. By default a filtered READ for a XFILE is executed with case sensitivity. If the FILTERNOCASE keyword for a XFILE is set ON, the filtered READ for the XFILE is executed without case sensitivity.

    NOEMPTYFIELDS={nvar}

    a flag indicating that an error will occur on reading an empty field.

    ROOT={svar}

    name of the root element.

    RECORDSET={svar}

    name of the recordset.

    SCHEMANAME={svar}

    name of the physical XML schema file.

    SCHEMADATA={svar}

    XML schema data.

    SCHEMANOCASE={nvar}

    a flag indicating data field and recordset labels are not case sensitive.

    SCHEMASIZE={nvar}

    the size required for a DIM variable to receive the data for the SCHEMADATA keyword.

    SCHEMATYPE={svar}

    delimited string that includes the schema data label references with a XML data node type and its schema type.

    SCHEMAWRITE={nvar}

    a flag indicating that the schema should be output on a FLUSH or CLOSE statement.

    SUBHEADER={svar}

    current XFILE sub-header that has been assigned to the XFILE using a SETFILE instruction. If a sub-header has been assigned to the XFILE, this sub-header is output to the XML data immediately following the XML declaration line that contains the version. (9.6D)

    XMLFORMAT={nvar}

    A value indicating the XML output formatting options.

    XMLDATA={svar}

    XML data.

    XMLSIZE={nvar}

    the size required for a DIM variable to receive the data for the XMLDATA keyword.

     

  1. A field in a recordset is returned as <name>,<type>,<size>,<array count> where:

    2.  

    <name>

    name of the field

    <type>

    A=attribute, E=element, R=recordset

    <size>

    maximum size of the data

    <array count>

    maximum number of times the field appears in one record

     

  1. The {keyword} is "XMLFORMAT =" followed by a decimal number or Numeric Variable (four byte INTEGER) containing bit maps as follows:

    2.  

    Keyword

    Value

    Meaning ...

    XMLOUTFMTUSEINDENT

    0x1

    Use tag indentation on output.

    XMLOUTFMTUSEEOR

    0x2

    Write End Of Record indicators.

    XMLOUTFMTUSETABS

    0x4

    Use tab characters of indentation.

    XMLOUTFMTSPCSUPRESS

    0x8

    Suppress leading and trailing spaces when outputting XML data.

    XMLOUTFMTESCALWAYS

    0x10

    Always escape double-quote (") and single-quote (') characters when outputting XML element data. This format control allows double-quote and single-quote characters to be escaped for the element data in the same manner as they are escaped for attribute data. When this control is not used, the default behavior is to only escape these characters in the attribute data as defined in the W3C XML specification.

    XMLOUTFMTCVTTOSPC

    0x20

    Convert any character less than 0x20 to 0x20. This output format control should only be used when XML output data contains binary data that the user does not want to be escaped.

    XMLOUTFMTWRTISO8859

    0x200

    Use ISO8859 when outputting XML data for the XFILE. (10.4)

     

  2. The SCHEMATYPE string is semicolon (;) delimited and formatted as follows:

    3.  

    {data};{data1};...

    Where:

    {data} = '<name>,<type},{schematype}'

     

    Parameter

    Meaning

    name

    Name of xml element or attribute

    type

    A=attribute or E=element

    schematype

    S=xsd:string, N=xsd:decimal, B=xsd:boolean

 

  1. When a XFILE is created and written in a PLB program, the default {schematype} for all xml data references are defined to be 'xsd:string'.

  2. The SETFILE schematype changes the current schema type.

    3.  

 

See Also: SETFILE (XFILE), XML Support

 


PL/B Language Reference FPOSIT (XFILE) INSERTXML