If you need to save spooled files with complex text or graphics characteristics, you'll need more power than the standard OS/400 commands provide.
Brief: The system command CPYSPLF can save a spooled file to a database file. However, it saves only text data, not special characteristics such as fonts and graphics. Using the system-provided spooled file APIs, you can create a program to save and restore everything in a spooled file. This article describes the APIs and how to use them, and includes complete utilities to save and restore spooled files with all formatting.
Over the past several years, the capabilities of AS/400 printers have greatly increased. Where there were once only line, matrix and letter-quality printers, there are now also Intelligent Printer Data Stream (IPDS) and Advanced Function Printing (AFP) printers. AS/400 printed output can now include multiple fonts, special printing effects, bar codes and graphics. This versatility enhances our ability to communicate using AS/400 documents, but it creates some special problems when we need to archive them.
At some point, all AS/400 printed output exists as a spooled file. OS/400 provides a variety of commands that can be used to save and restore spooled files but cannot save the special printing effects such as fonts, colors, bar codes and graphics. (See "How and Why to Copy Spooled Files" in this issue).
However, OS/400 provides several system Application Program Interface (API) functions that can save and restore an exact image of a spooled file no matter what it contains. Although using the APIs may seem more complicated than using the OS/400 commands, they eliminate many of the limitations imposed by the Copy Spooled File (CPYSPLF) command. In addition to saving a true image, the APIs run more quickly than the CPYSPLF command and create a smaller object to save.
Using the Utility Programs
In this article, I'll use the APIs to develop two commands, Save Spooled File to User Space (SAVSPLFUS) and Restore Spooled File from User Space (RSTSPLFUS). The SAVSPLFUS command saves a spooled file to a user space. The RSTSPLFUS command restores a spooled file from a user space back to an output queue. (For more information about user spaces see the sidebar, "What is a User Space?" which accompanies this article.) Once the spooled file is copied to a user space, the user space object can be saved like any other object. For example, to archive a spooled file, you can run the SAVSPLFUS command, run the Save Object (SAVOBJ) command to save the user space to tape and then delete the user space from disk. To recreate the saved spooled file, restore the user space (using the Restore Object (RSTOBJ) command) and then run the RSTSPLFUS command to create the spooled file in an output queue.
A short CL command processing program (CPP) and an RPG program are associated with each command. I'll explain how each program works and the APIs it calls in the following sections.
Gathering the Pieces
To write the save and restore spooled file programs, I had to locate information about the APIs. All of the Spooled File APIs, including those I've used in this utility, are documented in the System Programmer's Interface Reference manual. You call API programs like any other program on your system. There are usually several parameters and data structures that are used with the programs. The requirements for each API are documented in the reference manual. The manual indicates that the format of many of the data structures can be found in the QUSRTOOL library. (For more information about QUSRTOOL, see "Tips for Managing the QUSRTOOL Library" and "From the Toolbox" both in this issue.)
The reference manual mentions that the QUSRTOOL product includes a tool called Save and Restore Spooled Files (SAVRSTSPLF), so I started by looking there, only to discover that the programs are written in C/400. I adapted the techniques used in that tool for RPG and they are the basis for the programs in this article.
Overview of the Spooled File APIs
The first step in saving a spooled file image that can be exactly restored is to retrieve the spooled file attributes. These will be stored with the spooled file data and are also needed to calculate the correct size for the user space. The Retrieve Spooled File Attributes (QUSRSPLA) API returns all available attributes for a specific spooled file to a data structure.
Next, a user space with the Create User Space is created (QUSCRTUS) API to contain the copy of the spooled file data. To actually put data in the user space, the spooled file is opened with the Open Spooled File (QSPOPNSP) API. The Get Spooled File Data (QSPGETSP) API then gets data from the spooled file and writes it to the user space. Finally, the Close Spooled File (QSPCLOSP) API closes the spooled file.
At that point, the user space contains the exact image of the spooled file. However, to recreate the spooled file from the user space, we also need the original spooled file attributes. Rather than save the attributes in a file or another user space, the program appends them to the same user space in which the spooled file data is saved. The Retrieve User Space (QUSRTVUS) and Change User Space (QUSCHGUS) APIs are used to add the attribute information to the user space.
Restoring a saved spooled file from a user space is less involved than saving it. The first step is to retrieve the attributes from the user space with the QUSRTVUS API. The Create Spooled File (QSPCRTSP) API is called to create a new spooled file. The Put Spooled File Data (QSPPUTSP) API transfers the data from the user space into the new spooled file. Finally, the QSPCLOSP API closes the spooled file. The spooled file is recreated with all its attributes and data intact. We can work with it using the standard spool and output queue commands, or reprint an exact copy of the original document.
The SAVSPLFUS Command and Program
The Save Spooled File to User Space (SAVSPLFUS) command (see 1) is modeled after the system-provided CPYSPLF command.
The Save Spooled File to User Space (SAVSPLFUS) command (see Figure 1) is modeled after the system-provided CPYSPLF command.
The first three parameters identify the spooled file. Only the FILE parameter is required. The JOB parameter defaults to the current job. The SPLNBR parameter default of *ONLY can be used if the spooled file is the only spooled file within the job with the given file name.
The USRSPC parameter defines the name of the user space created by the program. The default value of *GEN will generate a name in the format UJJJJJJNNN, where "U" is a constant, "JJJJJJ" is the job number and "NNN" is the rightmost three digits of the spooled file number.
The TEXT parameter can contain up to 50 characters of information to be placed in the text description for the user space. The default value of *GEN will cause the qualified job name, spooled file name and number, and the user data to be used for the description. The generated text is right-truncated if necessary.
The CPP for the SAVSPLFUS command is CL program SPLF004CL, shown in 2. The CL program simply receives the parameters from the command, breaks out the qualified job name and user space, then calls RPG program SPLF004RG (3) to save the spooled file. The CL program also handles error messages sent by the RPG program. RPG program SPLF004RG is a series of subroutines that call the APIs.
The CPP for the SAVSPLFUS command is CL program SPLF004CL, shown in Figure 2. The CL program simply receives the parameters from the command, breaks out the qualified job name and user space, then calls RPG program SPLF004RG (Figure 3) to save the spooled file. The CL program also handles error messages sent by the RPG program. RPG program SPLF004RG is a series of subroutines that call the APIs.
The first subroutine, RSPLA, uses the QUSRSPLA API to retrieve the spooled file attributes. The API identifies the spooled file with the job name, spooled file name and number. The attribute data is returned in the receiver variable data structure (RCVVAR). You can change any of the attributes; your changes will be in effect when the spooled file is restored. However, careless changing of attributes may result in a spooled file that is unusable when restored. This command simply saves the attributes and uses them to recreate the spooled file. The RSPLA subroutine also checks to see if the spooled file is open because it cannot be saved correctly until complete attribute information is available. In this case, an error code is set and the program returns.
The next subroutine, CRTUS, creates the user space. The user space name, library name and text for the user space are formatted. The final step before calling the QUSCRTUS API is to calculate the size of the user space. You may wonder why we need to calculate the size, since the manual indicates that the user space is automatically extended by the APIs as data is written to the space. The reason is that we are also going to store the attribute information in the user space, following the spooled file data, and QUSCHGUS will not automatically extend the size of the space. (To see how I determined the size, refer to 4.) After creating the properly sized user space, the program copies the spooled file into it.
The next subroutine, CRTUS, creates the user space. The user space name, library name and text for the user space are formatted. The final step before calling the QUSCRTUS API is to calculate the size of the user space. You may wonder why we need to calculate the size, since the manual indicates that the user space is automatically extended by the APIs as data is written to the space. The reason is that we are also going to store the attribute information in the user space, following the spooled file data, and QUSCHGUS will not automatically extend the size of the space. (To see how I determined the size, refer to Figure 4.) After creating the properly sized user space, the program copies the spooled file into it.
The OPNSP subroutine uses the spooled file identification parameters to open the spooled file. The QSPOPNSP API returns a four-byte binary field which is used as a "handle" by the QSPGETSP API to identify the spooled file.
In the GETSP subroutine, the QSPGETSP API performs the actual transfer of spooled file data from the spooled file to the user space. The program supplies the spooled file handle and the name of the destination user space as parameters for the API. Although the API allows processing of specific buffers in the spooled file, we indicate that we want to process the entire spooled file by putting a value of -1 in the buffer identification field.
After writing the spooled file to the user space, we close it in the CLOSP subroutine. The QSPCLOSP API uses the spooled file handle to identify the spooled file to close.
The image of the spooled file is now in the user space. To complete the process, giving us a single object to save and restore, the program needs to add the spooled file attribute information to the user space. This is done in subroutine SAVAT. Even though we started by getting the attribute information, we could not put it into the front of the user space. The QSPGETSP API puts header information into the first 128 bytes of the user space, followed by the spooled file data. Anything that we put into the first part of the user space is overlaid. That's why we put the spooled file data into the user space first.
But where are we going to add attribute information? The header information written by QSPGETSP includes a field that indicates the number of bytes used to contain the header and the spooled file data. Using this number, we can put the attribute information into the user space starting at the next byte following the spooled file data. To get the number, we use the QUSRTVUS API to retrieve the 128-byte header information into data structure USHDR. The total size of the header plus the spooled file data is found in the size used field (UHSZUS). We simply add 1 to this value before we output the attribute information with the QUSCHGUS API.
The program also needs to record the size and location of the attribute information for use by the RSTSPLFUS command. Fortunately, the first 64 bytes of the header area are reserved for our use-I used the first eight bytes to record the starting position and length of the attribute information. The values for the two fields (UHATSP and UHRLEN) are set, then the QUSCHGUS API is called to change the header information area. We could also record other data, such as the date and time the spooled file was saved, the system it was saved on, and so on.
The user space now contains a complete save of the spooled file with all the information needed to restore an exact copy of it. Standard system save and restore commands can be used on the user space.
The RSTSPLFUS Command and Program
The programming to restore the saved spooled file is much easier than the save programming. We identify the name of the user space, then call the APIs to retrieve the spooled file attributes, create a new spooled file, copy the spooled file data from the user space to the spooled file, then close the spooled file. After running the restore program, the spooled file is in the output queue identified in the saved attributes.
The Restore Spooled file from User Space (RSTSPLFUS) command is shown in 5. There is only one parameter, the qualified name of the user space that contains the saved spooled file. Before running the command, the user space must be on the system in the library that you specify or in the job's library list.
The Restore Spooled file from User Space (RSTSPLFUS) command is shown in Figure 5. There is only one parameter, the qualified name of the user space that contains the saved spooled file. Before running the command, the user space must be on the system in the library that you specify or in the job's library list.
The CPP for the RSTSPLFUS command is CL program SPLF005CL, shown in 6. This program simply splits the qualified user space name into its components, then calls RPG program SPLF005RG. The CL program includes code to display any error messages issued by the RPG program.
The CPP for the RSTSPLFUS command is CL program SPLF005CL, shown in Figure 6. This program simply splits the qualified user space name into its components, then calls RPG program SPLF005RG. The CL program includes code to display any error messages issued by the RPG program.
RPG program SPLF005RG (7) calls four subroutines. The first, RTVUS, retrieves the spooled file attribute information from the user space. The QUSRTVUS API is called to retrieve the header information. Recall that the SPLF004RG program stored the attribute start position and length in the first eight bytes of the header. After retrieving the header part of the user space, the subroutine calls QUSRTVUS again to retrieve the spooled file attributes into the attribute data structure (RCVVAR).
RPG program SPLF005RG (Figure 7) calls four subroutines. The first, RTVUS, retrieves the spooled file attribute information from the user space. The QUSRTVUS API is called to retrieve the header information. Recall that the SPLF004RG program stored the attribute start position and length in the first eight bytes of the header. After retrieving the header part of the user space, the subroutine calls QUSRTVUS again to retrieve the spooled file attributes into the attribute data structure (RCVVAR).
In subroutine CRTSP, we call the QSPCRTSP API to create a new spooled file. The API uses the attribute information data structure as an input parameter. It returns a handle to the newly created spooled file as output. At this point, the spooled file is on the system as a "shell," into which the saved spooled file data is placed.
The PUTSP subroutine calls the QSPPUTSP API to put spooled file information into the spooled file from the user space. This API uses two parameters: the handle to the newly created spooled file and the qualified name of the user space. As with the QSPGETSP API, you do not need to do anything special to get all the data from the user space into the spooled file. The API locates the needed header information, then reads all the saved spooled file buffer information and writes it to the spooled file.
Finally, the CLOSP subroutine closes the spooled file. The spooled file now exists on your system. It is an exact copy of the original spooled file, including all the special formatting that was in the original version.
Ownership and Placement
When a spooled file is created with the QSPCRTSP API, its ownership and placement (output queue) may be different from the original values. If the user name value in the spooled file attributes is the same as the current user, the spooled file is created within the current user's job. The job name, job number and spooled file number are set to valid values for that job. The spooled file is created under the current user's name if the attribute user name stored with the file is different than the current user. A special system job, QPRTJOB, is used for this type of restore. The job number and spooled file number are set to valid values within the QPRTJOB job.
The new spooled file is created in the output queue specified in the stored attributes. You can change the output queue in which the spooled file is located by changing the output queue name and library fields in the attribute data structure before calling the QSPCRTSP API.
If the output queue specified in the attributes does not exist when the QSPCRTSP API is called, output queue QGPL/QPRINT is used. If QGPL/QPRINT does not exist, escape message CPF9845 ("Output queue not found") is sent and the restore program is canceled.
Performance
I ran a few tests, comparing the performance of the API save method with the CPYSPLF command. I timed these tests with a wristwatch. The API method saved a 65-page text report to a user space in six seconds. The size of the user space was 167424 bytes. The same report saved to a database file with CPYSPLF took 12 seconds (not including the time to run the CRTPF command to create the output file used by CPYSPLF). The file size was 417792 bytes.
Another test on a 54-page text report had similar timing ratios, although the size ratio was not as dramatic (along the order of 4:5).
Beyond CPYSPLF
This article has shown how you can use several of the system APIs to create a utility that provides a function unavailable with normal OS/400 commands. The primary advantage of using the API method is that an exact copy of a spooled file can be saved and restored to your system. This is in contrast to the CPYSPLF command that saves only text data. Even if you save and restore text spooled files only, you may find the API method to be useful.
Craig Pelkie can be reached through Midrange Computing.
Reference System Programmer's Interface Reference (SC41-8223, CD ROM QBKA8401)
SIDEBAR
What is a User Space?
A user space is a type of object that you can create, manipulate and delete. You can save and restore a user space like any other object. A user space is quite simply an area of disk storage. It is similar to a data area, but it may be as large as 16MB.
Some APIs use a user space to store their output. This is because the APIs often need to store "header" information, used to describe the contents of the user space, and the data itself. Some of the APIs store what is best characterized as variable length data. For those reasons, it would be cumbersome for an API to write to a database file and difficult for programs to work with the data. By storing the information in a user space, the API can simply write to the next available section of the space. User programs can read from the user space by identifying a starting point within the user space and the number of bytes to read.
Many of the system APIs that put information into a user space write a "header" section into the user space. The header is in the first part of the user space, usually 140 bytes long. Subfields within the header typically include the number of bytes used, the location and length of the first entry and information about the API that put the data into the user space. If you are using APIs to put and retrieve data into the user space, you should obtain current values from the header (such as start position and length of an entry), rather than hard code those values into your program. The reason is that new versions of the API may change those values. By retrieving them from the header, you are working with current values.
There are five user space APIs. These are Create User Space (QUSCRTUS), Delete User Space (QUSDLTUS), Change User Space (QUSCHGUS), Retrieve User Space (QUSRTVUS) and Retrieve Pointer to User Space (QUSPTRUS). There is also a system command to delete a user space, DLTUSRSPC.
The QUSCRTUS API is used to create a new user space. You can optionally request that an existing space of the same name be replaced. The API includes an initial size parameter, where you specify the number of bytes you want in the user space. Many of the system APIs extend the size if they need additional space. For your own programs, you must ensure that the user space is sufficiently large for your needs; there is no automatic expansion.
There are two methods of deleting a user space. The first one is to use the QUSDLTUS API. The other method is to use the DLTUSRSPC command. In both cases, you supply the name and library of the user space you want to delete.
The QUSCHGUS API is used to change one or more bytes in the user space. You specify the starting position within the space to change, the number of bytes to change, and the name of a variable that contains the new values to put into the user space.
The QUSRTVUS API retrieves the specified number of bytes from the user space at a specified starting point. The bytes are retrieved into a variable that you supply as a parameter. The QUSPTRUS API is used with pointer capable languages (such as C) to provide more efficient access to a user space and its contents.
Additional information about user spaces may be found in the System Programmer's Interface Reference and in the August 1991 issue of Midrange Computing ("APIs and the Anatomy of a User Space" and "A List API Processor").
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 1 Command SAVSPLFUS
/*===============================================================*/
/* To compile: */
/* */
/* CRTCMD CMD(XXX/SAVSPLFUS) PGM(XXX/SPLF004CL) + */
/* SRCFILE(XXX/QCMDSRC) */
/* */
/*===============================================================*/
SAVSPLFUS: CMD PROMPT('Save SPLF to USRSPC')
PARM KWD(FILE) TYPE(*NAME) LEN(10) MIN(1) +
PROMPT('Spooled file')
PARM KWD(JOB) TYPE(Q1) DFT(*) SNGVAL((*)) +
PROMPT('Job name')
PARM KWD(SPLNBR) TYPE(*DEC) LEN(4) DFT(*ONLY) +
RANGE(1 9999) SPCVAL((*ONLY 0) (*LAST +
-1)) PROMPT('Spooled file number')
PARM KWD(USRSPC) TYPE(Q2) +
PROMPT('User space name')
PARM KWD(TEXT) TYPE(*CHAR) LEN(50) +
DFT(*GEN) PROMPT('Text')
Q1: QUAL TYPE(*NAME) LEN(10)
QUAL TYPE(*NAME) LEN(10) PROMPT('User')
QUAL TYPE(*CHAR) LEN(6) RANGE('000000' '999999') +
PROMPT('Number')
Q2: QUAL TYPE(*NAME) LEN(10) DFT(*GEN) SPCVAL((*GEN))
QUAL TYPE(*NAME) LEN(10) DFT(*CURLIB) +
SPCVAL((*CURLIB)) PROMPT('Library')
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 2 CL Program SPLF004CL
/*===============================================================*/
/* To compile: */
/* */
/* CRTCLPGM PGM(XXX/SPLF004CL) SRCFILE(XXX/QCLSRC) */
/* */
/*===============================================================*/
SPLF004CL: +
PGM PARM(&PMSPNM &PMQUALJOB &PMSPNO &PMQUALUSP &PMTEXT)
DCL VAR(&PMSPNO) TYPE(*DEC) LEN(4 0)
DCL VAR(&PMQUALJOB) TYPE(*CHAR) LEN(26)
DCL VAR(&PMJBNM) TYPE(*CHAR) LEN(10)
DCL VAR(&PMUSNM) TYPE(*CHAR) LEN(10)
DCL VAR(&PMJBNO) TYPE(*CHAR) LEN(6)
DCL VAR(&PMSPNM) TYPE(*CHAR) LEN(10)
DCL VAR(&PMQUALUSP) TYPE(*CHAR) LEN(20)
DCL VAR(&PMUSPN) TYPE(*CHAR) LEN(10)
DCL VAR(&PMUSLB) TYPE(*CHAR) LEN(10)
DCL VAR(&PMTEXT) TYPE(*CHAR) LEN(50)
DCL VAR(&PMERRC) TYPE(*CHAR) LEN(1)
DCL VAR(&PMMSG) TYPE(*CHAR) LEN(7)
DCL VAR(&PMDTA) TYPE(*CHAR) LEN(100)
/* Extract qualified job name components */
CHGVAR VAR(&PMJBNM) VALUE(%SST(&PMQUALJOB 1 10))
CHGVAR VAR(&PMUSNM) VALUE(%SST(&PMQUALJOB 11 10))
CHGVAR VAR(&PMJBNO) VALUE(%SST(&PMQUALJOB 21 6))
/* Extract qualified user space name components */
CHGVAR VAR(&PMUSPN) VALUE(%SST(&PMQUALUSP 1 10))
CHGVAR VAR(&PMUSLB) VALUE(%SST(&PMQUALUSP 11 10))
/* Call program to save spooled file to user space */
CALL PGM(SPLF004RG) PARM(&PMJBNM &PMUSNM &PMJBNO &PMSPNM &PMSPNO +
&PMUSPN &PMUSLB &PMTEXT &PMERRC &PMMSG &PMDTA)
/* Check for, process error messages */
IF COND(&PMERRC *EQ 'O') THEN(SNDPGMMSG MSGID(CPF9898) +
MSGF(QCPFMSG) MSGDTA('Spooled file is open so it cannot be +
saved') MSGTYPE(*ESCAPE))
IF COND(&PMERRC *EQ 'E') THEN(SNDPGMMSG MSGID(&PMMSG) +
MSGF(QCPFMSG) MSGDTA(&PMDTA) MSGTYPE(*ESCAPE))
ENDPGM
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 3 RPG Program SPLF004RG
*===================================================================
* To compile:
*
* CRTRPGPGM PGM(XXX/SPLF004RG) SRCFILE(XXX/QRPGSRC)
*
*===================================================================
* Receiver variable for spool file attributes
IRCVVAR DS 3301
I 49 58 JOBNAM
I 59 68 USRNAM
I 69 74 JOBNUM
I 75 84 FILNAM
I B 85 880FILNUM
I 99 108 USRDTA
I B 149 1520TOTPAG
I B 861 8640BUFSIZ
I B 99710000NBRBUF
I 10191019 FILOPN
* API Error Code Parameter data structure
IAPIERR DS
I I 116 B 1 40ERBYPR
I B 5 80ERBYAV
I 9 15 EREXID
I 17 116 EREXDT
* Parameter for QSPCLOSP API
I DS
I B 1 40SCSPHN
* Parameters for QSPGETSP API
I DS
I B 1 40SGSPHN
I 5 24 SGQSPN
I I 'SPFR0200' 25 32 SGFMTN
I I -1 B 33 360SGBFRD
I I '*WAIT' 37 46 SGENDA
* User Space Header created by QSPGETSP API
IUSHDR DS 128
I B 1 40UHATSP
I B 5 80UHRLEN
I B 89 920UHSZUS
* Parameters for QSPOPNSP API
I DS
I B 1 40SOSPHN
I 5 30 SOQJOB
I 5 14 SOJBNM
I 15 24 SOUSNM
I 25 30 SOJBNO
I 31 46 SOINJB
I 47 62 SOINSP
I 63 72 SOSPNM
I B 73 760SOSPNO
I I -1 B 77 800SONOBF
* Parameters for QUSRSPLA API
I DS
I I 3301 B 1 40RSRLEN
I I 'SPLA0200' 5 12 RSFMTN
I 13 38 RSQJOB
I 13 22 RSJBNM
I 23 32 RSUSNM
I 33 38 RSJBNO
I 39 54 RSINJB
I 55 70 RSINSP
I 71 80 RSSPNM
I B 81 840RSSPNO
* Parameters for QUSCHGUS API
I DS
I 1 20 UCQSPN
I B 21 240UCSTPO
I B 25 280UCLNDT
I I '2' 29 29 UCFORC
* Parameters for QUSCRTUS API
I DS
I 1 20 CUQSPN
I 1 10 CUUSPN
I 11 20 CUUSLB
I I 'SAVSPLFUS' 21 30 CUEXTA
I B 31 340CUISIZ
I I ' ' 35 35 CUIVAL
I I '*ALL' 36 45 CUPUBA
I 46 95 CUTEXT
I I '*YES' 96 105 CUREPL
* Parameters for QUSRTVUS API
I DS
I 1 20 URQSPN
I I 1 B 21 240URSTPO
I I 128 B 25 280URLNDT
*
C *ENTRY PLIST
C PARM PMJBNM 10 *Job name
C PARM PMUSNM 10 *User name
C PARM PMJBNO 6 *Job number
C PARM PMSPNM 10 *Spool file nam
C PARM PMSPNO 40 *Spool file no.
C PARM PMUSPN 10 *USRSPC name
C PARM PMUSLB 10 *USRSPC library
C PARM PMTEXT 50 *USRSPC text
C PARM PMERRC 1 *Error code
C PARM PMMSG 7 *MSGID of error
C PARM PMDTA 100 *error msg data
*
C EXSR RSPLA *Rtv SPLF Attr
C EXSR CRTUS *Create USRSPC
C EXSR OPNSP *Open SPLF
C EXSR GETSP *Get SPLF data
C EXSR CLOSP *Close SPLF
C EXSR SAVAT *Save SPLF attr
*
C MOVE *ON *INLR
*===================================================================
* Retrieve Spooled File Attributes - use QUSRSPLA API
*===================================================================
C RSPLA BEGSR
*
C MOVELPMJBNM RSJBNM *Job name
C MOVELPMUSNM RSUSNM *User name
C MOVELPMJBNO RSJBNO *Job number
C CLEARRSINJB *Internal JobNo
C CLEARRSINSP *Internal SPLF
C MOVELPMSPNM RSSPNM *SPLF name
C Z-ADDPMSPNO RSSPNO *SPLF number
*
C CALL 'QUSRSPLA' 99 *99 - error
C PARM RCVVAR *Receiver Var
C PARM RSRLEN *RCVVAR length
C PARM RSFMTN *Format name
C PARM RSQJOB *Qual job name
C PARM RSINJB *Internal Job
C PARM RSINSP *Internal SPLF
C PARM RSSPNM *SPLF name
C PARM RSSPNO *SPLF number
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
* ..if spooled file is still open, set error code and return
C FILOPN IFEQ 'Y' *File open
C MOVEL'O' PMERRC *Error code
C MOVE *ON *INLR
C RETRN
C ENDIF
*
C ENDSR
*===================================================================
* Create User Space - use QUSCRTUS API
*===================================================================
C CRTUS BEGSR
* ..use parm as USRSPC name, or create name
C PMUSPN IFNE '*GEN' *Use parm value
C MOVELPMUSPN CUUSPN *USRSPC name
C ELSE *Generate name
C 'U' CAT JOBNUM:0 CUUSPN *USRSPC name
C MOVE FILNUM W03 3 *SPLF number
C CAT W03:0 CUUSPN
C ENDIF
*
C MOVELPMUSLB CUUSLB *USRSPC library
* ..use parm as USRSPC text, or create text
C PMTEXT IFNE '*GEN' *Use parm value
C MOVELPMTEXT CUTEXT *USRSPC text
C ELSE *Generate text
C JOBNUM CAT '/':0 CUTEXT *Job number
C CAT USRNAM:0 CUTEXT *User name
C CAT '/':0 CUTEXT
C CAT JOBNAM:0 CUTEXT *Job name
C CAT FILNAM:2 CUTEXT *SPLF name
C MOVE FILNUM W04 4 *SPLF number
C CAT W04:2 CUTEXT
C CAT USRDTA:2 CUTEXT *SPLF user data
C ENDIF
* ..set initial size for USRSPC.
C BUFSIZ ADD 84 W09N0 90 *SPLF buffer sz
C W09N0 MULT NBRBUF CUISIZ *Initial size
C TOTPAG MULT 12 W09N0 *Total pages
C ADD W09N0 CUISIZ
C ADD 128 CUISIZ *USRSPC header
C ADD RSRLEN CUISIZ *Rcvr var len
*
C CALL 'QUSCRTUS' 99 *99 - error
C PARM CUQSPN *Qual USRSPC
C PARM CUEXTA *Extended Attr
C PARM CUISIZ *Initial size
C PARM CUIVAL *Initial value
C PARM CUPUBA *Public Auth
C PARM CUTEXT *Text
C PARM CUREPL *Replace
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Open Spool File - use QSPOPNSP API
*===================================================================
C OPNSP BEGSR
*
C CLEARSOSPHN *SPLF handle
C MOVELPMJBNM SOJBNM *Job name
C MOVELPMUSNM SOUSNM *User name
C MOVELPMJBNO SOJBNO *Job number
C CLEARSOINJB *Internal JobNo
C CLEARSOINSP *Internal SPLF
C MOVELPMSPNM SOSPNM *SPLF name
C Z-ADDPMSPNO SOSPNO *SPLF number
*
C CALL 'QSPOPNSP' 99 *99 - error
C PARM SOSPHN *SPLF handle
C PARM SOQJOB *Qual job name
C PARM SOINJB *Internal Job
C PARM SOINSP *Internal SPLF
C PARM SOSPNM *SPLF name
C PARM SOSPNO *SPLF number
C PARM SONOBF *Number buffers
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Get Spooled File data - use QSPGETSP API
*===================================================================
C GETSP BEGSR
*
C Z-ADDSOSPHN SGSPHN *SPLF handle
C MOVELCUQSPN SGQSPN *Qual USRSPC
*
C CALL 'QSPGETSP' 99 *99 - error
C PARM SGSPHN *SPLF handle
C PARM SGQSPN *Qual USRSPC
C PARM SGFMTN *Format name
C PARM SGBFRD *Buffer to read
C PARM SGENDA *End action
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Close Spooled File - use QSPCLOSP API
*===================================================================
C CLOSP BEGSR
*
C Z-ADDSOSPHN SCSPHN *SPLF handle
*
C CALL 'QSPCLOSP' 99 *99 - error
C PARM SCSPHN *SPLF handle
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Save SPLF attributes in User Space.
*===================================================================
C SAVAT BEGSR
* ..get USRSPC header information
C MOVELCUQSPN URQSPN *Qual USRSPC
*
C CALL 'QUSRTVUS' 99 *99 - error
C PARM URQSPN *Qual USRSPC
C PARM URSTPO *Start position
C PARM URLNDT *Length to rtv
C PARM USHDR *Rtv to var.
C PARM APIERR *Error code
*
C EXSR CKERR
* ..change USRSPC generic header area.
C UHSZUS ADD 1 UHATSP *Attr start pos
C Z-ADDRSRLEN UHRLEN *RCVVAR length
*
C MOVELCUQSPN UCQSPN *Qual USRSPC
C Z-ADD1 UCSTPO *Start position
C Z-ADD128 UCLNDT *Length of data
*
C CALL 'QUSCHGUS' 99 *99 - error
C PARM UCQSPN *Qual USRSPC
C PARM UCSTPO *Start position
C PARM UCLNDT *Length of data
C PARM USHDR *New value
C PARM UCFORC *Force changes
C PARM APIERR *Error code
*
C EXSR CKERR
* ..put SPLF Attributes into USRSPC, following saved SPLF data
C Z-ADDUHATSP UCSTPO *Start position
C Z-ADDUHRLEN UCLNDT *RCVVAR length
*
C CALL 'QUSCHGUS' 99 *99 - error
C PARM UCQSPN *Qual USRSPC
C PARM UCSTPO *Start position
C PARM UCLNDT *Length of data
C PARM RCVVAR *SPLF Attr data
C PARM UCFORC *Force changes
C PARM APIERR *Error code
*
C EXSR CKERR
*
C ENDSR
*===================================================================
* Check for error on API call - return if any error
*===================================================================
C CKERR BEGSR
*
C ERBYAV IFGT 0 *Bytes avail
C MOVELEREXID PMMSG *Exception ID
C MOVELEREXDT PMDTA *Exception data
C MOVEL'E' PMERRC *Error code
C MOVE *ON *INLR
C RETRN
C ENDIF
*
C ENDSR
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 4 Calculating the Size of the User Space
Information Required Source Allocation
Number of pages Attribute information 12 bytes per page
in the spooled file data structure.
Number of spooled Attribute information Length plus 84 bytes per
file buffers data structure. buffer
Buffer length Attribute information N/A
(512 or 4079 bytes) data structure.
Length of header area Constant (may change 128 bytes
in future releases)
Length for saved Constant (may change 3301 bytes
attribute information in future releases)
size = (pages * 12) + ((buffers * (buffer length + 84)) + 128 + 3301
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 5 Command RSTSPLFUS
/*===============================================================*/
/* To compile: */
/* */
/* CRTCMD CMD(XXX/RSTSPLFUS) PGM(XXX/SPLF005CL) + */
/* SRCFILE(XXX/QCMDSRC) */
/* */
/*===============================================================*/
RSTSPLFUS: CMD PROMPT('Restore SPLF from USRSPC')
PARM KWD(USRSPC) TYPE(Q1) MIN(1) PROMPT('User +
space name')
Q1: QUAL TYPE(*NAME) LEN(10)
QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) +
SPCVAL((*LIBL)) PROMPT('Library')
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 6 CL Program SPLF005CL
/*===============================================================*/
/* To compile: */
/* */
/* CRTCLPGM PGM(XXX/SPLF005CL) SRCFILE(XXX/QCLSRC) */
/* */
/*===============================================================*/
SPLF005CL: +
PGM PARM(&PMQUALUSP)
DCL VAR(&PMQUALUSP) TYPE(*CHAR) LEN(20)
DCL VAR(&PMUSPN) TYPE(*CHAR) LEN(10)
DCL VAR(&PMUSLB) TYPE(*CHAR) LEN(10)
DCL VAR(&PMERRC) TYPE(*CHAR) LEN(1)
DCL VAR(&PMMSG) TYPE(*CHAR) LEN(7)
DCL VAR(&PMDTA) TYPE(*CHAR) LEN(100)
/* Extract qualified user space name components */
CHGVAR VAR(&PMUSPN) VALUE(%SST(&PMQUALUSP 1 10))
CHGVAR VAR(&PMUSLB) VALUE(%SST(&PMQUALUSP 11 10))
/* Call program to restore spooled file from user space */
CALL PGM(SPLF005RG) PARM(&PMUSPN &PMUSLB &PMERRC &PMMSG &PMDTA)
/* Check for, process error messages */
IF COND(&PMERRC *EQ 'E') THEN(SNDPGMMSG MSGID(&PMMSG) +
MSGF(QCPFMSG) MSGDTA(&PMDTA) MSGTYPE(*ESCAPE))
ENDPGM
Beyond CPYSPLF - Saving Everything in a SPLF
Figure 7 RPG Program SPLF005RG
*===================================================================
* To compile:
*
* CRTRPGPGM PGM(XXX/SPLF005RG) SRCFILE(XXX/QRPGSRC)
*
*===================================================================
* Receiver variable for spool file attributes
IRCVVAR DS 3301
* API Error Code Parameter data structure
IAPIERR DS
I I 116 B 1 40ERBYPR
I B 5 80ERBYAV
I 9 15 EREXID
I 17 116 EREXDT
* Parameter for QSPCLOSP API
I DS
I B 1 40SCSPHN
* Parameter for QSPCRTSP API
I DS
I B 1 40CSSPHN
* User Space Header created by QSPGETSP API
IUSHDR DS 128
I B 1 40UHATSP
I B 5 80UHRLEN
* Parameters for QSPPUTSP API
I DS
I B 1 40PSSPHN
I 5 24 PSQSPN
I 5 14 PSUSPN
I 15 24 PSUSLB
* Parameters for QUSRTVUS API
I DS
I 1 20 URQSPN
I 1 10 URUSPN
I 11 20 URUSLB
I I 1 B 21 240URSTPO
I I 128 B 25 280URLNDT
*
C *ENTRY PLIST
C PARM PMUSPN 10 *USRSPC name
C PARM PMUSLB 10 *USRSPC library
C PARM PMERRC 1 *Error code
C PARM PMMSG 7 *MSGID of error
C PARM PMDTA 100 *error msg data
*
C EXSR RTVUS *Rtv USRSPC
C EXSR CRTSP *Create SPLF
C EXSR PUTSP *Put SPLF data
C EXSR CLOSP *Close SPLF
*
C MOVE *ON *INLR
*===================================================================
* Retrieve values from USRSPC
*===================================================================
C RTVUS BEGSR
*
C MOVELPMUSPN URUSPN *USRSPC name
C MOVELPMUSLB URUSLB *USRSPC library
* ..retrieve SPLF attribute data start position, length
C CALL 'QUSRTVUS' 99 *99 - error
C PARM URQSPN *Qual USRSPC
C PARM URSTPO *Start position
C PARM URLNDT *Length of data
C PARM USHDR *Rtv to var
C PARM APIERR *Error code
*
C EXSR CKERR
* ..retrieve SPLF attribute data
C Z-ADDUHATSP URSTPO *Start position
C Z-ADDUHRLEN URLNDT *Length of data
*
C CALL 'QUSRTVUS' 99 *99 - error
C PARM URQSPN *Qual USRSPC
C PARM URSTPO *Start position
C PARM URLNDT *Length of data
C PARM RCVVAR *Rtv to var
C PARM APIERR *Error code
*
C EXSR CKERR
*
C ENDSR
*===================================================================
* Create Spool File - use QSPCRTSP API
*===================================================================
C CRTSP BEGSR
*
C CALL 'QSPCRTSP' 99 *99 - error
C PARM CSSPHN *SPLF handle
C PARM RCVVAR *SPLF attrs
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Put SPLF data from USRSPC to newly created SPLF
*===================================================================
C PUTSP BEGSR
*
C Z-ADDCSSPHN PSSPHN *SPLF handle
C MOVELPMUSPN PSUSPN *USRSPC name
C MOVELPMUSLB PSUSLB *USRSPC library
*
C CALL 'QSPPUTSP' 99 *99 - error
C PARM PSSPHN *SPLF handle
C PARM PSQSPN *Qual USRSPC
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Close Spooled File - use QSPCLOSP API
*===================================================================
C CLOSP BEGSR
*
C Z-ADDCSSPHN SCSPHN *SPLF handle
*
C CALL 'QSPCLOSP' 99 *99 - error
C PARM SCSPHN *SPLF handle
C PARM APIERR *Error code
*
C EXSR CKERR *Check API err
*
C ENDSR
*===================================================================
* Check for error on API call - return if any error
*===================================================================
C CKERR BEGSR
*
C ERBYAV IFGT 0 *Bytes avail
C MOVELEREXID PMMSG *Exception ID
C MOVELEREXDT PMDTA *Exception data
C MOVEL'E' PMERRC *Error code
C MOVE *ON *INLR
C RETRN
C ENDIF
*
C ENDSR
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online