380 lines
21 KiB
HTML
380 lines
21 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 OPM RPG: Using keys with List Spooled Files API" />
|
|
<meta name="abstract" content="This example shows the steps necessary to process keyed output from an API." />
|
|
<meta name="description" content="This example shows the steps necessary to process keyed output from an API." />
|
|
<meta name="DC.Relation" scheme="URI" content="opmScenario.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="conReceiver.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="usf.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="listOverview.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysCOBOL.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysILEC.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysILERPG.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysCOBOL.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysILEC.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysILERPG.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="cmnKeysRPG" />
|
|
<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 OPM RPG: Using keys with List Spooled Files API</title>
|
|
</head>
|
|
<body id="cmnKeysRPG"><a name="cmnKeysRPG"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Example in OPM RPG: Using keys with List Spooled Files API</h1>
|
|
<div><p>This example shows the steps necessary to process
|
|
keyed output from an API.</p>
|
|
<div class="section"><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>
|
|
<p>This section introduces a new program named LSTSPL.
|
|
Program LSTSPL uses the List Spooled Files (QUSLSPL) API to determine the
|
|
spooled file name, date created, and number of pages for all spooled files
|
|
created by the current user of the LSTSPL program. Unlike the earlier JOBDAPI
|
|
program examples, where format JOBD0100 of the Retrieve Job Description (QWDRJOBD)
|
|
API returned dozens of fields while we were only interested in the HOLD field,
|
|
the QUSLSPL API provides a keyed interface that allows LSTSPL to request that
|
|
only the relevant fields (spooled file name, date created, and number of pages)
|
|
be returned. In addition to providing a keyed interface, QUSLSPL also differs
|
|
from QWDRJOBD in that the QUSLSPL API retrieves a list of all spooled files
|
|
into a User Space (*USRSPC) while QWDRJOBD retrieves information about one
|
|
specific job description into a program variable.</p>
|
|
<p>In the following program
|
|
example, all the pieces have been put together with an OPM RPG program that
|
|
accesses specific information related to spooled files. A report listing this
|
|
information is created. The program example does not handle API-related errors.
|
|
Any errors that are received are returned as exception messages, as shown
|
|
at <a href="#cmnKeysRPG__NUMBERONE">1</a>.</p>
|
|
<pre>
|
|
F***************************************************************
|
|
F*
|
|
F* Program Name: LSTSPL
|
|
F*
|
|
F* Program Language: OPM RPG
|
|
F*
|
|
F* Descriptive Name: List Spooled Files for Current User
|
|
F*
|
|
F* Description: This example shows the steps necessary
|
|
F* to process keyed output from an API.
|
|
F*
|
|
F* Header Files Included: QUSEC - Error Code Parameter
|
|
F* QUSGEN - User Space Generic Header
|
|
F* QUSLSPL - List Spooled Files
|
|
F*
|
|
F* APIs Used: QUSLSPL - List Spooled Files
|
|
F* QUSCRTUS - Create User Space
|
|
F* QUSRTVUS - Retrieve User Space
|
|
F*
|
|
F***************************************************************
|
|
FQSYSPRT O F 132 OF PRINTER
|
|
I*
|
|
I* Copy User Space Generic Header
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSGEN <span class="uicontrol" id="cmnKeysRPG__num11"><a name="cmnKeysRPG__num11"><!-- --></a>(11)</span>
|
|
I*
|
|
I* Copy API Error Code parameter
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSEC
|
|
I*
|
|
I* Copy List Spooled Files API include
|
|
I*
|
|
I/COPY QSYSINC/QRPGSRC,QUSLSPL
|
|
I*
|
|
I* Data structure to hold space name
|
|
I*
|
|
ISPCNAM DS
|
|
I I 'SPCNAME ' 1 10 SPC
|
|
I I 'QTEMP ' 11 20 LIB
|
|
I*
|
|
I* Data structure to hold requested key values
|
|
I*
|
|
IKEYARA DS <span class="uicontrol" id="cmnKeysRPG__num7"><a name="cmnKeysRPG__num7"><!-- --></a>(7)</span>
|
|
I I 201 B 1 40KEY1
|
|
I I 216 B 5 80KEY2
|
|
I I 211 B 9 120KEY3 <span class="uicontrol" id="cmnKeysRPG__num8"><a name="cmnKeysRPG__num8"><!-- --></a>(8)</span>
|
|
I*
|
|
I* Receiver variable for QUSRTVUS
|
|
I*
|
|
IRECVR DS 1000
|
|
I*
|
|
I* Other assorted variables
|
|
I*
|
|
I DS
|
|
I B 1 40SIZ
|
|
I B 5 80START
|
|
I B 9 120LENDTA
|
|
I B 13 160KEY#
|
|
I B 17 200PAGES#
|
|
I 17 20 PAGESA
|
|
I I X'00' 21 21 INTVAL
|
|
C*
|
|
C* Initialize Error Code structure to accept exceptions
|
|
C*
|
|
C Z-ADD0 QUSBNB <span class="uicontrol" id="cmnKeysRPG__NUMBERONE"><a name="cmnKeysRPG__NUMBERONE"><!-- --></a>(1)</span>
|
|
C*
|
|
C* Create the User Space to hold the QUSLSPL API results
|
|
C*
|
|
C CALL 'QUSCRTUS' <span class="uicontrol" id="cmnKeysRPG__num2"><a name="cmnKeysRPG__num2"><!-- --></a>(2)</span>
|
|
C PARM SPCNAM
|
|
C PARM 'quslspl' EXTATR 10
|
|
C PARM 2000 SIZ
|
|
C PARM INTVAL
|
|
C PARM '*ALL' PUBAUT 10
|
|
C PARM TXTDSC 50
|
|
C PARM '*YES' REPLAC 10
|
|
C PARM QUSBN
|
|
C*
|
|
C* Call QUSLSPL to get all spooled files for *CURRENT user
|
|
C*
|
|
C CALL 'QUSLSPL' <span class="uicontrol" id="cmnKeysRPG__num3"><a name="cmnKeysRPG__num3"><!-- --></a>(3)</span>
|
|
C PARM SPCNAM
|
|
C PARM 'SPLF0200'FORMAT 8 <span class="uicontrol" id="cmnKeysRPG__num4"><a name="cmnKeysRPG__num4"><!-- --></a>(4)</span>
|
|
C PARM '*CURRENT'USRNAM 10
|
|
C PARM '*ALL' OUTQ 20
|
|
C PARM '*ALL' FRMTYP 10
|
|
C PARM '*ALL' USRDTA 10
|
|
C PARM QUSBN
|
|
C PARM JOBNAM 26
|
|
C PARM KEYARA <span class="uicontrol" id="cmnKeysRPG__num5"><a name="cmnKeysRPG__num5"><!-- --></a>(5)</span>
|
|
C PARM 3 KEY# <span class="uicontrol" id="cmnKeysRPG__num6"><a name="cmnKeysRPG__num6"><!-- --></a>(6)</span>
|
|
C*
|
|
C* Retrieve information concerning the User Space and its contents
|
|
C*
|
|
C CALL 'QUSRTVUS' <span class="uicontrol" id="cmnKeysRPG__num9"><a name="cmnKeysRPG__num9"><!-- --></a>(9)</span>
|
|
C PARM SPCNAM
|
|
C PARM 1 START Start Rtv at 1
|
|
C PARM 192 LENDTA for length =192
|
|
C PARM QUSBP <span class="uicontrol" id="cmnKeysRPG__num10"><a name="cmnKeysRPG__num10"><!-- --></a>(10)</span>
|
|
C PARM QUSBN
|
|
C*
|
|
C* Check User Space status for good information
|
|
C*
|
|
C QUSBPD IFEQ '0100' <span class="uicontrol" id="cmnKeysRPG__num12"><a name="cmnKeysRPG__num12"><!-- --></a>(12)</span> Header Fmt
|
|
C QUSBPJ IFEQ 'C' <span class="uicontrol" id="cmnKeysRPG__num14"><a name="cmnKeysRPG__num14"><!-- --></a>(14)</span> Complete
|
|
C QUSBPJ OREQ 'P' or Partial
|
|
C*
|
|
C* Check to see if any entries were put into User Space
|
|
C*
|
|
C QUSBPS IFGT 0 <span class="uicontrol" id="cmnKeysRPG__num16"><a name="cmnKeysRPG__num16"><!-- --></a>(16)</span>
|
|
C*
|
|
C* Keep count of how many list entries we have processed
|
|
C*
|
|
C Z-ADD0 COUNT 90 <span class="uicontrol" id="cmnKeysRPG__num17"><a name="cmnKeysRPG__num17"><!-- --></a>(17)</span>
|
|
C*
|
|
C* Adjust Offset value to Position value
|
|
C*
|
|
C QUSBPQ ADD 1 START <span class="uicontrol" id="cmnKeysRPG__num18"><a name="cmnKeysRPG__num18"><!-- --></a>(18)</span>
|
|
C*
|
|
C* Retrieve the lesser of allocated storage or available data
|
|
C*
|
|
C QUSBPT IFLT 1000 <span class="uicontrol" id="cmnKeysRPG__num19"><a name="cmnKeysRPG__num19"><!-- --></a>(19)</span>
|
|
C Z-ADDQUSBPT LENDTA
|
|
C ELSE
|
|
C Z-ADD1000 LENDTA
|
|
C ENDIF
|
|
C*
|
|
C* Process all entries returned
|
|
C*
|
|
C COUNT DOWLTQUSBPS <span class="uicontrol" id="cmnKeysRPG__num20"><a name="cmnKeysRPG__num20"><!-- --></a>(20)</span>
|
|
C*
|
|
C* Retrieve spooled file information
|
|
C*
|
|
C CALL 'QUSRTVUS' <span class="uicontrol" id="cmnKeysRPG__num21"><a name="cmnKeysRPG__num21"><!-- --></a>(21)</span>
|
|
C PARM SPCNAM
|
|
C PARM START
|
|
C PARM LENDTA
|
|
C PARM RECVR
|
|
C PARM QUSBN
|
|
C*
|
|
C* Loop through returned fields
|
|
C*
|
|
C 4 SUBSTRECVR QUSFV <span class="uicontrol" id="cmnKeysRPG__num22"><a name="cmnKeysRPG__num22"><!-- --></a>(22)</span>
|
|
C Z-ADD5 X 40
|
|
C DO QUSFVB <span class="uicontrol" id="cmnKeysRPG__num23"><a name="cmnKeysRPG__num23"><!-- --></a>(23)</span>
|
|
C*
|
|
C* Get header information
|
|
C*
|
|
C 16 SUBSTRECVR:X QUSKR <span class="uicontrol" id="cmnKeysRPG__num24"><a name="cmnKeysRPG__num24"><!-- --></a>(24)</span>
|
|
C*
|
|
C* Set Y to location of actual data associated with key
|
|
C*
|
|
C X ADD 16 Y 40
|
|
C*
|
|
C* Process the data based on key type
|
|
C*
|
|
C QUSKRC CASEQ201 FILNAM <span class="uicontrol" id="cmnKeysRPG__num25"><a name="cmnKeysRPG__num25"><!-- --></a>(25)</span>
|
|
C QUSKRC CASEQ211 PAGES
|
|
C QUSKRC CASEQ216 AGE
|
|
C CAS ERROR
|
|
C END
|
|
C*
|
|
C* Adjust X to address next keyed record returned
|
|
C*
|
|
C ADD QUSKRB X
|
|
C ENDDO
|
|
C*
|
|
C* Output information on spooled file
|
|
C*
|
|
C EXCPTPRTLIN <span class="uicontrol" id="cmnKeysRPG__num26"><a name="cmnKeysRPG__num26"><!-- --></a>(26)</span>
|
|
C*
|
|
C* Adjust START to address next entry
|
|
C*
|
|
C ADD 1 COUNT <span class="uicontrol" id="cmnKeysRPG__num27"><a name="cmnKeysRPG__num27"><!-- --></a>(27)</span>
|
|
C ADD QUSBPT START
|
|
C ENDDO
|
|
C ENDIF
|
|
C ELSE <span class="uicontrol" id="cmnKeysRPG__num15"><a name="cmnKeysRPG__num15"><!-- --></a>(15)</span>
|
|
C EXCPTLSTERR
|
|
C ENDIF
|
|
C ELSE <span class="uicontrol" id="cmnKeysRPG__num13"><a name="cmnKeysRPG__num13"><!-- --></a>(13)</span>
|
|
C EXCPTHDRERR
|
|
C ENDIF
|
|
C MOVE '1' *INLR <span class="uicontrol" id="cmnKeysRPG__num28"><a name="cmnKeysRPG__num28"><!-- --></a>(28)</span>
|
|
C RETRN
|
|
C*
|
|
C* Various subroutines
|
|
C*
|
|
C***************************************************************
|
|
C FILNAM BEGSR
|
|
C*
|
|
C* Extract spooled file name for report
|
|
C*
|
|
C MOVE *BLANKS PRTFIL 10
|
|
C QUSKRG SUBSTRECVR:Y PRTFIL
|
|
C ENDSR
|
|
C***************************************************************
|
|
C PAGES BEGSR
|
|
C*
|
|
C* Extract number of pages for report
|
|
C*
|
|
C QUSKRG SUBSTRECVR:Y PAGESA
|
|
C ENDSR
|
|
C***************************************************************
|
|
C AGE BEGSR
|
|
C*
|
|
C* Extract age of spooled file for report
|
|
C*
|
|
C MOVE *BLANKS OPNDAT 7
|
|
C QUSKRG SUBSTRECVR:Y OPNDAT
|
|
C ENDSR
|
|
C***************************************************************
|
|
C ERROR BEGSR
|
|
C*
|
|
C* If unknown key value, then display the value and end
|
|
C*
|
|
C DSPLY QUSKRC
|
|
C MOVE '1' *INLR
|
|
C RETRN
|
|
C ENDSR
|
|
O*
|
|
OQSYSPRT E PRTLIN
|
|
O PRTFIL 10
|
|
O PAGES# 25
|
|
O OPNDAT 40
|
|
OQSYSPRT E LSTERR
|
|
O 22 'List data not valid '
|
|
OQSYSPRT E HDRERR
|
|
O 22 'Unknown Generic Header'
|
|
|
|
</pre>
|
|
<p>List APIs do not automatically create the user space (*USRSPC)
|
|
to receive the list. You must first create one using the Create User Space
|
|
(QUSCRTUS) API <a href="#cmnKeysRPG__num2">(2)</a>. Similar to CL create
|
|
commands, the QUSCRTUS API has several parameters that identify the name of
|
|
the object, the public authority, the object description text, and so forth.</p>
|
|
<p>After
|
|
creating the user space, you can call the QUSLSPL API to return spooled file
|
|
information into the user space <a href="#cmnKeysRPG__num3">(3)</a>.
|
|
The QUSLSPL API supports two formats: SPLF0100, which returns a fixed set
|
|
of information about each selected spooled file, and SPLF0200, which returns
|
|
only user-selected fields. LSTSPL uses SPLF0200 <a href="#cmnKeysRPG__num4">(4)</a> and
|
|
passes to the QUSLSPL API a list of keys to identify the selected fields <a href="#cmnKeysRPG__num5">(5)</a> and the number of keys <a href="#cmnKeysRPG__num6">(6)</a>.
|
|
Because OPM RPG does not support an array (list) of binary values, LSTSPL
|
|
defines the key array (KEYARA) as a data structure comprised of contiguous
|
|
binary(4) fields <a href="#cmnKeysRPG__num7">(7)</a>. The fields are
|
|
initialized to 201, 216, and 211, which correspond to the keys named spooled
|
|
file name, date file was opened, and total pages, respectively <a href="#cmnKeysRPG__num8">(8)</a>.
|
|
Note that while the user space was created with an initial size of 2000 bytes <a href="#cmnKeysRPG__num2">(2)</a>, most List APIs implicitly extend the user
|
|
space (up to a maximum of 16MB) in order to return all available list entries.
|
|
The reverse, truncation when the user space is too large, is not performed
|
|
by list APIs.</p>
|
|
<p>Having generated the list, you can now process the user
|
|
space data.</p>
|
|
<p>List APIs (like QUSLSPL) generally provide a generic list
|
|
header at the beginning of the user space, which provides information such
|
|
as the API that created the list, the number of entries (spooled files for
|
|
this example) in the list, the size of each entry, and so on. See User spaces
|
|
for further information. To access the generic list header, use the Retrieve
|
|
User Space (QUSRTVUS) API <a href="#cmnKeysRPG__num9">(9)</a>. Program
|
|
LSTSPL retrieves the generic list header into the data structure QUSBP <a href="#cmnKeysRPG__num10">(10)</a>, which is defined in the QUSGEN QSYSINC
|
|
/COPY (include) file <a href="#cmnKeysRPG__num11">(11)</a>. Note that
|
|
languages, such as ILE RPG, COBOL, and C, which support pointers, can avoid
|
|
this call to QUSRTVUS (and the resulting movement of data) by using the Retrieve
|
|
Pointer to User Space (QUSPTRUS) API. See Examples: List Object API for examples.</p>
|
|
<p>Program
|
|
LSTSPL now checks that the format of the generic list header is the one expected <a href="#cmnKeysRPG__num12">(12)</a>, and if not, prints an error line <a href="#cmnKeysRPG__num13">(13)</a>. Having verified the header format, LSTSPL
|
|
now checks the information status of the list <a href="#cmnKeysRPG__num14">(14)</a> (and
|
|
if it is not accurate, prints an error line <a href="#cmnKeysRPG__num15">(15)</a>)
|
|
and that at least one list entry is available <a href="#cmnKeysRPG__num16">(16)</a>.</p>
|
|
<p>Having
|
|
determined that accurate list entries are available, LSTSPL does the following:</p>
|
|
<ul><li>Initializes the COUNT variable to keep track of how many entries have
|
|
been processed <a href="#cmnKeysRPG__num17">(17)</a></li>
|
|
<li>Adds one to the base 0 offset (to the first entry in the list) as the
|
|
QUSRTVUS API assumes base 1 positional values <a href="#cmnKeysRPG__num18">(18)</a> </li>
|
|
<li>Determines how much data is associated with each entry <a href="#cmnKeysRPG__num19">(19)</a> (which
|
|
is the lesser of either the amount of storage you allocated to receive a list
|
|
entry, or the size of a list entry) </li>
|
|
<li>Falls into a DO loop to process all of the available list entries <a href="#cmnKeysRPG__num20">(20)</a></li>
|
|
</ul>
|
|
<p>Within this loop, LSTSPL retrieves each list entry <a href="#cmnKeysRPG__num21">(21)</a>,
|
|
extracts the number of fields returned <a href="#cmnKeysRPG__num22">(22)</a>,
|
|
and enters an inner DO loop to process all of the available list entry fields <a href="#cmnKeysRPG__num23">(23)</a>.</p>
|
|
<p>Within this inner loop, the program
|
|
extracts the field information <a href="#cmnKeysRPG__num24">(24)</a> and
|
|
processes the field data based on the key field <a href="#cmnKeysRPG__num25">(25)</a>.</p>
|
|
<p>When
|
|
all fields for a given list entry have been processed, LSTSPL generates a
|
|
print line <a href="#cmnKeysRPG__num26">(26)</a> and proceeds to the
|
|
next list entry <a href="#cmnKeysRPG__num27">(27)</a>.</p>
|
|
<p>When all
|
|
the list entries have been processed, LSTSPL ends <a href="#cmnKeysRPG__num28">(28)</a>.</p>
|
|
<p>See
|
|
the following for the same example in different languages:</p>
|
|
<ul><li>COBOL and ILE COBOL</li>
|
|
<li>ILE C</li>
|
|
<li>ILE RPG</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="opmScenario.htm" title="This scenario demonstrates the use of an original program model (OPM) API in several different programs.">Scenario: Original Program Model (OPM) API</a></div>
|
|
</div>
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
|
<div><a href="conReceiver.htm" title="A receiver variable is a program variable that is used as an output field to contain information that is returned from an API.">Receiver variables</a></div>
|
|
<div><a href="listOverview.htm" title="List APIs return a list unique to a given API. The section discusses the characteristics of a list API and provides information that you should be aware of when you use list APIs.">List APIs overview</a></div>
|
|
</div>
|
|
<div class="relref"><strong>Related reference</strong><br />
|
|
<div><a href="usf.htm" title="List APIs require a user space for returning information. A user space is an object consisting of a collection of bytes that can be used for storing any user-defined information.">User spaces</a></div>
|
|
<div><a href="cmnKeysCOBOL.htm" title="This example shows the steps necessary to process keyed output from an API.">Example in ILE COBOL: Using keys with List Spooled Files API</a></div>
|
|
<div><a href="cmnKeysILEC.htm" title="This example shows the steps necessary to process keyed output from an API">Example in ILE C: Using keys with List Spooled Files API</a></div>
|
|
<div><a href="cmnKeysILERPG.htm" title="This example shows the steps necessary to process keyed output from an API.">Example in ILE RPG: Using keys with List Spooled Files API</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |