525 lines
20 KiB
HTML
525 lines
20 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="Using offsets in a user space" />
|
|
<meta name="abstract" content="An offset indicates the point in a structure that specific information should start. When offsets are correctly used, programs can extract specific pieces of data from a structure and perform actions on that data." />
|
|
<meta name="description" content="An offset indicates the point in a structure that specific information should start. When offsets are correctly used, programs can extract specific pieces of data from a structure and perform actions on that data." />
|
|
<meta name="DC.Relation" scheme="URI" content="pgmerr.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_offusrs" />
|
|
<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>Using offsets in a user space</title>
|
|
</head>
|
|
<body id="pgmerr_offusrs"><a name="pgmerr_offusrs"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Using offsets in a user space</h1>
|
|
<div><p>An offset indicates the point in a structure that specific information
|
|
should start. When offsets are correctly used, programs can extract specific
|
|
pieces of data from a structure and perform actions on that data.</p>
|
|
<div class="section"><p>Using offsets incorrectly can produce errors when coding in a
|
|
base 1 language such as RPG and COBOL. One way to determine the base of a
|
|
language is to determine how the first element of an array is specified. In
|
|
a base 0 language, the first element is number 0. In base 1 languages, the
|
|
first element is number 1.</p>
|
|
<p>The example programs in the following topics
|
|
are coded using RPG. RPG is a base 1 language. However, APIs produce information
|
|
using a base of 0. To compensate, the API user must add 1 to all decimal and
|
|
hexadecimal offsets to the formats.</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_offusrs__offusrs_incorrect"><a name="pgmerr_offusrs__offusrs_incorrect"><!-- --></a><h4 class="sectiontitle">Example of incorrect coding: Use offsets
|
|
in a user space</h4><p>The beginning point for reading a user space is
|
|
shown at <a href="#pgmerr_offusrs__SPTRK18A">(1)</a>. The data is read
|
|
and placed into a user space. However, the data in the user space is incorrect
|
|
because the position to start was off by 1. This program started to retrieve
|
|
the data one character (or position) too soon. The correct coding is shown
|
|
at <a href="#pgmerr_offusrs__SPTRK19B">(2)</a>.</p>
|
|
<pre>I*****************************************************************
|
|
I*****************************************************************
|
|
I*
|
|
I*Program Name: APIUG1
|
|
I*
|
|
I*Programming Language: RPG
|
|
I*
|
|
I*Description: This sample program illustrates the incorrect
|
|
I* way of using the offset in a user space.
|
|
I*
|
|
I*Header Files Included: QUSGEN - Generic Header of a User Space
|
|
I* QUSEC - Error Code Parameter
|
|
I* (Copied into Program)
|
|
I* QUSLOBJ - List Objects API
|
|
I*
|
|
I*APIs Used: QUSCRTUS - Create User Space
|
|
I* QUSLOBJ - List Objects
|
|
I* QUSRTVUS - Retrieve User Space
|
|
I* QUSDLTUS - Delete User Space
|
|
I*****************************************************************
|
|
I*****************************************************************
|
|
I*
|
|
I* Generic Header of a User Space Include
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSGEN
|
|
I*
|
|
I* Error Code Parameter Include for the APIs
|
|
I*
|
|
I* The following QUSEC include is copied into this program
|
|
I* so that the variable length field can be defined as a
|
|
I* fixed length.
|
|
I*
|
|
I*** START HEADER FILE SPECIFICATIONS ****************************
|
|
I*
|
|
I*Header File Name: H/QUSEC
|
|
I*
|
|
I*Descriptive Name: Error Code Parameter.
|
|
I*
|
|
I*5763-SS1 (C) Copyright IBM Corp. 1994,1994
|
|
I*All rights reserved.
|
|
I*US Government Users Restricted Rights -
|
|
I*Use, duplication or disclosure restricted
|
|
I*by GSA ADP Schedule Contract with IBM Corp.
|
|
I*
|
|
I*Licensed Materials-Property of IBM
|
|
I*
|
|
I*
|
|
I*Description: Include header file for the error code parameter.
|
|
I*
|
|
I*Header Files Included: None.
|
|
I*
|
|
I*Macros List: None.
|
|
I*
|
|
I*Structure List: Qus_EC_t
|
|
I*
|
|
I*Function Prototype List: None.
|
|
I*
|
|
I*Change Activity:
|
|
I*
|
|
I*CFD List:
|
|
I*
|
|
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
|
|
I*---- ------------ ----- ------ --------- ----------------------
|
|
I*$A0= D2862000 3D10 931201 DPOHLSON: New Include
|
|
I*
|
|
I*End CFD List.
|
|
I*
|
|
I*Additional notes about the Change Activity
|
|
I*End Change Activity.
|
|
I*** END HEADER FILE SPECIFICATIONS ******************************
|
|
I*****************************************************************
|
|
I*Record structure for Error Code Parameter
|
|
I**** ***
|
|
I*NOTE: The following type definition only defines the corrected
|
|
I* portion of the format. Varying length field Exception
|
|
I* Data will not be defined here.
|
|
I*****************************************************************
|
|
IQUSBN DS
|
|
I* Qus EC
|
|
I B 1 40QUSBNB
|
|
I* Bytes Provided
|
|
I B 5 80QUSBNC
|
|
I* Bytes Available
|
|
I 9 15 QUSBND
|
|
I* Exception Id
|
|
I 16 16 QUSBNF
|
|
I* Reserved
|
|
I* 17 17 QUSBNG
|
|
I*
|
|
I* Varying length
|
|
I 17 100 QUSBNG
|
|
I*
|
|
I* List Objects API Include
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
|
|
I*
|
|
I* Qualified User Space Data Structure
|
|
I*
|
|
IUSERSP DS
|
|
I I 'APIUG1 ' 1 10 USRSPC
|
|
I I 'QGPL ' 11 20 SPCLIB
|
|
I* Qualified Object Name Data Structure
|
|
IOBJECT DS
|
|
I I '*ALL ' 1 10 OBJNAM
|
|
I I 'QGPL ' 11 20 OBJLIB
|
|
I*
|
|
I* Miscellaneous Data Structure
|
|
I*
|
|
I DS
|
|
I* Set up parameters for the Create User Space API
|
|
I I 'TESTUSRSPC' 1 10 EXTATR
|
|
I I X'00' 11 11 INTVAL
|
|
I 12 12 RSVD1
|
|
I I 256 B 13 160INTSIZ
|
|
I I '*USE ' 17 26 PUBAUT
|
|
I I 'TEXT DESCRIPTION - 27 76 TEXT
|
|
I 'FOR USER SPACE -
|
|
I 'CALLED APIUG1 '
|
|
I I '*YES ' 77 87 REPLAC
|
|
I* Set up parameters for the List Objects API
|
|
I I 'OBJL0100' 88 95 FORMAT
|
|
I I '*ALL ' 96 105 OBJTYP
|
|
I 106 108 RSVD2
|
|
I* Set up parameters for the Retrieve User Space API
|
|
I I 1 B 109 1120STRPOS
|
|
I I 192 B 113 1160LENDTA
|
|
I B 117 1200COUNT
|
|
C*
|
|
C* Create a user space called APIUG1 in library QGPL.
|
|
C*
|
|
C Z-ADD100 QUSBNB
|
|
C CALL 'QUSCRTUS'
|
|
C PARM USERSP
|
|
C PARM EXTATR
|
|
C PARM INTSIZ
|
|
C PARM INTVAL
|
|
C PARM PUBAUT
|
|
C PARM TEXT
|
|
C PARM REPLAC
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C* Get a list of all objects in the QGPL library.
|
|
C*
|
|
C CALL 'QUSLOBJ'
|
|
C PARM USERSP
|
|
C PARM FORMAT
|
|
C PARM OBJECT
|
|
C PARM OBJTYP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C* Look at the generic header.
|
|
C* The generic header contains information
|
|
C* about the list data section that is needed when processing
|
|
C* the entries.
|
|
C*
|
|
C CALL 'QUSRTVUS'
|
|
C PARM USERSP
|
|
C PARM STRPOS
|
|
C PARM LENDTA
|
|
C PARM QUSBP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C* Check the information status field, QUSBPJ, to see if
|
|
C* the API was able to return all the information.
|
|
C* Possible values are:
|
|
C* C -- Complete and accurate
|
|
C* P -- Partial but accurate
|
|
C* I -- Incomplete
|
|
C*
|
|
C QUSBPJ IFEQ 'C'
|
|
C QUSBPJ OREQ 'P'
|
|
C*
|
|
C* Check to see if any entries were put into the user space.
|
|
C*
|
|
C QUSBPS IFGT 0
|
|
C Z-ADD1 COUNT
|
|
C Z-ADDQUSBPQ STRPOS <span class="uicontrol" id="pgmerr_offusrs__SPTRK18A"><a name="pgmerr_offusrs__SPTRK18A"><!-- --></a>(1)</span>
|
|
C Z-ADD30 LENDTA
|
|
C* Walk through all the entries in the user space.
|
|
C COUNT DOWLEQUSBPS
|
|
C CALL 'QUSRTVUS'
|
|
C PARM USERSP
|
|
C PARM STRPOS
|
|
C PARM LENDTA
|
|
C PARM QUSDM
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C*
|
|
C* Process the objects.
|
|
C*
|
|
C ADD 1 COUNT
|
|
C ADD QUSBPT STRPOS
|
|
C ENDDO
|
|
C ENDIF
|
|
C*
|
|
C* Information in the user space is not accurate
|
|
C*
|
|
C ENDIF
|
|
C*
|
|
C* Delete the user space called APIUG1 in library QGPL.
|
|
C*
|
|
C CALL 'QUSDLTUS'
|
|
C PARM USERSP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C SETON LR
|
|
C RETRN
|
|
C*
|
|
C* End of MAINLINE
|
|
C*
|
|
C* Subroutine to handle errors returned in the error code
|
|
C* parameter.
|
|
C*
|
|
C ERRCOD BEGSR
|
|
C QUSBNC IFGT 0
|
|
C*
|
|
C* Process errors returned from the API.
|
|
C*
|
|
C END
|
|
C ENDSR</pre>
|
|
</div>
|
|
<div class="section" id="pgmerr_offusrs__offusrs_correct"><a name="pgmerr_offusrs__offusrs_correct"><!-- --></a><h4 class="sectiontitle">Example: Use offsets in a user space
|
|
of correct coding</h4><p>The following example program has code in it that
|
|
compensates for the API offset convention of that starts at 0. The code adds
|
|
1 to the starting position (STRPOS) offset. This is shown at <a href="#pgmerr_offusrs__SPTRK19B">(2)</a>.</p>
|
|
<pre>I*
|
|
I*Program Name: APIUG2
|
|
I*
|
|
I*Programming Language: RPG
|
|
I*
|
|
I*Description: This sample program illustrates the correct
|
|
I* way of using offsets in user space.
|
|
I*
|
|
I*Header Files Included: QUSGEN - Generic Header of a User Space
|
|
I* QUSEC - Error Code Parameter
|
|
I* (Copied into Program)
|
|
I* QUSLOBJ - List Objects API
|
|
I*
|
|
I*APIs Used: QUSCRTUS - Create User Space
|
|
I* QUSLOBJ - List Objects
|
|
I* QUSRTVUS - Retrieve User Space
|
|
I* QUSDLTUS - Delete User Space
|
|
I*****************************************************************
|
|
I*****************************************************************
|
|
I*
|
|
I* Generic Header of a User Space Include
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSGEN
|
|
I*
|
|
I* Error Code Parameter Include for the APIs
|
|
I*
|
|
I* The following QUSEC include is copied into this program
|
|
I* so that the variable length field can be defined as a
|
|
I* fixed length.
|
|
I*
|
|
I*** START HEADER FILE SPECIFICATIONS ****************************
|
|
I*
|
|
I*Header File Name: H/QUSEC
|
|
I*
|
|
I*Descriptive Name: Error Code Parameter.
|
|
I*
|
|
I*5763-SS1 (C) Copyright IBM Corp. 1994,1994
|
|
I*All rights reserved.
|
|
I*US Government Users Restricted Rights -
|
|
I*Use, duplication or disclosure restricted
|
|
I*by GSA ADP Schedule Contract with IBM Corp.
|
|
I*
|
|
I*Licensed Materials-Property of IBM
|
|
I*
|
|
I*
|
|
I*Description: Include header file for the error code parameter.
|
|
I*
|
|
I*Header Files Included: None.
|
|
I*
|
|
I*Macros List: None.
|
|
I*
|
|
I*Structure List: Qus_EC_t
|
|
I*
|
|
I*Function Prototype List: None.
|
|
I*
|
|
I*Change Activity:
|
|
I*
|
|
I*CFD List:
|
|
I*
|
|
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
|
|
I*---- ------------ ----- ------ --------- ----------------------
|
|
I*$A0= D2862000 3D10 931201 DPOHLSON: New Include
|
|
I*
|
|
I*End CFD List.
|
|
I*
|
|
I*Additional notes about the Change Activity
|
|
I*End Change Activity.
|
|
I*** END HEADER FILE SPECIFICATIONS ******************************
|
|
I*****************************************************************
|
|
I*Record structure for Error Code Parameter
|
|
I**** ***
|
|
I*NOTE: The following type definition only defines the corrected
|
|
I* portion of the format. Varying length field Exception
|
|
I* Data will not be defined here.
|
|
I*****************************************************************
|
|
IQUSBN DS
|
|
I* Qus EC
|
|
I B 1 40QUSBNB
|
|
I* Bytes Provided
|
|
I B 5 80QUSBNC
|
|
I* Bytes Available
|
|
I 9 15 QUSBND
|
|
I* Exception Id
|
|
I 16 16 QUSBNF
|
|
I* Reserved
|
|
I* 17 17 QUSBNG
|
|
I*
|
|
I* Varying length
|
|
I 17 100 QUSBNG
|
|
I*
|
|
I* List Objects API Include
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
|
|
I*
|
|
I* Qualified User Space Data Structure
|
|
I*
|
|
IUSERSP DS
|
|
I I 'APIUG1 ' 1 10 USRSPC
|
|
I I 'QGPL ' 11 20 SPCLIB
|
|
I* Qualified Object Name Data Structure
|
|
IOBJECT DS
|
|
I I '*ALL ' 1 10 OBJNAM
|
|
I I 'QGPL ' 11 20 OBJLIB
|
|
I*
|
|
I* Miscellaneous Data Structure
|
|
I*
|
|
I DS
|
|
I* Set up parameters for the Create User Space API
|
|
I I 'TESTUSRSPC' 1 10 EXTATR
|
|
I I X'00' 11 11 INTVAL
|
|
I 12 12 RSVD1
|
|
I I 256 B 13 160INTSIZ
|
|
I I '*USE ' 17 26 PUBAUT
|
|
I I 'TEXT DESCRIPTION - 27 76 TEXT
|
|
I 'FOR USER SPACE -
|
|
I 'CALLED APIUG2 '
|
|
I I '*YES ' 77 87 REPLAC
|
|
I* Set up parameters for the List Objects API
|
|
I I 'OBJL0100' 88 95 FORMAT
|
|
I I '*ALL ' 96 105 OBJTYP
|
|
I 106 108 RSVD2
|
|
I* Set up parameters for the Retrieve User Space API
|
|
I I 1 B 109 1120STRPOS
|
|
I I 192 B 113 1160LENDTA
|
|
I B 117 1200COUNT
|
|
C*
|
|
C* Create a user space called APIUG1 in library QGPL.
|
|
C*
|
|
C Z-ADD100 QUSBNB
|
|
C CALL 'QUSCRTUS'
|
|
C PARM USERSP
|
|
C PARM EXTATR
|
|
C PARM INTSIZ
|
|
C PARM INTVAL
|
|
C PARM PUBAUT
|
|
C PARM TEXT
|
|
C PARM REPLAC
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C* Get a list of all objects in the QGPL library.
|
|
C*
|
|
C CALL 'QUSLOBJ'
|
|
C PARM USERSP
|
|
C PARM FORMAT
|
|
C PARM OBJECT
|
|
C PARM OBJTYP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C* Look at the generic header. This contains information
|
|
C* about the list data section that is needed when processing
|
|
C* the entries.
|
|
C*
|
|
C CALL 'QUSRTVUS'
|
|
C PARM USERSP
|
|
C PARM STRPOS
|
|
C PARM LENDTA
|
|
C PARM QUSBP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C*
|
|
C* Check the information status field, QUSBPJ, to see if the
|
|
C* API was able to return all the information. Possible values
|
|
C* are: C -- Complete and accurate
|
|
C* P -- Partial but accurate
|
|
C* I -- Incomplete.
|
|
C*
|
|
C QUSBPJ IFEQ 'C'
|
|
C QUSBPJ OREQ 'P'
|
|
C*
|
|
C* Check to see if any entries were put into the user space.
|
|
C*
|
|
C QUSBPS IFGT 0
|
|
C Z-ADD1 COUNT
|
|
C* Because RPG is Base 1, the offset must be increased by one.
|
|
C*
|
|
C QUSBPQ ADD 1 STRPOS <span class="uicontrol" id="pgmerr_offusrs__SPTRK19B"><a name="pgmerr_offusrs__SPTRK19B"><!-- --></a>(2)</span>
|
|
C Z-ADD30 LENDTA
|
|
C* Walk through all the entries in the user space.
|
|
C COUNT DOWLEQUSBPS
|
|
C CALL 'QUSRTVUS'
|
|
C PARM USERSP
|
|
C PARM STRPOS
|
|
C PARM LENDTA
|
|
C PARM QUSDM
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C*
|
|
C* Process the objects.
|
|
C*
|
|
C ADD 1 COUNT
|
|
C ADD QUSBPT STRPOS
|
|
C ENDDO
|
|
C ENDIF
|
|
C*
|
|
C* Information in the user space is not accurate.
|
|
C*
|
|
C ENDIF
|
|
C*
|
|
C*
|
|
C* Delete the user space called APIUG1 in library QGPL.
|
|
C*
|
|
C CALL 'QUSDLTUS'
|
|
C PARM USERSP
|
|
C PARM QUSBN
|
|
C* See if any errors were returned in the error code parameter.
|
|
C EXSR ERRCOD
|
|
C*
|
|
C SETON LR
|
|
C RETRN
|
|
C*
|
|
C* End of MAINLINE
|
|
C*
|
|
C* Subroutine to handle errors returned in the error code
|
|
C* parameter.
|
|
C*
|
|
C ERRCOD BEGSR
|
|
C QUSBNC IFGT 0
|
|
C*
|
|
C* Process errors returned from the API.
|
|
C*
|
|
C END
|
|
C ENDSR</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>
|
|
</body>
|
|
</html> |