^MARRAY

Create an array by mapping a field or structure over a handle

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

array = ^MARRAY(field, handle)

Return value

array

An array of the same type as the field argument. (a or n)

Arguments

field

The data field or structure to map. The field cannot be dimensioned. (a or n)

handle

The memory handle that contains the data area to allocate. (n)

Discussion

^MARRAY maps a field or structure as many times as it can over the allocated area in handle and returns an array of descriptors. For example, if you allocate an area of size 12 and field is an a4, ^MARRAY will return an array of three (12/4) elements.

Because the memory backing the descriptors of this array is held by handle, the array should not have a lifetime longer than handle.

If handle is smaller than the field or structure being mapped on it (so not even one can fit), an $ERR_HSIZERR error will occur.

Examples

main
structure bob
    afield   ,a6
endstructure

structure bob1
    1fld     ,i1
    i2fld    ,i2
    i4fld    ,i4
    i8fld    ,i8
    d2fld    ,d2
    d4fld    ,d4
    d6fld    ,d6
    a2fld    ,a2
    a4fld    ,a4
    a6fld    ,a6
endstructure
			
record
    hand,D_HANDLE
			
proc
    open(15,o,'tt:')
    hand = %mem_proc(DM_ALLOC,12)
    xcall testa("bob",^marray(bob,hand))         ;2
    xcall testa("a2fld",^marray(a2fld,hand))	 ;6
    xcall testa("a4fld",^marray(a4fld,hand))	 ;3
    xcall testa("a6fld",^marray(a6fld,hand))	 ;2
    
    xcall testi("i2fld",^marray(i2fld,hand))     ;6
    xcall testi("i4fld",^marray(i4fld,hand))	 ;3
    xcall testi("i8fld",^marray(i8fld,hand))	 ;1
    
    xcall testd("d2fld",^marray(d2fld,hand))     ;6
    xcall testd("d4fld",^marray(d4fld,hand))	 ;3
    xcall testd("d6fld",^marray(d6fld,hand))	 ;2
end
			
    subroutine testa
    parm1    ,a
    parm2    ,[*]a

proc
    writes(15, parm1+" args="+%string(^argdim(^argnum(parm2),1)))
    xreturn
end
			
subroutine testi
    parm1   ,a
    parm2   ,[*]i
			
proc
    writes(15, parm1+" args="+%string(^argdim(^argnum(parm2),1)))
    xreturn
end
			
subroutine testd
    parm1   ,a
    parm2   ,[*]d

proc
    writes(15, parm1+" args="+%string(^argdim(^argnum(parm2),1)))
    xreturn