User spaces for list APIs

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. 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.

• Logic flow of processing a list of entries
  This topic shows you what a logic flow looks like when you process a list containing multiple entries.
• Manipulating a user space with pointers
  Some languages, such as ILE C, Visual Age for C++, ILE COBOL, ILE RPG, COBOL, Pascal, and PL/I, support pointers. Pointers allow you to manipulate information more rapidly from the user space.
• Manipulate a user space without pointers
  When programming in a language that does not support pointers, you can use the Change user space (QUSCHGUS) and Retrieve user space (QUSRTVUS) APIs to manipulate data. However, you must first understand how to use positions and lengths with these APIs.
• Examples: Change a user space
  These examples illustrate how a user space can be changed.
• Additional information about list APIs and a user space
  Before you can use a list API to create a list, the *USRSPC object must exist.
• Example: List database file members with a CL program
  This program generates a list of members that start with M, and places the list into a user space named example in Library QGPL.