^M

Map a structure to a data area

^M([structure_field, ]data_area)

Arguments

structure_field

(optional) The structure to map and the data field to access. It can be any valid field expression based on a field within a structure declaration. It can have multiple path elements, any of which can be dimensioned, and the field can be indexed, dimensioned, ranged, and so forth.

data_area

The data area to be referenced. It can be any valid Synergy DBL variable or memory handle. If this expression is alpha, the data area referenced is exactly that of data_area. If it is numeric, its value is considered to be a memory handle whose associated memory segment is the data area to reference. (a or n)

Discussion

^M “maps” a structure to a data area or memory handle and then accesses a field from within that data structure.

The result of this operation is a field whose data type and size is the same as structure_field and whose location (and, therefore, contents) is determined by the data area reference by data_area.

Semantically, this operation does three things:

The structure whose field is used in structure_field is logically “aligned” to the first character of the data area specified by data_area.
Based on this alignment, the logical position and length of the field represented by structure_field are determined.
If the position and size lie entirely within the referenced data area, a descriptor is generated that references this data field. If the position and size lie outside the data area, a “Map outside bounds of field or handle” error ($ERR_HSIZERR) is generated.

If data_area is numeric but is not a memory handle, an “Invalid memory handle” error ($ERR_INVHDL) is generated.

If data_area is the only argument, the entire allocated memory area is accessed. If the size of the memory accessed is greater than 65,535 bytes, a “Map outside bounds of field or handle” error ($ERR_HSIZERR) is generated.

On a 32-bit machine, once a string's size exceeds 65,535, the string is no longer directly interchangeable with alpha data, and an $ERR_HSIZERR error is generated if you attempt to store or convert such a string to alpha. Therefore, if you use string data in the place of an alpha argument or variable, you must use ranging to ensure the resultant size does not exceed 65,535.

Report handles, pen handles, RCB handles, and NET handles cannot be used as a memory handle with ^M to access the associated memory.

In Synergy .NET, passing ^M(structure_field, data_area) to a pseudo array or real array argument will result in an array of structure_field whose dimension is determined by the number of these fields that will fit in the memory area. Note that you cannot pass a ^M value that would result in a pseudo array of structures as an argument to a parameter, because a pseudo array of structures is not allowed as a parameter type. D_ADDR is not supported for use with ^M or arguments to functions that take ^M; use D_HANDLE instead. ^M cannot be used on a global structure that is defined in a referenced assembly.

Examples

record
    hnd         ,D_HANDLE
    var         ,i4
structure str
    fld1        ,i4
    fld2        ,i4
proc
    hnd = %mem_proc(DM_ALLOC, ^size(str))
    clear ^i(^m(hnd))                           ;Clear entire structure
    var = ^m(str.fld2, hnd)
    ^m(str.fld1, hnd) = var
    hnd = %mem_proc(DM_FREE, hnd)               ;Release memory
.end