282 lines
12 KiB
HTML
282 lines
12 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="Define data structures" />
|
|
<meta name="abstract" content="When a data structure is defined for use with an API, the structure must be built to receive what the API returns." />
|
|
<meta name="description" content="When a data structure is defined for use with an API, the structure must be built to receive what the API returns." />
|
|
<meta name="DC.Relation" scheme="URI" content="pgmerr.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="data.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="pgmerr_datas" />
|
|
<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>Define data structures</title>
|
|
</head>
|
|
<body id="pgmerr_datas"><a name="pgmerr_datas"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Define data structures</h1>
|
|
<div><p>When a data structure is defined for use with an API, the structure
|
|
must be built to receive what the API returns.</p>
|
|
<div class="section"><p>The use of IBM-supplied data structures eliminates having to create
|
|
your own data structures. For information on IBM-supplied data structures
|
|
that are contained in library QSYSINC, see Include files and the QSYSINC Library.</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>
|
|
</div>
|
|
<div class="section" id="pgmerr_datas__data_incorrect"><a name="pgmerr_datas__data_incorrect"><!-- --></a><h4 class="sectiontitle">Example of incorrect coding: Define a
|
|
data structure</h4><p>When the program that defines a data structure is
|
|
run, it does the following:</p>
|
|
<ul><li>Creates a user space</li>
|
|
<li>Retrieves a list of active jobs</li>
|
|
<li>Displays the first part of a job name</li>
|
|
<li>Deletes the user space that held the data</li>
|
|
</ul>
|
|
<p>In this example, the data structure to be used with the QUSLJOB API
|
|
has been defined incorrectly. The incorrectly defined variables are JNAME
|
|
and USRNAM. The JNAME length is defined as 1 through 12 and the USRNAM length
|
|
as 13 through 20. This is shown at <a href="#pgmerr_datas__SPTRK5A">(1)</a>.
|
|
The data displayed (JNAME variable) will be incorrect. The correct coding
|
|
is shown at <a href="#pgmerr_datas__SPTRK6B">(2)</a>.</p>
|
|
<pre> *****************************************************************
|
|
*
|
|
*Program Name: PGM1
|
|
*
|
|
*Program Language: RPG
|
|
*
|
|
*Description: This sample program illustrates the incorrect
|
|
* way of defining data structures.
|
|
*
|
|
*Header Files Included: QUSEC - Error Code Parameter
|
|
* QUSGEN - User Space Format for Generic Header
|
|
*
|
|
*APIs Used: QUSCRTUS - Create User Space
|
|
* QUSLJOB - List Job
|
|
* QUSRTVUS - Retrieve User Space
|
|
* QUSDLTUS - Delete User Space
|
|
*****************************************************************
|
|
* THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL
|
|
* THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.
|
|
* THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.
|
|
*
|
|
* BRING IN THE USER SPACE GENERIC HEADER
|
|
I/COPY QSYSINC/QRPGSRC,QUSGEN
|
|
* BRING IN THE ERROR STRUCTURE FROM QSYSINC
|
|
I/COPY QSYSINC/QRPGSRC,QUSEC
|
|
** JOB NAME STRUCTURE FOR CALLING QUSLJOB
|
|
IJOBNAM DS
|
|
I I '*ALL ' 1 10 JOB
|
|
I I '*ALL ' 11 20 USER
|
|
I I '*ALL ' 21 26 JOBNUM
|
|
** JOBL0100 FORMAT RETURNED FROM QUSLJOB API
|
|
** INCORRECTLY CODE THE JNAME/USRNAM LENGTHS
|
|
IRECVR DS
|
|
I 1 12 JNAME <span class="uicontrol" id="pgmerr_datas__SPTRK5A"><a name="pgmerr_datas__SPTRK5A"><!-- --></a>(1)</span>
|
|
I 13 20 USRNAM <span class="uicontrol">(1)</span>
|
|
I 21 26 JOBNBR
|
|
I 27 42 JOBID
|
|
I 43 52 JSTAT
|
|
I 53 53 JTYPE
|
|
I 54 54 JSUBT
|
|
I 55 56 RESRV
|
|
**
|
|
ISPCNAM DS
|
|
I I 'SPCNAME ' 1 10 SPC
|
|
I I 'QTEMP ' 11 20 LIB
|
|
** OTHER ASSORTED VARIABLES
|
|
I DS
|
|
I I 2000 B 1 40SIZ
|
|
I I B 5 80START
|
|
I I B 9 120LENDTA
|
|
I I X'00' 13 13INTVAL
|
|
*
|
|
* SET UP TO ACCEPT EXCEPTIONS
|
|
C Z-ADD*ZEROS QUSBNB
|
|
*
|
|
* CREATE THE SPACE TO HOLD THE DATA
|
|
C CALL 'QUSCRTUS'
|
|
C PARM SPCNAM
|
|
C PARM 'EXT_ATTR'EXTATR 10
|
|
C PARM SIZ
|
|
C PARM INTVAL
|
|
C PARM '*ALL 'PUBAUT 10
|
|
C PARM 'TEXT DSC'TXTDSC 50
|
|
C PARM '*YES 'REPLAC 10
|
|
C PARM QUSBN
|
|
*
|
|
* CALL THE API TO LIST THE ACTIVE JOBS
|
|
C CALL 'QUSLJOB'
|
|
C PARM SPCNAM
|
|
C PARM 'JOBL0100'FORMAT 8
|
|
C PARM JOBNAM
|
|
C PARM '*ACTIVE 'STAT 10
|
|
C PARM QUSBN
|
|
*
|
|
* RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
|
|
C Z-ADD1 START
|
|
C Z-ADD140 LENDTA
|
|
C CALL 'QUSRTVUS'
|
|
C PARM SPCNAM
|
|
C PARM START
|
|
C PARM LENDTA
|
|
C PARM QUSBP
|
|
C PARM QUSBN
|
|
*
|
|
* RETRIEVE THE FIRST LIST ENTRY
|
|
C QUSBPQ ADD 1 START
|
|
C Z-ADD56 LENDTA
|
|
C CALL 'QUSRTVUS'
|
|
C PARM SPCNAM
|
|
C PARM START
|
|
C PARM LENDTA
|
|
C PARM RECVR
|
|
C PARM QUSBN
|
|
*
|
|
* DISPLAY THE JOB NAME
|
|
C DSPLY JNAME
|
|
****************************
|
|
* When displayed, JNAME *
|
|
* will look something like *
|
|
* 'QCPF QS' *
|
|
****************************
|
|
* DELETE THE SPACE THAT HELD THE DATA
|
|
C CALL 'QUSDLTUS'
|
|
C PARM SPCNAM
|
|
C PARM QUSBN
|
|
**
|
|
C SETON LR</pre>
|
|
</div>
|
|
<div class="section" id="pgmerr_datas__data_correct"><a name="pgmerr_datas__data_correct"><!-- --></a><h4 class="sectiontitle">Example: Define a data structure of correct
|
|
coding</h4><p>The following program uses a data structure that is supplied
|
|
from the QSYSINC library. When you use this data structure, you can prevent
|
|
errors in data structure creation from happening. If the data structures change
|
|
from release to release, updates to programs do not have to be done. The application
|
|
program would have to be updated <em>only</em> if a new field was added to the
|
|
data structure and you <em>wanted</em> to use the field. The copying of the
|
|
QSYSINC data structure is shown at <a href="#pgmerr_datas__SPTRK6B">(2)</a>.</p>
|
|
<pre> *
|
|
*
|
|
*****************************************************************
|
|
*
|
|
*Program Name: PGM2
|
|
*
|
|
*Program Language: RPG
|
|
*
|
|
*Description: This sample program illustrates the correct
|
|
* way of defining data structures.
|
|
*
|
|
*Header Files Included: QUSEC - Error Code Parameter
|
|
* QUSGEN - User Space Format for Generic Header
|
|
* QUSLJOB - List Job API
|
|
*
|
|
*APIs Used: QUSCRTUS - Create User Space
|
|
* QUSLJOB - List Job
|
|
* QUSRTVUS - Retrieve User Space
|
|
* QUSDLTUS - Delete User Space
|
|
*
|
|
*
|
|
* THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL
|
|
* THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.
|
|
* THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.
|
|
*
|
|
I/COPY QSYSINC/QRPGSRC,QUSGEN
|
|
I/COPY QSYSINC/QRPGSRC,QUSEC
|
|
I/COPY QSYSINC/QRPGSRC,QUSLJOB <span class="uicontrol" id="pgmerr_datas__SPTRK6B"><a name="pgmerr_datas__SPTRK6B"><!-- --></a>(2)</span>
|
|
** JOB NAME STRUCTURE FOR CALLING QUSLJOB
|
|
IJOBNAM DS
|
|
I I '*ALL ' 1 10 JOB
|
|
I I '*ALL ' 11 20 USER
|
|
I I '*ALL' 21 26 JOBNUM
|
|
** JOBL0100 FORMAT RETURNED FROM QUSLJOB API
|
|
**
|
|
**
|
|
ISPCNAM DS
|
|
I I 'SPCNAME ' 1 10 SPC
|
|
I I 'QTEMP ' 11 20 LIB
|
|
** OTHER ASSORTED VARIABLES
|
|
I DS
|
|
I I 2000 B 1 40SIZ
|
|
I I B 5 80START
|
|
I I B 9 120LENDTA
|
|
I I X'00' 13 13 INTVAL
|
|
*
|
|
* SET UP TO ACCEPT EXCEPTIONS
|
|
C Z-ADD*ZEROS QUSBNB
|
|
*
|
|
* CREATE THE SPACE TO HOLD THE DATA
|
|
C CALL 'QUSCRTUS'
|
|
C PARM SPCNAM
|
|
C PARM 'EXT_ATTR'EXTATR 10
|
|
C PARM SIZ
|
|
C PARM INTVAL
|
|
C PARM '*ALL 'PUBAUT 10
|
|
C PARM 'TEXT DSC'TXTDSC 50
|
|
C PARM '*YES 'REPLAC 10
|
|
C PARM QUSBN
|
|
*
|
|
* CALL THE API TO LIST THE ACTIVE JOBS
|
|
C CALL 'QUSLJOB'
|
|
C PARM SPCNAM
|
|
C PARM 'JOBL0100'FORMAT 8
|
|
C PARM JOBNAM
|
|
C PARM '*ACTIVE 'STAT 10
|
|
C PARM QUSBN
|
|
*
|
|
* RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
|
|
C Z-ADD1 START
|
|
C Z-ADD140 LENDTA
|
|
C CALL 'QUSRTVUS'
|
|
C PARM SPCNAM
|
|
C PARM START
|
|
C PARM LENDTA
|
|
C PARM QUSBP
|
|
C PARM QUSBN
|
|
*
|
|
* RETRIEVE THE FIRST LIST ENTRY
|
|
C QUSBPQ ADD 1 START
|
|
C Z-ADD56 LENDTA
|
|
C CALL 'QUSRTVUS'
|
|
C PARM SPCNAM
|
|
C PARM START
|
|
C PARM LENDTA
|
|
C PARM QUSDD
|
|
C PARM QUSBN
|
|
*
|
|
* DISPLAY THE JOB NAME
|
|
C DSPLY QUSDDB
|
|
*************************
|
|
* Correct job name *
|
|
* will now show as *
|
|
* 'QCPF ' *
|
|
*************************
|
|
* DELETE THE SPACE THAT HELD THE DATA
|
|
C CALL 'QUSDLTUS'
|
|
C PARM SPCNAM
|
|
C PARM QUSBN
|
|
**
|
|
C SETON LR</pre>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="pgmerr.htm" title="Provides information about common programming errors, as well as examples of correct and incorrect coding.">Common API programming errors</a></div>
|
|
</div>
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
|
<div><a href="data.htm" title="APIs support character data and binary data.">Data types</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |