Basing Pointer Data Type

Basing pointers are used to locate the storage for based variables. The storage is accessed by defining a field, array, or data structure as based on a particular basing pointer variable and setting the basing pointer variable to point to the required storage location.

For example, consider the based variable MY_FIELD, a character field of length 5, which is based on the pointer PTR1. The based variable does not have a fixed location in storage. You must use a pointer to indicate the current location of the storage for the variable.

Suppose that the following is the layout of some area of storage:

-------------------------------------------------------------
| A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
-------------------------------------------------------------

If we set pointer PTR1 to point to the G,

   PTR1-------------------.
                          |
                          V
-------------------------------------------------------------
| A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
-------------------------------------------------------------

MY_FIELD is now located in storage starting at the 'G', so its value is 'GHIJK'. If the pointer is moved to point to the 'J', the value of MY_FIELD becomes 'JKLMN':

               PTR1-------------------.
                                      |
                                      V
-------------------------------------------------------------
| A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
-------------------------------------------------------------

If MY_FIELD is now changed by an EVAL statement to 'HELLO', the storage starting at the 'J' would change:

               PTR1-------------------.
                                      |
                                      V
-------------------------------------------------------------
| A | B | C | D | E | F | G | H | I | H | E | L | L | O | O |
-------------------------------------------------------------

Use the BASED keyword on the definition specification (see BASED(basing_pointer_name)) to define a basing pointer for a field. Basing pointers have the same scope as the based field.

The length of the basing pointer field must be 16 bytes long and must be aligned on a 16 byte boundary. This requirement for boundary alignment can cause a pointer subfield of a data structure not to follow the preceding field directly, and can cause multiple occurrence data structures to have non-contiguous occurrences. For more information on the alignment of subfields, see Aligning Data Structure Subfields.

The default initialization value for basing pointers is *NULL.

Note:

When coding basing pointers, you must be sure that you set the pointer to storage that is large enough and of the correct type for the based field. Figure 101 shows some examples of how not to code basing pointers.

Note:

You can add or subtract an offset from a pointer in an expression, for example EVAL ptr = ptr + offset. When doing pointer arithmetic be aware that it is your responsibility to ensure that you are still pointing within the storage of the item you are pointing to. In most cases no exception will be issued if you point before or after the item.

When subtracting two pointers to determine the offset between them, the pointers must be pointing to the same space, or the same type of storage. For example, you can subtract two pointers in static storage, or two pointers in automatic storage, or two pointers within the same user space.

Note:

When a data structure contains a pointer, and the data structure is copied to a character field, or to another data structure that does not have a pointer subfield defined, the pointer information may be lost in the copied value. The actual 16-byte value of the pointer will be copied, but there is extra information in the system that indicates that the 16-byte area contains a pointer; that extra information may not be set in the copied value.

If the copied value is copied back to the original value, the pointer may be lost in the original value.

Passing a data structure containing pointers as a prototyped parameter by read-only reference (CONST keyword) or by value (VALUE keyword) may lose pointer information in the received parameter, if the parameter is prototyped as a character value rather than using the LIKEDS keyword. A similar problem can occur when returning a data structure containing a pointer.

[ Top of Page | Previous Page | Next Page | Contents | Index ]