# 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:

1. 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.
2. 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.
3. Refer to the Authorized Assembler Services Guide for your system's level of MVS or OS/390 for more information on the DYNALLOC service.
4. 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.

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.

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.

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:

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

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

© Copyright 1998 by Open Software Technologies, Inc.