OPM RPG 中的示例: 将密钥与 "列表假脱机文件" (QUSLSPL) API 配合使用
此 OPM RPG 程序处理使用键指定的假脱机文件信息的列表。
此示例引入了名为 LSTSPL 的程序。 程序 LSTSPL 使用 "列示假脱机文件" (QUSLSPL) API 来确定由 LSTSPL 程序的当前用户创建的所有假脱机文件的假脱机文件名，创建日期和页数。
与先前的 JOBDAPI 程序示例不同，当我们只对 HOLD 字段感兴趣时， "检索作业描述" (QWDRJOBD) API 的格式 JOBD0100 返回了数十个字段， QUSLSPL API 提供了一个键控接口，允许 LSTSPL 请求仅返回相关字段 (假脱机文件名，创建日期和页数)。
除了提供键控接口外， QUSLSPL 还与 QWDRJOBD 不同，因为 QUSLSPL API 将所有假脱机文件的列表检索到用户空间 (*USRSPC) 中，而 QWDRJOBD 将有关一个特定作业描述的信息检索到程序变量中。
在以下程序示例中，所有片段已与访问与假脱机文件相关的特定信息的 OPM RPG 程序放在一起。 将创建列出此信息的报告。 程序示例不处理与 API 相关的错误。 接收到的任何错误都将作为异常消息返回，如 1中所示。
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 (11)
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 (7)
I I 201 B 1 40KEY1
I I 216 B 5 80KEY2
I I 211 B 9 120KEY3 (8)
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 (1)
C*
C* Create the User Space to hold the QUSLSPL API results
C*
C CALL 'QUSCRTUS' (2)
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' (3)
C PARM SPCNAM
C PARM 'SPLF0200'FORMAT 8 (4)
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 (5)
C PARM 3 KEY# (6)
C*
C* Retrieve information concerning the User Space and its contents
C*
C CALL 'QUSRTVUS' (9)
C PARM SPCNAM
C PARM 1 START Start Rtv at 1
C PARM 192 LENDTA for length =192
C PARM QUSBP (10)
C PARM QUSBN
C*
C* Check User Space status for good information
C*
C QUSBPD IFEQ '0100' (12) Header Fmt
C QUSBPJ IFEQ 'C' (14) 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 (16)
C*
C* Keep count of how many list entries we have processed
C*
C Z-ADD0 COUNT 90 (17)
C*
C* Adjust Offset value to Position value
C*
C QUSBPQ ADD 1 START (18)
C*
C* Retrieve the lesser of allocated storage or available data
C*
C QUSBPT IFLT 1000 (19)
C Z-ADDQUSBPT LENDTA
C ELSE
C Z-ADD1000 LENDTA
C ENDIF
C*
C* Process all entries returned
C*
C COUNT DOWLTQUSBPS (20)
C*
C* Retrieve spooled file information
C*
C CALL 'QUSRTVUS' (21)
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 (22)
C Z-ADD5 X 40
C DO QUSFVB (23)
C*
C* Get header information
C*
C 16 SUBSTRECVR:X QUSKR (24)
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 (25)
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 (26)
C*
C* Adjust START to address next entry
C*
C ADD 1 COUNT (27)
C ADD QUSBPT START
C ENDDO
C ENDIF
C ELSE (15)
C EXCPTLSTERR
C ENDIF
C ELSE (13)
C EXCPTHDRERR
C ENDIF
C MOVE '1' *INLR (28)
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'
列表 API 不会自动创建用于接收列表的用户空间 (*USRSPC)。 必须首先使用 "创建用户空间" (QUSCRTUS) API (2)创建一个用户空间。 与 CL 创建命令类似， QUSCRTUS API 具有多个参数，用于标识对象的名称，公共权限，对象描述文本等。
创建用户空间后，可以调用 QUSLSPL API 以将假脱机文件信息返回到用户空间 (3)中。 QUSLSPL API 支持两种格式: SPLF0100(返回有关每个所选假脱机文件的一组固定信息) 和 SPLF0200(仅返回用户选择的字段)。 LSTSPL 使用 SPLF0200 (4) 并将密钥列表传递到 QUSLSPL API ，以标识所选字段 (5) 和密钥数 (6)。 由于 OPM RPG 不支持二进制值的数组 (列表) ，因此 LSTSPL 将键数组 (KEYARA) 定义为由连续二进制 (4) 字段 (7)组成的数据结构。 这些字段初始化为 201,216 和 211 ，分别对应于名为假脱机文件名，打开日期文件和总页数的键 (8)。 请注意，虽然创建的用户空间初始大小为 2000 字节 (2)，但大多数 List API 隐式扩展用户空间 (最多 16MB) 以返回所有可用列表条目。 当用户空间过大时，反向截断不是由列表 API 执行的。
生成列表后，现在可以处理用户空间数据。
列表 API (如 QUSLSPL) 通常在用户空间的开头提供类属列表头，它提供诸如创建列表的 API ，列表中的项数 (此示例的假脱机文件) ，每个项的大小等信息。 要访问通用列表头，请使用 "检索用户空间" (QUSRTVUS) API (9)。 程序 LSTSPL 将通用列表头检索到数据结构 QUSBP (10)中，该数据结构是在 QUSGEN QSYSINC /COPY (include) 文件 (11)中定义的。 请注意，支持指针的语言 (例如 ILE RPG ， COBOL 和 C) 可以通过使用 "检索指针到用户空间" (QUSPTRUS) 来避免调用 QUSRTVUS (以及由此产生的数据移动) API。
现在，程序 LSTSPL 将检查通用列表头的格式是否为期望的 (12)格式，如果没有，将打印错误行 (13)。 验证了头格式后， LSTSPL 现在会检查列表 (14) 的信息状态 (如果不准确，将打印错误行 (15)) ，并且至少有一个列表条目可用 (16)。
在确定准确的列表条目可用后，程序 LSTSPL 将执行以下操作:
- 初始化 COUNT 变量以跟踪已处理的条目数 (17)。
- 将 1 添加到基本 0 偏移量 (到列表中的第一个条目) ，因为 QUSRTVUS API 采用基本 1 位置值 (18)。
- 确定与每个条目 (19) 关联的数据量 (这是分配给接收列表条目的存储量或列表条目的大小中的较小者)。
- 进入 DO 循环以处理所有可用列表条目 (20)。
在此循环中， LSTSPL 检索每个列表条目 (21)，抽取返回的字段数 (22)，并进入内部 DO 循环以处理所有可用列表条目字段 (23)。
在此内部循环中，程序抽取字段信息 (24) ，并基于关键字段 (25)处理字段数据。
处理给定列表条目的所有字段后， LSTSPL 将生成打印行 (26) 并继续到下一个列表条目 (27)。
处理完所有列表条目后， LSTSPL 结束 (28)。