!   TITLE:  arry_transpose.mac (MANAGEMENT)
!
!
!   OBJECTIVE:
!
!   This sub-macro transposes the specified contents of an array to a new or
!   existing array of a user-specified name.
!
!
!   COMMAND SYNTAX:
!
!     --NEW ARRAY:
!
!                          (1)       (2)     (3) (4) (5) (6) (7) (8)
!        ARRY_TRANSPOSE, 'source', 'target', ri, rf, ci, cf, pi, pf
!
!
!                                                 (9)  (10)  (11)
!     --EXISTING ARRAY (additional arguments):   ri_t, ci_t, pi_t
!
!
!   ARGUMENTS:
!
!       (1) source = the origin (source) array name (in single quotes)
!
!       (2) target = the name of the new or existing array to transfer the
!                    transposed elements to (in single quotes).
!
!       (3,4) ri/rf = initial/final row index:
!                     -If both are 0 (or blank) or out-of-range, all rows are
!                       queried.
!                     -If either one is 0 (or blank), or out-of-range, and the
!                       other is in-range, then only that row (in-range value)
!                       is queried.
!                     -If both are in-range and not equal, then the range is
!                       from lowest to highest (independent of order).
!
!       (5,6) ci/cf = initial/final column index:
!                     -If both are 0 (or blank) or out-of-range, all columns
!                       are queried.
!                     -If either one is 0 (or blank), or out-of-range, and the
!                       other is in-range, then only that column (in-range value)
!                       is queried.
!                     -If both are in-range and not equal, then the range is
!                       from lowest to highest (independent of order).
!
!       (7,8) pi/pf = initial/final plane index:
!                     -If both are 0 (or blank) or out-of-range, all planes
!                       are queried.
!                     -If either one is 0 (or blank), or out-of-range, and the
!                       other is in-range, then only that plane (in-range value)
!                       is queried.
!                     -If both are in-range and not equal, then the range is
!                       from lowest to highest (independent of order).
!
!       If the target array exists, then the following additional arguments
!       (9 thru 11) must be specified as the initial target locations within that
!       array:
!
!       (9) ri_t = initial row index. If left blank, the target initial row
!                  value defaults to 1.
!
!       (10) ci_t = initial column index. If left blank, the target initial
!                   column value defaults to 1.
!
!       (11) pi_t = initial plane index. If left blank, the target initial
!                   plane value defaults to 1.
!
!
!   DESCRIPTION:
!
!   The Transpose of elements in an array is defined as assigning the indices
!   of the extracted elements according to the following rule:
!
!                               B(i,j,k) = A(j,i,k)
!
!       where, B is the target array and A is the source array; and i, j and k
!       are the row, column and plane indices of the target array.
!
!   This is the same mathematical definition used for the transpose of a
!   matrix in Linear Algebra.
!
!   The contents of the source array to be extracted and transposed are
!   specified in arguments 3 thru 8. The contents are then transposed and
!   written into the specified target array, if it exists.
!
!   If the target array does not exist, then the new target array will be
!   created and the specified contents of the source array will be transposed
!   to it. Therefore, the dimensions of the target array will acommodate the
!   size of the transferred data. Arguments 9 through 11 are ignored.
!
!   If the target exists, then the specified contents of the source array will
!   be transposed to it. In this case, arguments 9 through 11 may be specified.
!   The transposed contents of the source array will be transferred to the
!   target array beginning with the specified inital row column and plane values.
!   The dimension of the target array must accomodate the dimensions of the
!   transferred data. If 9 through 11 are left blank, the the default values
!   for ri_t, ci_t and pi_t default to 1.
!
!   If arguments 3 through 8 are left blank, then the entire contents (and
!   therefore its full dimensions) will be transferred to the target array.
!
!
*get,prkey_,active,0,prkey
/nopr
!
snam__=arg1
tnam__=arg2
rinit__=arg3
rfin__=arg4
cinit__=arg5
cfin__=arg6
pinit__=arg7
pfin__=arg8
rtinit__=arg9
ctinit__=ar10
ptinit__=ar11
!
!
!                         (1)       (2)    (3) (4) (5) (6) (7) (8)
!        ARRY_TRANSFER, 'source', 'target', ri, rf, ci, cf, pi, pf
!
!
arry_transfer,snam__,'arryhld_',rinit__,rfin__,cinit__,cfin__,pinit__,pfin__
!
*get,rsiz__,parm,arryhld_,dim,x
*get,csiz__,parm,arryhld_,dim,y
*get,psiz__,parm,arryhld_,dim,z
!
*dim,arrytp_,array,csiz__,rsiz__,psiz__
!
*do,piter_,1,psiz__,1
    *do,citer_,1,csiz__,1
        *do,riter_,1,rsiz__,1
            arrytp_(citer_,riter_,piter_)=arryhld_(riter_,citer_,piter_)
        *enddo
    *enddo
*enddo
!
arry_transfer,'arrytp_',tnam__,,,,,,,rtinit__,ctinit__,ptinit__
!
*set,arryhld_(1),
*set,arrytp_(1),
*set,riter_,
*set,citer_,
*set,piter_,
*set,rsiz__,
*set,csiz__,
*set,psiz__,
*set,snam__,
*set,tnam__,
*set,rinit__,
*set,rfin__,
*set,cinit__,
*set,cfin__,
*set,pinit__,
*set,pfin__,
*set,rtinit__,
*set,ctinit__,
*set,ptinit__,
!
*if,prkey_,eq,1,then
    /go
*endif