The RETRIEVE function locates the primary or backup copy of an object as specified by the COLLECTN, NAME, and VIEW keywords, and returns all or a specified portion of the object to the caller. Objects greater than 256 megabytes cannot be retrieved using a single OSREQ Retrieve. To retrieve an object greater than 256 megabytes, an object must be retrieved in pieces using multiple OSREQ Retrieves specifying the offset and length (maximum length allowed for each piece is 256 megabytes). The syntax diagram for the OSREQ RETRIEVE function follows.

Syntax for OSREQ RETRIEVE

>>-OSREQ RETRIEVE--MF=-+-L---------------------------------+---->
                       +-(M,parameter_list-+-----------+-)-+   
                       |                   '-,COMPLETE-'   |   
                       '-(E,parameter_list-+-----------+-)-'   
                                           '-,COMPLETE-'       

>--+-------------------------------------+---------------------->
   |       (1)                           |   
   '-TOKEN----=-+-token_area-----------+-'   
                '-(token_area_pointer)-'     

>--+--------------------------------------------------+--------->
   |          (1)                                     |   
   '-COLLECTN----=-+-collection_name_area-----------+-'   
                   '-(collection_name_area_pointer)-'     

>--+------------------------------------------+----------------->
   |      (1)                                 |   
   '-NAME----=-+-object_name_area-----------+-'   
               '-(object_name_area_pointer)-'     

>--+----------------------------------------+------------------->
   |         (2)                            |   
   '-BUFLIST----=-+-buffer_list-----------+-'   
                  '-(buffer_list_pointer)-'     

>--+-------------------+---------------------------------------->
   |       .-PRIMARY-. |   
   '-VIEW=-+-BACKUP--+-'   
           '-BACKUP2-'     

>--+-----------------------------------------------+------------>
   '-OFFSET=-+-offset_of_starting_byte-----------+-'   
             '-(offset_of_starting_byte_pointer)-'     

>--+------------------------------------+----------------------->
   '-LENGTH=-+-number_bytes-----------+-'   
             '-(number_bytes_pointer)-'     

>--+-------------------------------------+---------------------->
   '-MSGAREA=-+-message_area-----------+-'   
              '-(message_area_pointer)-'     

>--+------------------------------------+----------------------->
   '-RETCODE=-+-return_code-----------+-'   
              '-(return_code_pointer)-'     

>--+------------------------------------+----------------------->
   '-REACODE=-+-reason_code-----------+-'   
              '-(reason_code_pointer)-'     

>--+-----------------------------------+------------------------>
   '-RECALL=-+-number_days-----------+-'   
             '-(number_days_pointer)-'     

>--+--------------------------------------+--------------------->
   '-RETCODE2=-+-return_code2-----------+-'   
               '-(return_code2_pointer)-'     

>--+--------------------------------------+--------------------><
   '-TTOKEN=-+-tracking_token-----------+-'   
             '-(tracking_token_pointer)-'     

1. These keywords must be specified on at least one of the forms if the MF=E does not indicate COMPLETE.
2. These keywords must be specified on at least one of the forms if the MF=E does not indicate COMPLETE. For each buffer specified in buffer_list, the length of the buffer must be specified. The variable buffer_list is described in Figure 1.

If the VIEW=PRIMARY function is requested, the object is copied from its place in the object storage hierarchy to the requester's virtual storage buffers that are specified in the BUFLIST keyword. When VIEW=BACKUP is specified, OAM attempts to retrieve the first backup copy of the object from backup optical or tape. When VIEW=BACKUP2 is specified, OAM attempts to retrieve the second backup copy of the object from backup optical or tape. If the specified VIEW function is requested but no object exists, return and reason codes reflect the error (see Reason codes) and no data is retrieved into the user's buffers.

You may retrieve a copy of the entire object (PRIMARY, BACKUP, or BACKUP2). Alternatively, you may retrieve a specified portion of the object, as defined by the OFFSET and LENGTH keywords. With adequate buffer space supplied by the application, RETRIEVE returns the entire object (or requested portion). If any errors occur during RETRIEVE processing, the buffer contents are invalid.

The RETRIEVE function can use the output from a successful OSREQ QUERY request by using the collection name length field (QELQECNL) as the parameter for the COLLECTN keyword, the object name length field (QELQEONL) as the parameter for the NAME keyword, and by supplying an input buffer of the size noted by object size (QELQEOS).

If you do not specify UPD=N on the CBRINIT statement in the IEFSSNxx parmlib member that is used during IPL, the last referenced date and pending action date of a retrieved object are updated to the current date. This schedules the retrieved objects for action during the next storage management cycle. During that cycle, objects may be placed in a different level in the storage hierarchy to meet new performance objectives, or the objects may not need any processing other than resetting their pending action dates.

If OAM cannot successfully retrieve the object and one or more backup copies exist, the application can use OSREQ RETRIEVE with VIEW=BACKUP or VIEW=BACKUP2 to retrieve the appropriate backup copy. The storage administrator may activate the automatic access backup function to obtain a backup copy of an object when the primary copy of the object is resident on removable media that is unreadable due to disaster or damage. See the z/OS DFSMS OAM Planning, Installation, and Storage Administration Guide for Object Support for more information on automatic access backup.

The RECALL keyword can be used to explicitly recall a full copy of an object from removable media to DB2 for the specified number of days at the time the object is retrieved. This can result in improved performance for subsequent retrieves of this object. Refer to z/OS DFSMS OAM Planning, Installation, and Storage Administration Guide for Object Support for more information on explicit and implicit recalls.

Upon successful completion of object recovery, you can use OSREQ RETRIEVE to retrieve the primary copy of the object.