IBM Version 4 manual User Spaces, Used by retrieve

User Spaces

internal job ID to access a spooled file for a job with the Ret Attributes (QUSRSPLA) API.

User Spaces

APIs	that return	information	to a	caller generally returnuser	the informati
space	(used by	list receiverAPIs)	variableor a	1	APIs).
				(used by retrieve

The list APIs require a user space for returning information. A user object type that is created by the Create User Space (QUSCRTUS) ally, a user space is used when information about more than one obj 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

w

a

data structure. Special fields are placed

in

the

user

space at

that

describe:

Ÿ

Where the

list

begins.

Ÿ

The number of

entries. The topic

“Logic

Flow

of

Processing

a List

o

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 lis
file or objects in a			library. When you	use	one	of	the list APIs,
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 directly. Figure 2-2 on page 2-3 describes each supported language whether it supports pointers. Generally, pointer access is faster access.

ŸFor languages that do not support pointers, you can use APIs to a

change the data	in a	user space. For	example, the data in a us
be accessed by	the	Retrieve User	Space (QUSRTVUS) API. The API
a receiver variable that receives a			number of bytes of informat
space.

You can pass the user space as a parameter to a program. You do language that has pointer support to be able to pass the address the user space as a parameter to the processing program. “Retrieving Description to a User Space—Examples” on page B-152 shows an example pointer support.

1 A user	space	is	an object consisting	of a collection of bytes that	can be used for receiverstoring any user-de
variable	is	a	program variable that	is used as an output field to	contain information	that is returned
				Chapter	2. Getting Started	with2-13APIs