User spaces for list APIs

List APIs require a user space to contain returned information.

A user space is an object type that is created by the Create User Space (QUSCRTUS) API. Generally, a user space is used when information about more than one object is being requested.

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. Logic flow of processing a list of entries 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. Language selection considerations 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.