ibm-information-center/dist/eclipse/plugins/i5OS.ic.apiref_5.4.0.1/exretilerpg.htm

648 lines
34 KiB
HTML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="reference" />
<meta name="DC.Title" content="Example in ILE RPG: Retrieving a file description to a user space" />
<meta name="abstract" content="This program retrieves a file definition template to a user space." />
<meta name="description" content="This program retrieves a file definition template to a user space." />
<meta name="DC.Relation" scheme="URI" content="ExTaskRetfile.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="exretilerpg" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>Example in ILE RPG: Retrieving a file description to a user space</title>
</head>
<body id="exretilerpg"><a name="exretilerpg"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">Example in ILE RPG: Retrieving a file description to a user space</h1>
<div><p>This program retrieves a file definition template to a user space.</p>
<div class="section" id="exretilerpg__HDRR2"><a name="exretilerpg__HDRR2"><!-- --></a><p>Refer to <a href="exretilec.htm">Example in ILE C: Retrieving a file description to a user space</a> for
the original example.</p>
<div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm">Code license and disclaimer information</a> for
important legal information.</div>
<pre> D***************************************************************
D***************************************************************
D*
D* Program: RTVFD
D*
D* Language: ILE RPG
D*
D* Description: This program retrieves a file definition
D* template to a user space.
D*
D* APIs Used: QDBRTVFD - Retrieve File Description
D* QUSCRTUS - Create User Space
D* QUSCUSAT - Change User Space Attributes
D* QUSPTRUS - Retrieve a pointer to a User Space
D*
D***************************************************************
D***************************************************************
D*
D* Error Code parameter include
D*
D/COPY QSYSINC/QRPGLESRC,QUSEC
D*
D* Not shown due to its size, this program also includes QDBRTVFD
D* and defines all of the data structures in QDBRTVFD as being
D* BASED(SPCPTR). For illustrative purposes, this sample shows
D* only the first significant data structure.
D*
D****************************************************************
D*
D*File Definition Template (FDT) Header
D*
D****************************************************************
D*This section is always located at the beginning of the
D*returned data.
D****************************************************************
DQDBQ25 DS BASED(SPCPTR)
D* Header information - The
D* FDT starts here
D QDBFYRET 1 4B 0
D* Bytes returned - The length
D* of the data returned
D QDBFYAVL 5 8B 0
D* Bytes available - The number
D* of bytes provided for the
D* file definition template
D* data
D*QDBFHFLG 2
D QDBBITS27 9 10
D* QDBRSV100 2 BITS
D* QDBFHFPL00 1 BIT
D* QDBRSV200 1 BIT
D* QDBFHFSU00 1 BIT
D* QDBRSV300 1 BIT
D* QDBFHFKY00 1 BIT
D* QDBRSV400 1 BIT
D* QDBFHFLC00 1 BIT
D* QDBFKFSO00 1 BIT
D* QDBRSV500 1 BIT
D* QDBFHSHR00 1 BIT
D* QDBRSV600 2 BITS
D* QDBFIGCD00 1 BIT
D* QDBFIGCL00 1 BIT
D* Attribute Bytes
D QDBRSV7 11 14
D* Reserved.
D QDBLBNUM 15 16B 0
D* Number Of Data Members
D* 1 = Externally described
D* physical file, or program
D* described physical file
D* that is NOT linked to a
D* Data Dictionary.
D* 1-32 = Number of Data
D* Dictionary record
D* formats for a program
D* described physical
D* file that is linked to
D* a Data Dictionary.
D* 1-32 = Number of based-on
D* physical files for
D* a logical file.
D*QDBFKDAT 14
D QDBFKNUM00 17 18B 0
D QDBFKMXL00 19 20B 0
D* QDBFKFLG00 1
D QDBBITS28 21 21
D* QDBRSV802 1 BIT
D* QDBFKFCS02 1 BIT
D* QDBRSV902 4 BITS
D* QDBFKFRC02 1 BIT
D* QDBFKFLT02 1 BIT
D QDBFKFDM00 22 22
D QDBRSV1000 23 30
D* Keyed Sequence Access Path
D QDBFHAUT 31 40
D* Public Authority (AUT)
D* '*CHANGE ' = Public change
D* authority.
D* '*ALL ' = Public all
D* authority.
D* '*USE ' = Public use
D* authority.
D* '*EXCLUDE ' = Public exclude
D* authority.
D* 'authorization-list-name'
D* = Name of the
D* authorization
D* list whose
D* authority is
D* used for the
D* file.
D* This is the original public
D* authority that the file was
D* created with, NOT the current
D* public authority for the file.
D QDBFHUPL 41 41
D* Preferred Storage Unit (UNIT)
D* X'00' = The storage space for
D* the file and its
D* members can be
D* allocated on any
D* available auxiliary
D* storage unit (*ANY).
D* X'01'-X'FF' = The unit
D* identifier (a
D* number from 1
D* to 255 assigned
D* when the disk
D* device is
D* configured) of
D* a specific
D* auxiliary
D* storage unit on
D* the system.
D QDBFHMXM 42 43B 0
D* Maximum Members (MAXMBRS)
D* 0 = No maximum is specified
D* for the number of members,
D* the system maximum of
D* 32,767 members is used
D* (*NOMAX).
D* 1-32,767 = The value for the
D* maximum number of
D* members that the
D* file can have
D* (maximum-members).
D QDBFWTFI 44 45B 0
D* Maximum File Wait Time
D* (WAITFILE)
D* -1 = The default wait time
D* specified in the class
D* description is used as
D* the wait time for the
D* file (*CLS).
D* 0 = A program does NOT wait
D* for the file, an
D* immediate allocation of
D* the file is required
D* (*IMMED).
D* 1-32,767 = The number of
D* seconds that a
D* program waits for
D* the file (number-
D* of-seconds).
D QDBFHFRT 46 47B 0
D* Records To Force A Write
D* (FRCRATIO)
D* 0 = There is NO force write
D* ratio, the system
D* determines when the
D* records are written to
D* auxiliary storage (*NONE).
D* 1-32,767 = The number of
D* inserted, updated,
D* or deleted records
D* that are processed
D* before they are
D* explicitly forced
D* to auxiliary
D* storage (number-
D* of-records-before-
D* force).
D QDBHMNUM 48 49B 0
D* Number Of Members
D* 0-32,767 = The current number
D* of members for the
D* file.
D QDBRSV11 50 58
D* Reserved.
D QDBFBRWT 59 60B 0
D* Maximum Record Wait Time
D* (WAITRCD)
D* -2 = The wait time is the
D* maximum allowed by the
D* system, 32,767 seconds
D* (*NOMAX).
D* -1 = A program does NOT wait
D* for the record, an
D* immediate allocation of
D* the record is required
D* (*IMMED).
D* 1-32,767 = The number of
D* seconds that a
D* program waits for
D* the record
D* (number-of-
D* seconds).
D*QDBQAAF00 1
D QDBBITS29 61 61
D* QDBRSV1200 7 BITS
D* QDBFPGMD00 1 BIT
D* Additional Attribute Flags
D QDBMTNUM 62 63B 0
D* Total Number Of Record
D* Formats
D* 1-32 = Number of record
D* formats for the file.
D*QDBFHFL2 2
D QDBBITS30 64 65
D* QDBFJNAP00 1 BIT
D* QDBRSV1300 1 BIT
D* QDBFRDCP00 1 BIT
D* QDBFWTCP00 1 BIT
D* QDBFUPCP00 1 BIT
D* QDBFDLCP00 1 BIT
D* QDBRSV1400 9 BITS
D* QDBFKFND00 1 BIT
D* Additional Attribute Flags
D QDBFVRM 66 67B 0
D* First Supported
D* Version Release Modification
D* Level
D* X'0000' = Pre-Version 2
D* Release 1
D* Modification 0 file.
D* X'1500' = Version 2 Release 1
D* Modification 0,
D* V2R1M0, file.
D* X'1501' = Version 2 Release 1
D* Modification 1,
D* V2R1M1, file.
D* X'1600' = Version 2 Release 2
D* Modification 0,
D* V2R2M0, file.
D* New Database support is used
D* in the file which will
D* prevent it from being saved
D* and restored to a prior
D* Version Release and
D* Modification level.
D*QDBQAAF2 1
D QDBBITS31 68 68
D* QDBFHMCS00 1 BIT
D* QDBRSV1500 1 BIT
D* QDBFKNLL00 1 BIT
D* QDBFNFLD00 1 BIT
D* QDBFVFLD00 1 BIT
D* QDBFTFLD00 1 BIT
D* QDBFGRPH00 1 BIT
D* QDBRSV1600 1 BIT
D* Additional Attribute Flags
D QDBRSV17 69 69
D* Reserved.
D QDBFHCRT 70 82
D* File Level Identifier
D* The date of the file in
D* internal standard format
D* (ISF), CYYMMDDHHMMSS.
D*QDBFHTX 52
D QDBRSV1800 83 84
D QDBFHTXT00 85 134
D* File Text Description
D QDBRSV19 135 147
D* Reserved
D*QDBFSRC 30
D QDBFSRCF00 148 157
D QDBFSRCM00 158 167
D QDBFSRCL00 168 177
D* Source File Fields
D QDBFKRCV 178 178
D* Access Path Recovery
D* (RECOVER)
D* 'A' = The file has its access
D* path built after the
D* IPL has been completed
D* (*AFTIPL).
D* 'N' = The access path of the
D* file is NOT built
D* during or after an IPL
D* (*NO). The file's
D* access path is built
D* when the file is next
D* opened.
D* 'S' = The file has its access
D* path built during the
D* IPL (*IPL).
D QDBRSV20 179 201
D* Reserved.
D QDBFTCID 202 203B 0
D* Coded Character Set
D* Identifier, CCSID, For
D* Text Description (TEXT)
D* 0 = There is NO text
D* description for the file.
D* 1-65,535 = The CCSID for the
D* file's text
D* description.
D QDBFASP 204 205
D* Auxiliary Storage Pool (ASP)
D* X'0000' = The file is
D* located on the
D* system auxiliary
D* storage pool.
D* X'0002'-X'0010' = The user
D* auxiliary storage
D* pool the file is
D* located on
D* (asp-identifier).
D QDBRSV21 206 206
D* Reserved.
D QDBXFNUM 207 208B 0
D* Maximum Number Of Fields
D* 1-8000 = The number of fields
D* in the file's record
D* format that contains
D* the largest number
D* of fields.
D QDBRSV22 209 284
D* Reserved.
D QDBFODIC 285 288B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* IDDU/SQL Data Dictionary
D* Area, Qdbfdic.
D QDBRSV23 289 302
D* Reserved.
D QDBFFIGL 303 304B 0
D* File Generic Key Length
D* 0-2000 = The length of the
D* key before the first
D* *NONE key field for
D* the file.
D* If this file has an arrival
D* sequence access path, this
D* field is NOT applicable.
D QDBFMXRL 305 306B 0
D* Maximum Record Length
D* 1-32766 = The length of the
D* record in the
D* file's record
D* format that
D* contains the
D* largest number of
D* bytes.
D QDBRSV24 307 314
D* Reserved.
D QDBFGKCT 315 316B 0
D* File Generic Key Field Count
D* 0-120 = The count of the
D* number of key fields
D* before the first
D* *NONE key field for
D* the file.
D* If this file has an arrival
D* sequence access path, this
D* field is NOT applicable.
D QDBFOS 317 320B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* File Scope Array, Qdbfb.
D QDBRSV25 321 328
D* Reserved.
D QDBFOCS 329 332B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* Alternative Collating
D* Sequence Table section,
D* Qdbfacs.
D QDBRSV26 333 336
D* Reserved.
D QDBFPACT 337 338
D* Access Path Type
D* 'AR' = Arrival sequence
D* access path.
D* 'KC' = Keyed sequence access
D* path with duplicate
D* keys allowed.
D* Duplicate keys are
D* accessed in first-
D* changed-first-out
D* (FCFO) order.
D* 'KF' = Keyed sequence access
D* path with duplicate
D* keys allowed.
D* Duplicate keys are
D* accessed in first-
D* in-first-out
D* (FIFO) order.
D* 'KL' = Keyed sequence access
D* path with duplicate
D* keys allowed.
D* Duplicate keys are
D* accessed in last-
D* in-first-out
D* (LIFO) order.
D* 'KN' = Keyed sequence access
D* path with duplicate
D* keys allowed.
D* No order is guaranteed
D* when accessing
D* duplicate keys.
D* Duplicate keys are
D* accessed in one of the
D* following methods:
D* (FCFO) (FIFO) (LIFO).
D* 'KU' = Keyed sequence access
D* path with NO duplicate
D* keys allowed (UNIQUE).
D QDBFHRLS 339 344
D* File Version Release
D* Modification Level
D* 'VxRyMz' = Where x is the
D* Version, y is the
D* Release, and z is
D* the Modification
D* level
D* example V2R1M1
D* Version 2 Release
D* 1 Modification 1
D QDBRSV27 345 364
D* Reserved.
D QDBPFOF 365 368B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* Physical File Specific
D* Attributes section, Qdbfphys.
D QDBLFOF 369 372B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* Logical File Specific
D* Attributes section, Qdbflogl.
D*QDBFSSFP00 6
D* QDBFNLSB01 1
D QDBBITS58 373 373
D* QDBFSSCS02 3 BITS
D* QDBR10302 5 BITS
D QDBFLANG01 374 376
D QDBFCNTY01 377 378
D* Sort Sequence Table
D QDBFJORN 379 382B 0
D* Offset from the start of the
D* FDT header, Qdbfh, to the
D* Journal Section, Qdbfjoal.
D QDBRSV28 383 400
D* Reserved.
D****************************************************************
D*
D*The FDT header ends here.
D*
D****************************************************************
D*
D* Misc. elements
D*
DSPC_NAME S 20
DFILE_NAME S 20
DFMT_NAME S 10
DFILE_USED S 20
DLIB_NAME S 10
DSPC_SIZE S 9B 0
DSPC_INIT S 1 INZ(X'00')
DSPCPTR S *
DFORMAT S 8
DOVERRIDES S 1 INZ('0')
DSYSTEM S 10 INZ('*LCL')
DFORMAT_1 S 10 INZ('*INT')
DCHG_ATTR DS
D NBR_ATTR 9B 0 INZ(1)
D ATTR_KEY 9B 0 INZ(3)
D DATA_SIZE 9B 0 INZ(1)
D ATTR_DATA 1 INZ('1')
C*
C* Start of mainline
C*
C *ENTRY PLIST
C PARM SPC_NAME
C PARM FILE_NAME
C PARM FMT_NAME
C*
C EXSR INIT
C EXSR PROCES
C EXSR DONE
C*
C* Start of subroutines
C*
C*****************************************************************
C PROCES BEGSR
C*
C* The template returned from QDBRTVFD is now addressable by way
C* of SPCPTR; as an example the program will now display the
C* access method for the file:
C*
C DSPLY QDBFPACT
C ENDSR
C*
C*****************************************************************
C INIT BEGSR
C*
C* One time initialization code for this program
C*
C* Set Error Code structure to not use exceptions
C*
C Z-ADD 16 QUSBPRV
C*
C* Create a User Space for QDBRTVFD
C*
C CALL 'QUSCRTUS'
C PARM SPC_NAME
C PARM *BLANKS EXT_ATTR 10
C PARM 1024 SPC_SIZE
C PARM SPC_INIT
C PARM '*CHANGE' SPC_AUT 10
C PARM 'QDBRTVFD' SPC_TEXT 50
C PARM '*YES' SPC_REPLAC 10
C PARM QUSEC
C PARM '*USER' SPC_DOMAIN 10
C*
C* Check for errors on QUSCRTUS
C*
C QUSBAVL IFGT 0
C MOVEL 'QUSCRTUS' APINAM 10
C EXSR APIERR
C END
C*
C* Change the User Space so that it is extendable
C*
C CALL 'QUSCUSAT'
C PARM LIB_NAME
C PARM SPC_NAME
C PARM CHG_ATTR
C PARM QUSEC
C*
C* Check for errors on QUSCUSAT
C*
C QUSBAVL IFGT 0
C MOVEL 'QUSCUSAT' APINAM 10
C EXSR APIERR
C END
C*
C* Get a resolved pointer to the User Space
C*
C CALL 'QUSPTRUS'
C PARM SPC_NAME
C PARM SPCPTR
C PARM QUSEC
C*
C* Check for errors on QUSPTRUS
C*
C QUSBAVL IFGT 0
C MOVEL 'QUSPTRUS' APINAM 10
C EXSR APIERR
C END
C*
C* If no errors, then call QDBRTVFD passing the address of the
C* User Space as the receiver variable. As Data Structure
C* QDBQ25 is defined as BASED(SPCPTR) and SPCPTR is set to the
C* first byte of the User Space, simply passing QDBQ25 will cause
C* QDBRTVFD to use the User Space.
C*
C CALL 'QDBRTVFD'
C PARM QDBQ25
C PARM 16776704 SPC_SIZE
C PARM FILE_USED
C PARM 'FILD0100' FORMAT
C PARM FILE_NAME
C PARM FMT_NAME
C PARM OVERRIDES
C PARM SYSTEM
C PARM FORMAT_1
C PARM QUSEC
C*
C* Check for errors on QDBRTVFD
C*
C QUSBAVL IFGT 0
C MOVEL 'QDBRTVFD' APINAM 10
C EXSR APIERR
C END
C ENDSR
C*****************************************************************
C APIERR BEGSR
C*
C* Log any error encountered, and exit the program
C*
C APINAM DSPLY
C QUSEI DSPLY
C EXSR DONE
C ENDSR
C*****************************************************************
C DONE BEGSR
C*
C* Exit the program
C*
C EVAL *INLR = '1'
C RETURN
C ENDSR</pre>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="ExTaskRetfile.htm" title="These programming examples show an application that uses a user space as a receiver variable by retrieving a file description to a user space. This approach is possible only if you use an HLL that is able to work with pointers.">Examples: Retrieving a file description to a user space</a></div>
</div>
</div>
</body>
</html>