SEARCHBIN: Creating a list of bin numbers

Purpose

Before you begin: To use the RMM SEARCHBIN subcommand, you need READ access to the STGADMIN.EDG.MASTER resource profile.

Use the SEARCHBIN subcommand to create a list of shelf locations that are defined to DFSMSrmm. DFSMSrmm defines shelf space in storage locations as bin numbers.

You can restrict how many bin numbers DFSMSrmm lists by specifying the LIMIT operand. DFSMSrmm searches until your limit is reached or until it lists all shelf locations that match your search criteria. If you do not specify a search limit, DFSMSrmm lists a maximum of ten shelf locations.

Table 1 shows the information DFSMSrmm returns for each bin number in the list, in the order it is displayed:

Table 1. Information returned by SEARCHBIN
Table field name	Description
Rack/Bin	Bin number
Medianame	Type of volume
Volume	Volume serial number
Status	Status of the shelf location (one of EMPTY, INUSE, or SCRATCH)
Location	Location where the volume resides
Moving-in-volume	Volume that will move into this bin
Moving-out-volume	Volume that will move out of this bin
Old volume	Volume that was previously in this bin
Note: Moving-in volume, moving-out volume, and old volume information is available only if Extended Bin Support is enabled. See the topic Enabling extended bin support in z/OS DFSMSrmm Implementation and Customization Guide.

Format

SEARCHBIN syntax diagram


>>-+-SEARCHBIN-+--+---------------------------------------+----->
   '-SB--------'  |      .-*--------------------------.   |   
                  '-BIN(-+-full_or_generic_bin_number-+-)-'   

>--+-------------------------------------------------+---------->
   |                           .-LIST---.  .-START-. |   
   '-CLIST--| CLIST strings |--+--------+--+-------+-'   
                               '-NOLIST-'  '-ADD---'     

>--+-------------------------------------------------------------------------+-->
   '-CONTINUE(-+---------------------------------------------------------+-)-'   
               '-BIN(bin_number)-+-MEDIANAME(media)-LOCATION(loc_name)-+-'       
                                 '-STORE(builtin_store)----------------'         

>--+-------+--+---------------------------+--------------------->
   +-INUSE-+  |        .-10-----------.   |   
   '-EMPTY-'  '-LIMIT(-+-search_limit-+-)-'   
                       '-*------------'       

>--+-------------------+---------------------------------------->
   '-MOVING(-+-YES-+-)-'   
             +-NO--+       
             +-IN--+       
             '-OUT-'       

>--+-| Built-in locations |-------------+----------------------><
   '-| Installation defined locations |-'   

CLIST strings

|--(prefix_string,suffix_string)--------------------------------|

Built-in locations

|--+-------------------------+----------------------------------|
   '-LOCATION(-+-LOCAL---+-)-'   
               +-DISTANT-+       
               '-REMOTE--'       

Installation defined locations

|--+--------------------------------+--------------------------->
   '-LOCATION(LOCDEF_location_name)-'   

>--+----------------------------+-------------------------------|
   '-MEDIANAME(-+-medianame-+-)-'   
                '-*---------'

Parameters

ADD

Specify this operand to request that new records written to the CLIST data set are added after any existing records in the data set. When the CLIST data set is empty or DFSMSrmm creates the CLIST data set during command execution, specifying ADD is the same as specifying START.

ADD is mutually exclusive with START.

You can easily build a set of commands from CLIST processing using multiple SEARCH subcommands of the same or different resource types. For variable length records, the minimum record length can cause the LRECL to be increased. For fixed length records, if the minimum length cannot be accommodated, the subcommand fails.

BIN(full_or_generic_bin_number|*)

Specify a full or generic bin_number to define a shelf location in a storage location. A bin number in a built-in storage location is six numeric characters. A bin number in an installation defined storage location is six alphanumeric or national characters. You must also give a location name and media name.

An asterisk tells DFSMSrmm to search through all bin numbers.

CLIST(prefix_string,suffix_string)

Specify a CLIST to create a data set of executable commands. You can edit the data set to remove any bin numbers you do not want in the list. Then you can run the CLIST at your convenience.

DFSMSrmm returns the number of the shelf location for each record if you do not specify (prefix_string and suffix_string).

You can add RMM TSO subcommands and operands to the records in the CLIST data set by specifying (prefix_string and suffix_string). These text strings cannot exceed 255 characters. Separate the prefix_string and suffix_string using a blank or a comma between the text strings. Insert blanks in the prefix and suffix values to prevent DFSMSrmm from concatenating the strings with the data that DFSMSrmm returns. To enter a null prefix_string, add a pair of separator characters such as '' to the text string (for example, CLIST('','suffix_string')).

See Creating CLISTs of executable subcommands for information about the data set used for the CLIST output.

CONTINUE(BIN(bin_number) bininfo)

Specify the CONTINUE operand without any value to notify DFSMSrmm SEARCH subcommand processing that you want to break down the search results based on the LIMIT value and request that DFSMSrmm return the search continue information for use with the next command. For TSO, the continue information is returned either as a REXX variable or as a linemode message. When the subcommand is issued from the DFSMSrmm API, the continuation information may be either a linemode message or an SFI or XML attribute.

CONTINUE is an optional operand.

Use the LIMIT operand to control the maximum number of entries to be returned each time you start or continue the search.

To continue a previous search subcommand, the CONTINUE operand value includes these values to identify the current search position:

BIN(bin_number): bin_number is one to six characters enclosed in single quotation marks if it contains any special characters, or blank.

And, either one of the followingbininfo:

LOCATION(loc_name): loc_name is one to eight characters enclosed in single quotation marks if it contains any special characters, or blank.

and

MEDIANAME(media): media is one to eight characters enclosed in single quotation marks if it contains any special characters, or blank.

Or,

STORE(builtin_store)

Enter one of the built-in storage location names: LOCAL, DISTANT, REMOTE. Abbreviations are acceptable. For example, L stands for LOCAL.

LOCAL: The local storage location.
DISTANT: The distant storage location.
REMOTE: The remote storage location.

The information required to continue a search subcommand is returned by each search subcommand that specifies the CONTINUE operand and passed back to DFSMSrmm unchanged in order to continue the previous search. You should specify the exact same subcommand unchanged. To do this, just change the CONTINUE operand value on each additional command required.

EMPTY

Specifies bins in a storage location which are available for use.

INUSE

Specifies bins in a storage location that are occupied by a volume and not available for another volume.

LIMIT(search_limit,*)

Specifies how many entries DFSMSrmm lists. The maximum allowable decimal value is 9999. Specify an asterisk to request a list of all entries matching your search criteria.

The default value is 10.

LIST

Specifies that DFSMSrmm produce a list when the CLIST operand is used.

LIST is mutually exclusive with the NOLIST operand. LIST is the default.

LOCATION(LOCAL|DISTANT|REMOTE|LOCDEF_location_name)

Specifies a search in a specific storage location. Specify a built-in storage location name, LOCAL, DISTANT, or REMOTE or LOCDEF_location_name. For LOCDEF_location_name, you can enter any value as no checking is done against the current list of locations defined to DFSMSrmm". For an installation defined storage location, MEDIANAME can also be specified.

The storage location name does not have to be one that is currently defined using the LOCDEF command.

MEDIANAME(medianame|*)

Specifies that the list is limited to shelf locations containing volumes belonging to the same media name. The media name allows you to specify the type or shape of media. They are defined by your installation and one to eight characters. You can also use the media name * which is a media name defined in a LOCDEF command.

If you do not specify MEDIANAME, all the bin numbers in the specified location are listed.

Use the LISTCONTROL subcommand to display media names defined for your location. See LISTCONTROL: Displaying parmlib options and control information for more information.

MOVING(YES|NO|IN|OUT)

Specify to list bins based on the moving status of their assigned volumes.

NOLIST

Specifies that DFSMSrmm should neither produce a list nor set REXX variables for resources when the CLIST operand is used. DFSMSrmm produces only the CLIST output file.

NOLIST is mutually exclusive with the LIST operand. LIST is the default.

START

Specify this operand to request that records written to the CLIST data set start from the beginning of the data set.

START is mutually exclusive with ADD.

START is the default value.

Examples

Task: Create a list of empty bin numbers that are available for use in the DPBINS storage location.

Command:

RMM SEARCHBIN BIN(A*) LOCATION(DPBINS) MEDIANAME(3480) EMPTY

Output: DFSMSrmm displays a list such as the one shown in Figure 1.

Figure 1. Sample SEARCHBIN output for empty bins

Rack/Bin           Media              Current  Moving-in  Moving-out  Old
number   Location  name      Status   volume   volume     volume      volume
-------- --------  --------  -------  -------  ---------  ----------  ------
A00001   DPBINS    3480      EMPTY
A00002   DPBINS    3480      EMPTY
A00003   DPBINS    3480      EMPTY
A00004   DPBINS    3480      EMPTY
A00005   DPBINS    3480      EMPTY
A00006   DPBINS    3480      EMPTY
A00007   DPBINS    3480      EMPTY
A00008   DPBINS    3480      EMPTY
A00009   DPBINS    3480      EMPTY
A00010   DPBINS    3480      EMPTY
EDG3203I SEARCH COMPLETE - MORE ENTRIES MAY EXIST
EDG3012I 10         ENTRIES LISTED

