1 12/18/84  get_vol_list_
 2 
 3 Function: allocates and returns two structures containing
 4 disk_table information.  One, pv_list, holds physical_volume
 5 information, the other, lv_list, holds logical volume
 6 information.
 7 
 8 The routine is supplied two pointers, initially null () and
 9 hopefully static.  It returns in them pointers to two
10 structures, for which it has allocated space.  If re-called,
11 with the same pointers, it will validate the storage addressed
12 to determine if it is the correct size and re-use it to hold
13 updated information if it is correct.  If not, it will free the
14 existing storage and re-allocate and fill in new structures.
15 
16 
17 Syntax:
18    declare get_vol_list_ entry (ptr, ptr, ptr, char(8), fixed bin(35));
19    call get_vol_list_
20         (pv_list_ptr, lv_list_ptr, area_ptr, version, code);
21 
22 
23 Arguments:
24    pv_list_ptr      (Input/Output)
25       is a pointer to the structure lv_info, as defined by
26       get_vol_list_.incl.pl1.  If the pointer is input as null,
27       storage will be allocated in the specified area for the
28       structure.  On exit this pointer will point to the pv_list
29       structure.
30    lv_list_ptr       (Input/Output)
31       is a pointer to the structure pv_info, as defined by
32       get_vol_list_.incl.pl1.  If the pointer is  null,
33       storage will be allocated in the specified area for the
34       structure.  On exit this pointer will point to the lv_list
35       structure.
36 
37    area_ptr         (Input)
38       if this pointer is null (), storage is allocated in
39       system_free_area.  If the pointer is non-null it is taken
40       as the pointer to an area for storage allocation.  The
41       area is validated prior to use.
42    version          (Input)
43       is the 8-character name of the current version of
44       get_vol_list_ structures.  This value is currently
45       "gvlist02".
46    code             (Output)
47       is a standard status code.
48 
49 
50 Notes: This subroutine allocates and frees storage as
51 appropriate.  The user's program should maintain the pointers
52 correctly to permit re-calling the routine to update
53 information.  The initial structure pointer values should be
54 null to cause first-time allocation of the storage.  A user
55 program can also free the data structures if it is cleaning up,
56 since they are self-describing and self-contained within a
57 single structure.  The area pointer of the area of allocation is
58 stored within the structures for easy reference.
59 
60 The area supplied is validated prior to use, and if the
61 information structures must be re-allocated, the area of their
62 current allocation is validated for freeing prior to an attempt
63 to free them and re-allocate.  If the area they were allocated
64 within does not permit freeing then their current storage space
65 is lost and they will simply be re-allocated in the currently
66 supplied area, without freeing the space of the current
67 allocation.