Midrange News for the IBM i Community

Posted by: Bob Cozzi
Rogue Programmer
Cozzi Productions, Inc.
SQL iQuery Documentation - UDF and UDTF
has no ratings.
Published: 27 Aug 2019
Revised: 10 Sep 2019 - 1630 days ago
Last viewed on: 25 Feb 2024 (1142 views) 
  1. SQL iQuery - RUNiQRY CL Command
  2. CSV() - Read and Parse Comma Separated Values File
  3. CSV_VAL() Extract CSV Column Value
  4. CSV_XXXX() Extract CSV Column Value as xxxx
  5. CSV_COUNT - Retrieve Field Count
  6. ObjExist - Check Object Exits
  7. DTAARA - Data Area
  8. encode_URL Encode URL for the Web
  9. encode_TAG Encode HTML TAG Content
  10. FLDLIST - List the Fields of a Table
  11. FROMHEX - Fold 2-hex Chars into 1 Char
  13. MD5_HASH - UDF - Return MD5 Hash
  14. ifsStat - Get IFS File Attributes
  15. ifsExists - Check if IFS File Exists
  16. ifsFile - Query Contents of IFS Text File
  17. ifsDIR - List IFS Directory Entires
  18. DEPFILE - List Dependent Database Relations
  19. JOB - Get Job Name Component
  20. Job_ATTR - Job Attributes
  21. JOB_DATE Retrieve the Job Date
  22. JOBLOG - Write Message to Joblog
  23. Library List UDF and Procedures
  24. MBRLIST - Member List
  25. MCHINFO Machine Type and Model Number and OS version
  26. OSVER and OSVRM Get IBM i Version/Release
  27. PrintPDF - Print a PDF to a PDF Compatible Printer
  28. CPYTOPDF - Copy SPOOLED File to PDF file
  29. OBJ_LIST List Object in a Library
  30. LIB_LIST List Descriptions of Libraries on the Library List
  31. OBJ_EXPORTS List Exported Items from an Object
  32. OBJ_STRUCT Retrieve Objects Components
  33. RTVCMDD Retrieve Command Definition
  34. RTVJOBA - Retrieve Job Attributes
  35. RTVJOBD - Retrieve Job Description
  36. RTVLASTSPLF - Retrieve ID of Last SPOOLED File for this Job
  37. RTVxxx - Retrieve Various Objects Description Table Functions
  38. WATCHLIST - List Current Watches
  39. Polymorphic Qualified Name Syntax

Using IBM i? Need to create Excel, CSV, HTML, JSON, PDF, SPOOL reports? Learn more about the fastest and least expensive tool for the job: SQL iQuery.

iQuery.DTAARA - UDTF Published by: Bob Cozzi on 27 Aug 2019 view comments

Retrieve Data Area Data

The iQuery.dtaara() UDTF returns a one row result that contains the data area content, along with some of the data area attributes, such as length and type.

UDF Return Type Description
dtaara TABLE Returns the content and attributes of a data area.


Form 1:

iquery.DTAARA( library, data area name, starting-position, length );

Form 2:

iquery.DTAARA( data area name, starting-position, length );

Note: This function uses our polymorphic qualified name syntax.

The first form allows users to specify a library (schema) and data area object name in two separate parameters. The second form allows users to specify the data area name and optional library as one parameter using CL-style qualified syntax. If the data area is not qualified, the library list is searched for the data area.

The library parameter is the IBM i libary (schema) that contains the data area. It can be a valid library name, *LIBL or *CURLIB.

The data area parameter is the name of the data area whose content is returned. In form 1 it is a simple object name (upper/lower case is ignored). In form 2 it can be a simple object name or a qualified object name (e.g., qgpl/mystuff).

The Starting Position parameter is optional and identifies the first byte to retrieve from the data area. If unspecified, then position 1 is used. This parameter is only used for *CHAR data areas.

The Length parameter is optional and identifies the number of bytes to retrieve from the data area. If unspecified, then the number of bytes is calculated through the end of the data area data being returned. This parameter is only used for *CHAR data areas.

Result Set Columns

Column Type Description
DTAARA varchar(10) The name of the data area whose data is being returned.
DTAARALIB varchar(10) The library where the data area is located.
DTAARATYPE varchar(5) The type of data area (*CHAR, *DEC, *LGL).
LENGTH int The declared length of the data area.
DECPOS int If DTAARATYPE is *DEC, then this column contains the decimal positions. Otherwise it is null.
VALUE varchar(2000) The data area data returned begins at the Starting-position parameter for the number of bytes specified on the LENGTH parameter, but never exceeds the length of the data area definition itself.


select value INTO :LDA from table (iQuery.dtaara('*LDA')) da;

The local data area is read and its content copied to the LDA host variable. 

Remember, using SQL, you can cast the resulting value to any length you need. For example, if you store several pieces of information in the data area, you can extract the indivudal parts using the SQL SUBSTR function and also convert the result from a VARCHAR(2000) into some other data-type and length. For example:

select Dec(substr(value, 1, 5),5,0) as compDiv,
 char(substr(value, 11,20),30) as compName
INTO :compDivision, :companyName
FROM table(iQuery.dtaara('datalib/compinfo')) da;

Return to midrangenews.com home page.
Sort Ascend | Descend