USING FORMSPEC TO CREATE AN ARB

• Live fields exist on both the screen and the ARB.

• Filler fields exist on the ARB only; for example, alignment and accumulator fields.

Table 3-11 “Form/ARB Relationships” shows how an alteration made to the form will affect the ARB, if at all.

The Effect of Renaming a Field on a Form

There are three possibilities, which are described below.

• The old name is in the ARB but the new name is not: The ARB field is renamed to the new name, retaining its "live" field type, and the screen length and screen type are altered if necessary.

• The old name is not in the ARB, but the new name is, as a "filler" field: The ARB field changes from "filler" to "live" field type, and the screen length and screen data type are updated if necessary.

• Both old and new names exist in the ARB: The old name changes from "live" to "filler" type, and the screen length and screen data type change to zero and blanks respectively. The new name changes from "filler" to "live" field type, and the screen length and screen data type are updated.

	NOTE: FORMSPEC allows the designer to delete a field from a form after a corresponding field has been added to the ARB. The field need not be deleted from the ARB as well; at compile-time, the ARB field is converted to a "filler" field, with screen length set to zero and screen type blank. The designer can; however, choose to delete or rename the ARB field. It is possible, though usually not advisable, to create an ARB without using the GENerate feature. To do this, type RES and use the Restructure ARB Menu to add fields one at a time.

If your default conversion for any field(s) could cause run-time errors, you will get a message to that effect (see Appendix B, VPLUS ERROR MESSAGES). Go to the ARB Field Menu to check that the conversion does make sense in this case, or to change the target datatype if it doesn't.

3. Enter GEN in the Selection box and press ENTER to generate an ARB for this form. The "No field(s) in ARB" changes to show a number equivalent to the number of fields on the form.

4. You can now change the position of a field in the ARB, add or delete fields, or modify a field by changing its length and/or data type.

5. To move, rename, add or delete fields, type RES in the Selection box and press ENTER. The Restructure ARB menu is displayed.

   This menu displays all the fields in the ARB by name and in sequence. The form name is displayed in the first field (display only). The lower part of the screen shows the ARB fields. Use PREV PAGE and NEXTPAGE to view them all if necessary.

   	NOTE: ARB changes do not propagate to form family members. Changes impact the current form only.

   Figure 3-29 Restructure ARB Menu

6. Use the fields at the top of the screen to change the order by moving fields or ranges. Press ENTER to execute all changes.

The programmer is responsible for:

If you use a language whose compiler pads to ensure word alignment for integers, you must pad your ARB correspondingly. For example, suppose you are coding in Pascal and you declare a record that looks like this:

ODD_BYTE_EXAMPLE = RECORD
  THREE_BYTES    : PACKED ARRAY [1..3] OF CHAR;
   GOTCHA         : INTEGER
     .
     .
   END;

The Pascal compiler will insert an additional byte after THREE_BYTES to align the integer on a word boundary. You must do the same with the ARB record; use the ARB LAYOUT screen to add a filler field after the three-byte field so that the ARB looks like this:

Field Name                ARB Type                 ARB Length
 
  DEPT                     CHAR                          3
 
  FILLER1                  CHAR                          1
 
  TOTAL PURCHASES          DINT                          4

The ARB trace facility may be enabled by setting the JCW VPLUSARBTRACE to 1. This will print trace messages to the stdlist. You may direct VPLUS screens to a different device by using a FILE command to set the device of the filename used by VOPENTERM to a device other than the stdlist device.

This is an example of a trace from a form that has seven fields.

:SETJCW VPLUSARBTRACE,1
   :FILE VTERM;DEV=99
   :RUN ARBPROG
 
Field 1    : Buffer offset from 0 = 1
                            Length = 2
                              Type = INT
                             Value = 1234
 
Field 2    : Buffer offset from 0 = 3
                            Length = 2
                              Type = INT
                             Value = 1234
 
Field 3    : Buffer offset from 0 = 6
                            Length = 2
                              Type = INT
                             Value = 1234
 
Field 4    : Buffer offset from 0 = 9
                            Length = 4
                              Type = DINT
                             Value = 12345678
 
Field 5    : Buffer offset from 0 = 14
                            Length = 4
                              Type = DINT
                             Value = -1234567
 
Field 6    : Buffer offset from 0 = 19
                            Length = 4
                              Type = DINT
                             Value = 12345678
 
Field 7    : Buffer offset from 0 = 23
                            Length = 8
                              Type = CHAR
                             Value = ABCDEFGH
 
END OF PROGRAM
:

The trace provides the following information. It shows:

	NOTE: This ARB is tied to seven form fields, but there are gaps in the buffer before field 1, and between each field from 2 to 6. These gaps are one-byte filler fields.