Task: Create a list of bin numbers.

Command:

RMM SEARCHBIN BIN(*)

Output: DFSMSrmm displays a list such as the one shown in Figure 2.

Figure 2. Sample SEARCHBIN output

Rack/Bin           Media              Current  Moving-in  Moving-out  Old
number   Location  name      Status   volume   volume     volume      volume
-------- --------  --------  -------  -------  ---------  ----------  ------
000001   LOCAL               IN USE   A09999
000002   LOCAL               EMPTY
000003   LOCAL               IN USE   A09003
000004   LOCAL               EMPTY     
000005   LOCAL               EMPTY     
000006   LOCAL               IN USE   A09005
000007   LOCAL               EMPTY
000008   LOCAL               EMPTY
000009   LOCAL               EMPTY
000010   LOCAL               EMPTY
EDG3203I SEARCH COMPLETE - MORE ENTRIES MAY EXIST
EDG3012I 10         ENTRIES LISTED

Task: Create a list of bin numbers using the CONTINUE operand to break down the results of a search into small quantities.

First Command:

RMM SEARCHBIN LIMIT(100) CONTINUE

First output: DFSMSrmm displays a list such as the one shown in Figure 3.

Figure 3. Sample SEARCHBIN output for bins numbers using the CONTINUE operand

Rack/Bin           Media              Current  Moving-in  Moving-out  Old
number   Location  name      Status   volume   volume     volume      volume
-------- --------  --------  -------  -------  ---------  ----------  ------
000001   DISTANT             EMPTY
000002   DISTANT             EMPTY
000003   DISTANT             EMPTY
...
...
...
000003   LOCAL               EMPTY
000004   LOCAL               EMPTY
000005   LOCAL               EMPTY
EDG3203I SEARCH COMPLETE - MORE ENTRIES MAY EXIST
EDG3012I 100        ENTRIES LISTED
EDG3025I BIN('000005')STORE(L)

Second Command:

RMM SEARCHBIN LIMIT(100) CONTINUE(BIN('000005')STORE(L))

Second output: DFSMSrmm displays a list such as the one shown in Figure 4.

Figure 4. Sample SEARCHBIN output for bins numbers using the CONTINUE operand

Rack/Bin           Media              Current  Moving-in  Moving-out  Old
number   Location  name      Status   volume   volume     volume      volume
-------- --------  --------  -------  -------  ---------  ----------  ------
000006   LOCAL               EMPTY
000007   LOCAL               EMPTY
000008   LOCAL               EMPTY
...
...
...
M00008   MAZBIN    3480      EMPTY
M00009   MAZBIN    3480      EMPTY
M00010   MAZBIN    3480      EMPTY
EDG3203I SEARCH COMPLETE - MORE ENTRIES MAY EXIST
EDG3012I 100        ENTRIES LISTED
EDG3025I BIN('M00010')LOCATION('MAZBIN')MEDIANAME('3480')

Third Command:

RMM SEARCHBIN LIMIT(100) CONTINUE(BIN('M00010')LOCATION('MAZBIN')MEDIANAME('3480'))

Third output: DFSMSrmm displays a list such as the one shown in Figure 5.

Figure 5. Sample SEARCHBIN output for bins numbers using the CONTINUE operand

Rack/Bin           Media              Current  Moving-in  Moving-out  Old
number   Location  name      Status   volume   volume     volume      volume
-------- --------  --------  -------  -------  ---------  ----------  ------
M00011   MAZBIN    3480      EMPTY
M00012   MAZBIN    3480      EMPTY
M00013   MAZBIN    3480      EMPTY
...
...
...
W00003   WORMSBIN  3490      EMPTY
W00004   WORMSBIN  3490      EMPTY
W00005   WORMSBIN  3490      EMPTY
EDG3012I 65        ENTRIES LISTED

Return codes

See DFSMSrmm return codes and reason codes for DFSMSrmm reason codes.

0: Subcommand completed normally.
4: Warning. Subcommand completed but some operands could have been ignored or modified. DFSMSrmm sets a reason code.
8: User not authorized.
12: Subcommand ended with an error. DFSMSrmm sets a reason code.
16: Error. The DFSMSrmm subsystem is not active.
20: Error. The data is incomplete or incorrect and the TSO user has set NOPROMPT.
24: The TSO subcommand is not APF authorized.
28: The user pressed the attention key.