RECORD and RECORDEND

The RECORD and RECORDEND data definitions allow logical grouping of a set of variables to make up a record. The record may be referenced by a single label in instructions supporting variable lists. It uses one of the following formats:

Where:

label

Optional. A Data Definition Label.

*

Optional. Denotes the item or file as being COMMON.

arraysize

Optional. An integer decimal constant, CONST variable or EQUATEd value indicating the number of array items.

^

Optional. Denotes the item as being a POINTER.

variable

Required. The name of a previously defined variable of the same type.

record

Required. The name of a previously defined RECORD.

Flags Affected: NONE

Note the following:

1. The basic record definition is defined by format (1). The data area is created and the record is placed in common if specified. If an array is specified, multiple copies of the record are created. The record definition also creates a record prototype definition with no record array information, since array information is not valid for the record prototype (format (2)).

2. The record prototype definition is defined by format (2). No data area is created at this time. COMMON and array information may not be specified with the DEFINITION clause.

3. Record definitions may be duplicated by using format (3). The LIKE clause defines the new data like the referenced definition. Any array information on the referenced record is ignored and the array information supplied with this definition is used. Nested record definitions can be accessed using the {parent_record}.{child_record}.variable format.

4. A shortcut method of referencing nested variables exist for labels that are not duplicated. If a variable A is defined in REC1 and REC1 is then nested in REC2, you may reference A by using REC2.A rather than the explicit form of REC2.REC1.A.

5. Each record must be terminated with a RECORDEND statement.

6. When a record array is specified, each element of the array contains the entire record and all fields are initialized to the value given in the definition.

7. Each item in a record may contain a label. This label must be unique to the record but may be duplicated in other records or data items in the program.

8. The only valid data items in a record are DIM, INIT, FORM, INTEGER, GUI Obects (10.6A), RECORD, or RECORDEND statements. Compiler directives may be included in the scope of a RECORD statement. Any individual item may be an array. Since RECORD is allowed as one of the items of the definition, this implies nested records.

9. The record definition defines whether the record is placed in COMMON or not. Either the entire record is in COMMON or none of the record is in COMMON.

10. If the DEFINITION clause is used, the label may only be referenced in another record statement that uses the LIKE clause.

11. If the LIKE clause is used, the label that is reference must be of a regular record definition or a record prototype definition. If a record array is desired, it must be specified at this time.

12. A ROUTINE, LROUTINE, FUNCTION, or LFUNCTION expecting a pointer to a RECORD as a parameter must pass in a pointer to a RECORD. Attempting to call the routine using a RECORD variable will result in an F05 runtime error. In addition, the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION will not have any knowledge of the structure of the incoming RECORD.

13. A pointer of this type can be used with any instruction that supports variable lists.

14. If the LIKEPTR clause (9.6A) is used, the {record} label that is referenced must be a previously declared record declaration or a previously declared record prototype definition. If a record array is desired, it must be specified at this time. All of the record members are created as variable pointers when the LIKEPTR clause is used. Also, the record member pointers are created as uninitialized pointers when the {record} is a record DEFINITION. Otherwise, the record member pointers are created and initialized to point to the corresponding member in the {record} structure.

15. When a RECORD item is a GUI object (10.6A), the behavior for PL/B instructions that allow a RECORD varlist reference can be affected as follows:

 

A GUI object record item is ignored for these instructions:

 

WRITE (FILE, AFILE, IFILE)

COUNT

DBFETCH

DBFETCHP

DBSEND

DISPLAY

EXTCALL

FILL

KEYIN

LOAD

MOVE

MOVELIST

PACK

PACKKEY

PRTPAGE

READ (FILE, AFILE, IFILE)

SET

STORE

 

A GUI object record item causes a runtime error for these instructions:

 

LOADADR //F5 error occurs in runtime if operand type mismatch found

UNPACK //F09 runtime error expected

 

A GUI object record item causes a compiler error for these instructions:

 

CLIPGET

CLIPSET

COMREAD

COMWRITE

MOVE Varlist, Varlistx

READ (XFILE)

STREAM

WRITE (XFILE)

 

A GUI object record item causes a behavior change for this instruction:

 

CLEAR //Modified to cause record GUI object items to be destroyed.

Example 1:

The above example defines a record that is 76 bytes in length. It may be referenced as a group in any statement where a list is valid.

Example 2:

The above statement changes the value of the ADDR field in the REC1 record.

Example 3:

The above statement generates an array of records, each formatted like REC1.

Example 4:

The above statement would define a record prototype exactly like REC1 butit would not define any data. It could only generate additional RECORD statements.

Example 5:

The above example shows nested records and how various fields would be accessed.

Example 6:

The above examples shows the use of the LIKEPTR clause. The sixth line defines ORGPTR that is a record of all pointer variables based on the ORG record template. The eighth line creates an array of three such records.

See Also: LIST, VARLIST, Data Definitions