BASED V.ARIABLES AND POINTER VARIABLES
DECLARE 0 OFFSET(A), P POINTER;
P=NULL;
O=P;
O=NULLO;
P=O;
Th'3 second and fourth assignments in the above example would be invalid. They could be made valid by inserting IF statements,.
such as the following:
IF P=NULL THEN O=NULLO;
ELSE O=P;
AREA ASSIGNMENT AND I NPUT/OUTPU'I'
The value of an area expression can be assigned to one or more area variables by an assignment statement. Area-to-area assignment has the effect of freeing all allocations in the target area and then assigning the extent of the source area to
t~he target area, in such a way that all allocations in the source area maintain their locations relative to each other;
that is. any gaps left by freeing opera-tions in the source area are maintained during the assignment (such a gap might have been left. for example, if the second of three contiguous allocations had been freed; if the gaps were automatically closed up, some offset values might lose t,heir meaning).
If a source area containing no alloca-tions is assigned to a target area. the effect is merely to free all allocations in t,he target area.
A possible use for area assignment is to allow for expansion of a list of based
va~iables beyond the bounds of its original area. When an attempt is made to allocate a based variable within an area that con-tains insufficient free storage to accommo-date it, the AREA condition is raised (see below). The on-unit for this condition could be to change the value of a pointer qualifying the reference to the inadequate area, so that i t pointed to a different area; on return from the on-unit, the allocation would be attempted again, within the new area. Alternatively, the on-unit 'could write out the area and reset it to EMPTY.
The EMPTY Built-in Function
The EMPTY built-in function requires no arguments and returns an area of zero size and extent. The effect is to free all allocations in the target area.
Example:
DECLARE A AREA, I BASED (P),
J BASED(Q);
ALLOCATE I IN(A), J IN (A);
A=EMPTYi
/*EQUIVALENT TO:
FREE I IN (A), J IN (A); */
The AREA ON-Condition
The AREA condition is raised in any of t,he following circumstances:
1. When an attempt is made to allocate a based variable within an area that contains insufficient free storage for the allocation to be made.
2. When an attempt is made to perform an area assignment, and the target area contains insufficient storage to acco-modate the extent of the source area.
3. When a SIGNAL AREA statement is exe-cuted.
The ONCODE built-in function can be used to determine whether the condition was raised by an allocation. an assignment. or a SIGNAL statement.
On normal return from the on-unit.. the action is as follows:
1. If the condition was raised by an allocation, the allocation is re-attempted. If the on-unit has changed the value of a pointer qualifying the reference to the inadequate area so that i t points to another area, the allocation is reattempted within the new area. Note that if the on-unit does not effectively correct the fault, a loop may result.
2. If the condition was raised by an area assignment., or by a SIGNAL statement, execution continues at the point of interrupt.
If no on-unit is specified, the system will comment and raise the ERROR condition.
The area facility is designed to allow easy input and output of complete lists of based variables as one unit, to and from RECORD files. The control information is transmitted with the area. Consequently, the record length required is governed by the area length (i.e., area size + 16): the RECORD condition is raised if the length of an area named in the INTO option of a READ sta·tement, or in the FROM option of a WRITE sta"tement, differs from the relevant record length. Note that even though the RECORD condition is raised., incorrect control information will be transmitted; when an area is' written out, i t must not be read back into an area of different size.
In the case of READ with SET, the length of ·the input area in the buffer is equal to the length of the area used to create the reco.rd.
ARE.A AND OFFSET DEFINING
An offset can be defined on an offset, using overlay or correspondence defining.
In the declarations of the defined offset and the base offset, the variables named in the two OFFSET atttributes need not be the same.
Similarly, an area can be defined on an area, using overlay or correspondence defining. The base area must have a size equal to that of the defined area.
174
COMMUNICATION BETWEEN PROCEDURES
Similarly to variables of other data
types~ locator and area variables in one procedure can be related to those in anoth-er procedure by means of argument.s and parameters, and the ~eneral rules are as described in Chapter 10, "Subroutines and Functions." There are necessarily some r:estrictions, which will be explained in the following discussion; but a gE!neral rule is that where it is possible to assign the value of one variable to another varia-lole, i t is also possible to relate the two variables by an argument and a paramet~er.
ARGUMENTS AND PARAMETERS
A locator argument of either pointE!r or offset type can be passed to a locator parameter only. The parameter can be of either type, but if the argument type differs from the parameter type" a dummy argument is created by the compiler" and a change in the value of the parameter will not be reflected in the value of the original argument.
Pointer to Pointer
No conversion is necessary when a poin-ter argument is passed to a poinpoin-ter param-eter; normally" therefore, no dummy argu-ment is created~ and a change in the value of the parameter will be reflected in the value of the argument. Note, howeverfl that this reflected change could be avoidE~d" if necessary" by passing the argument as an expression in parentheses: this causes a dummy argument to be created. For example:
PROC1: PROCEDURE;
DECLARE (P , Q) POINT1!:R;
CALL PROC2«P).Q);
PROC2: PROCEDURE(R,S);
DECLARE (R,S) POINTl!:R;
END PROC1;
In this example, a change in the value of S will be reflected in the value of Q, but; a change in the value of R will have no effect on p .•
Offset to Pointer
Passing'an offset argument to a pointer parameter implies conversion to a dummy pointer argument, which is then passed to the en1:ry point. The entry must be declared with the POINTER attribute in the parameter attribute list. For example:
PROC3: PROCEDURE;
DECLARE PROC4 ENTRY (POINTER) ,
o OFFSET (A) , A AREA BASED(P);
CALL PROC4 (0) ;
PROC4: PROCEDURE(Q);
DECLARE Q POINTER;
END PROC3;
In 1:his example, the values of P and 0 are used to obtain the value of the dummy pointer argument to be passed to PROC4.
Offset to Offset
When an offset argument is passed to an offset parameter~ variables named in the OFFSET attribute of the offset declarations are ignored~ just as they are ignored for offset assignment; if they differ, the fact that they differ does not imply conversion to a dummy argument. For example:
PROC5: PROCEDURE;
DECLARE OA OFFSET(A), A AREA BASED(P), B AREA BASED(Q), •••
CALL PROC6(OA);
PROC6: PROCEDURE(OB);
DECLARE OB OFFSET( B) , •••
END PROCS;
In this example, OA would be passed directly to OB.
Pointer to Offset
Passing a pointer argument to an parameter implies conversion to
offset a dummy
offset argument, which is then passed to the entry point. The entry must be declared with the OFFSET attribute in the parameter attribute list., and the two OFF-SET attribute specifications must name the same variable. For example:
PROC7: PROCEDURE;
DECLARE PROC8 ENTRY (OFFSET(A», P POINTER,
A AREA BASED(Q);
CALL PROC8 (P) ; PROC8: PROCEDURE(O)i
DECLARE OOFFSET(A);
END PROC7;
In this example, the values of P and Q are used to obtain the value of the dummy offset argument to be passed to PROC8.
The variable follo~ing the keyword OFF-SET is not considered during selection of a generic entry point.
Area to Area
An area argument can be passed only to an area parameter. If the size of the argument differs from the size appearing in the parameter attribute list of the rele-vant entry declaration, the argument is first assigned to a dummy area argument with the size specified in the entry dec-laration; the dummy argument is then passed to the entry point.
The size of an area considered during selection entry point.
RETURNS FROM ENTRY POINTS
argument is not of a generic
An entry point can return a locator value or an area; hence, the PROCEDURE and ENTRY statements and the RETURNS attribute may specify the POINTER, OFFSET, or AREA attributes.
Locator Returns
Either type of locator variable can appear in a RETURN statement in a procedure that returns a locator value. If the
procedure is to return an offset value but the RETURN statement specifies a pointer, there is implicit conversion to offset, and vice versa. For example:
PROCA: PROCEDURE POINTER;
DECLARE A AREA BASEDCP),
o
OFFSET (A) ;RETURN (0);
END PROCAi
The values of 0 and P are used to obtain the pointer value to be returned.
PROC3: PROCEDURE OFFSET(B);
DECLARE B AREA BASED(Q), R POINTER;
RETURN CR);
END PROCB;
The values of Q and R are used to obtain the offset value to be returned. Note that the OFFSET attribute is specified in the PROCEDURE statement complete with the name of the relevant area variable; the keyword OFFSET alone is not sufficient.
Similarly, a locator value returned by a function may undergo implicit conversion.
For example:
DECLARE 0 ENTRY RETURNSCOFFSET(A»,