LISTA (List Allocations)

Syntax:

LISTA([ddpattern][stem])

Arguments:

ddpattern

is the 1 to 8 character name that identifies the ddname or ddnames for which you want allocation information. If the pattern does not contain any wild card characters, at most, information for one ddname will be returned. For more information on specifying this argument, see "Using Pattern Matching".

Note: If ddpattern is not specified, information for all currently allocated ddnames will be returned.

stem

the name of a stem array into which LISTA is to direct ddname information. If you desire a true REXX stem, you must code a period suffix. For example, coding "abc." will yield variables of the form abc.1, abc.2. abc.n.

If stem is not coded, ddname information is queued to the REXX data stack.

Note: No zeroth variable is created. The number of stem elements created is returned as a component of the function's value (see "Returned Information" below).

Module Name:

SWXLISTA

Service Description:

The LISTA function is used to retrieve current allocation environment information. One record of information is produced for each ddname matching the ddpattern argument. The records are returned in the REXX data stack (the default) or in a stem array.

Notes:

LISTA uses the DYNALLOC information function to extract allocation environment information. DYNALLOC obtains an authorized, job-step-wide enqueue on SYSZTIOT to prevent abends. In multi-tasking environments, contention for SYSZTIOT can cause a task using LISTA to wait.
In multi-tasking environments, it is possible for the information returned by LISTA to change even as it is being gathered. This is because other tasks can allocate new ddnames and/or free others while LISTA is executing.
Refer to the Authorized Assembler Services Guide for your system's level of MVS or OS/390 for more information on the DYNALLOC service.
The LISTA function, itself, does not run authorized (i.e., no APF, no supervisor state, no authorized storage keys). All authorized work is performed by SVC 99 (DYNALLOC).

Returned Information:

The LISTA function returns a string. The contents of the string depends on the success of the operation.

If the return code is zero, LISTA returns the return code and the number of ddname information records produced. The return code and the record count are separated by one blank. If the stem argument is specified, the ddname records are placed into a stem array. Otherwise, the records are returned in the REXX data stack. A ddname is represented by exactly one record.

The records of ddname information are structured as follows:

Word Data Item Description
1. ddname The data definition name. This field is exactly 8 bytes in length (i.e., it is blank-padded to permit sorting).
2. dsncount The number of dsn groups that follow. This field is exactly 3 bytes long and right-justified to facilitate sorting.
dsngroups Data set information groups. Each group describes a data set.

Word	Data Item	Description
1.	ddname	The data definition name. This field is exactly 8 bytes in length (i.e., it is blank-padded to permit sorting).
2.	dsncount	The number of dsn groups that follow. This field is exactly 3 bytes long and right-justified to facilitate sorting.
	dsngroups	Data set information groups. Each group describes a data set.

The content of each data set information group is as follows:

Word Data Item Description
1. dsname fully qualified data set name.
2. dsorg data set organization.
3. status allocation status.
4. ndisp normal disposition.
5. cdisp conditional disposition.

Word	Data Item	Description
1.	dsname	fully qualified data set name.
2.	dsorg	data set organization.
3.	status	allocation status.
4.	ndisp	normal disposition.
5.	cdisp	conditional disposition.

If a data item is unavailable, the interface supplies a single question mark (?) as a placeholder. This ensures that the word position of all data items remain constant.

The order of the ddname records is not defined. However, you can use the REXXTOOLS STEMSORT function to sort the records into ddname or dsncount order. The dsngroups within each ddname record are in allocation order.

Note: LISTA performs a REXX DROP on the stem (if specified) prior creating the ddname records.

If the return code is not zero, the function's returned value consists of:

Word Data Item Description
1. rc the DYNALLOC return code.
2. reason the DYNALLOC reason code in printable hexadecimal digits.
message a textual message describing the error. This message can contain embedded blanks.

Word	Data Item	Description
1.	rc	the DYNALLOC return code.
2.	reason	the DYNALLOC reason code in printable hexadecimal digits.
	message	a textual message describing the error. This message can contain embedded blanks.

Depending on the nature of the error, a partial result -- in the form of stem variables or stack entries -- is possible.

If you CALL the LISTA function, the returned string is contained in the RESULT special variable. The RC variable is unchanged (unless you assign the return code to it). A return code of zero always indicates success.

Examples:

List all currently allocated ddnames:

parse value lista() with rc ddncount
if rc = 0 then do i=1 to ddncount
  parse pull ddname .; say ddname; end
else do
  parse var ddncount reason message
  say 'LISTA error:' message
end

List all ddnames that begin with 'SYS', sorted by ddname:

parse value lista('sys*','dd.') with rc dd.0
if dd.0>1 then call stemsort 'dd.',,,'(1,8,ch,a)'
do i=1 to dd.0
  parse var dd.i ddname dsncount dsngrps
  say ddname
  do j=1 to dsncount
    parse var dsngrps dsn do st nd cd dsngrps
    say left(do,3) left(st,3) left(nd,7) left(cd,7) dsn
  end
  say
end