Filter
Top Products
User Spaces
internal job ID to access a spooled file for a job with the Retrieve Spooled File
Attributes (QUSRSPLA) API.
User Spaces
APIs that return information to a caller generally return the information in a user
space (used by list APIs) or a receiver variable (used by retrieve APIs).
1
The list APIs require a user space for returning information. A user space is an
object type that is created by the Create User Space (QUSCRTUS) API. Gener-
ally, a user space is used when information about more than one object is being
requested.
Following are some of the advantages of using user spaces:
User spaces can be automatically extendable.
User spaces can be shared across jobs.
User spaces can exist across IPLs.
Most lists returned by APIs are made up of a series of entries where each entry is
a data structure. Special fields are placed in the user space at consistent locations
that describe:
Where the list begins.
The number of entries. The topic “Logic Flow of Processing a List of Entries”
on page 2-15 shows the logic for processing a list of entries.
The length of each entry.
User spaces are used for such functions as returning either a list of members in a
file or objects in a library. When you use one of the list APIs, the parameter list
requires that you name the user space that will be used.
User spaces can be processed in two ways:
If your language supports pointers, you can access or change the information
directly. Figure 2-2 on page 2-3 describes each supported language and
whether it supports pointers. Generally, pointer access is faster than API
access.
For languages that do not support pointers, you can use APIs to access or
change the data in a user space. For example, the data in a user space can
be accessed by the Retrieve User Space (QUSRTVUS) API. The API identifies
a receiver variable that receives a number of bytes of information from the user
space.
You can pass the user space as a parameter to a program. You do need to use a
language that has pointer support to be able to pass the address of the first byte of
the user space as a parameter to the processing program. “Retrieving a File
Description to a User Space—Examples” on page B-152 shows an example of
pointer support.
1
A user space is an object consisting of a collection of bytes that can be used for storing any user-defined information. A receiver
variable is a program variable that is used as an output field to contain information that is returned from an API.
Chapter 2. Getting Started with APIs
2-13