HP 3000 Manuals HP 3000 Manuals
Appendix F JOINFORM
JOINFORM Statements
JOINFORM is a FORMS/260 compatible forms package available in HP Business
BASIC/XL. The JOINFORM package cannot be accessed by any other languages
on the HP 3000. Use of JOINFORM is supported only on the HP150 and
HP239X Terminals. It is intended to provide an easy-to-use alternative
to VPLUS forms for HP260 users converting their applications.
OPEN FORM
OPEN FORM opens a form file. It tries to find form_member_name in
form_file_name if a form file is specified. Otherwise it searches the
currently open, default form file. If the specified form exists, it is
displayed at the current cursor position. Form names are limited to
eight characters.
If a form is already active when OPEN FORM is executed, it is deactivated
and the new form is inserted at the cursor position.
The Keywords HOME, OVERLAY, APPEND, and FREEZE have no effect when a
JOINFORM is opened.
Syntax
[HOME ]
[OVERLAY]
OPEN FORM form_name [;] [FREEZE ]
[APPEND ]
Parameters
form_name Form_name is a string expression with the following format:
form_member_name [:form_file_name]
Form_member_name is the name of the form you are opening.
Form_file_name is a quoted string literal that is the name of
the file that contains the form.
HOME The HOME, OVERLAY, FREEZE, and APPEND options are ignored if
OVERLAY the form to be opened is a JOINFORM.
FREEZE
APPEND
Examples
130 OPEN FORM "Appl1"
140 OPEN FORM Form2
150 OPEN FORM Form$
160 OPEN FORM "form1:joinfile"
CLEAR FORM
CLEAR FORM clears all input and output field entries on the form. The
form is not drawn on the screen. The input, output, and cursor field
pointers are reset to the first input and first output field. The cursor
is placed in the first input field. If the form does not have input
fields, the cursor is placed in the left upper corner.
The optional keyword [ [WITH] DEFAULT[S] ] has no effect for converted
JOINFORM. It is ignored.
If there is no active form, CLEAR FORM returns an error.
Syntax
CLEAR FORM [[WITH] DEFAULT[S]]
Examples
150 CLEAR FORM !Clears all fields
CLOSE FORM
CLOSE FORM deactivates and erases the form that is currently active. If
no option is specified, the form is erased by deleting all lines occupied
by the form, so the lines following the form are moved up on the screen.
Use the CLEARREST option to clear the form by clearing display memory
from the first line of the form to the end of display memory. Use the
CLEARALL option to clear the form by clearing all of display memory. Use
the REMAIN option to deactivate a form without erasing it.
If the cursor is in the form when CLOSE FORM is called, it is positioned
to the line that followed the form. If the cursor is outside of the
form, it is positioned to the same line again after the form is deleted.
If no form is active, CLOSE FORM returns immediately without performing
any action.
Syntax
[{;} ]
[{,} CLEARREST]
CLOSE FORM [CLEARALL ]
[REMAIN ]
Examples
90 CLOSE FORM
100 CLOSE FORM ;CLEARREST
110 CLOSE FORM ;CLEARALL
120 CLOSE FORM ;REMAIN
CURSOR
The CURSOR statement positions the terminal cursor within an active
JOINFORM. When positioning the cursor while a JOINFORM is active two
parameters must be supplied. The first parameter is either CFLD, IFLD,
OFLD, SETCFLD, SETIFLD, or SETOFLD. This parameter specifies the type of
field that the cursor is being moved into. The second argument is the
number of the field of that type on the form. 'CURSOR OFLD (5)' means
"position the cursor to the fifth output field within the defined output
order of the active form". The SETCFLD, SETIFLD, and SETOFLD parameters
set the internal field pointer, as do the CFLD, IFLD, and OFLD
parameters, but they do not move the cursor. A subsequent INPUT, DISP,
or PRINT statement will move the cursor to the desired field before the
input or output operation takes place. There is a performance
improvement because the cursor is not moved. CFLD stands for cursor
field and IFLD stands for input field.
The IFLD, OFLD, CFLD, SETCFLD, SETIFLD, and SETOFLD options of the CURSOR
statement cannot be executed unless a JOINFORM is active.
Syntax
{IFLD }
{OFLD }
{CFLD }
CURSOR {SETIFLD} (field_number)
{SETOFLD}
{SETCFLD}
Parameters
IFLD, OFLD, A keyword that specifies the type of field the cursor
CFLD moves into.
SETIFLD, A keyword that sets the internal field pointer for the
SETOFLD, type of field indicated.
SETCFLD
field_number The number of the field that the cursor will move to.
Examples
100 CURSOR OFLD (35) !Moves cursor to output field 35.
110 CURSOR SETIFLD (4) !Sets the input field pointer to field 4.
TFLD
TFLD is a built-in numeric function that returns the field number of the
last input field accessed in the form. The cursor pointer is moved
either by a CURSOR IFLD(), CFLD(), or an INPUT statement.
NOTE The actual cursor position and fieldnum returned to TFLD are only
identical when the fields were walked through using the RETURN key.
The TAB key moves the cursor to the next field (or the previous
field when BACKTAB is pressed) in screen order. This is not
recognized by TFLD since TAB and BACKTAB are local to the terminal.
TFLD also does not recognize moving the cursor using the cursor
positioning keys.
TFLD returns zero if executed when no JOINFORM is active.
Syntax
TFLD
PRINT and DISP
PRINT and DISP are standard HP Business BASIC/XL statements. Their
syntax is exactly the same for normal output and output to JOINFORM.
However, if a form is active, HP Business BASIC/XL calls a special forms
output routine that behaves like a PRINT or DISP statement on the HP260
does. If a ", " is used to separate the items, each item is displayed in
a separate field. If a "; " is used to separate them, then the output is
buffered and displayed when a ", " is found or the statement is
completed. The first field that an item is to be displayed in is defined
by the output field pointer. The output field pointer can be positioned
with the CURSOR OFLD statement. After an item is displayed in a field,
the output field pointer is incremented.
The syntax for the PRINT and DISP statements are in chapter 4.
LDISP
The result of an LDISP statement depends on whether a form is active.
When no JOINFORM is active, the current line is cleared from the current
cursor position to the end of the line. Output of the values of the
output_item begins at the current cursor position on the screen. If the
output requires more than the number of characters remaining on the
cleared line, additional lines on the screen are used. However, the
additional lines are not cleared before character output begins.
If a JOINFORM is active, the form is then inactivated. The cursor is
repositioned to the first column of the first line following the form.
Output then proceeds as if no JOINFORM were active. Following output,
the cursor does not return to its previous position in the now inactive
form. If the cursor is already outside the form, LDISP behaves as if no
JOINFORM were active.
Syntax
LDISP [d_list]
Parameters
[{,...} ]
d_list [,]...output_item_list [{; } output_item]...
output_item One of the following:
num_expr
str_expr
array_name(*) Array reference. See "Array References
in the Output Item List" in chapter 6
for more information.
{PAGE }
{{CTL} }
output_function {{LIN} }
{{SPA} (num_expr)}
{{TAB} }
See "Output Functions in the Display
List" in chapter 6 for more
information.
FOR_clause (FOR num_var=num_expr1 TO num_expr2
[STEP num_expr3], d_list)
See "FOR Clause in Output Item List" in
chapter 6 for more information.
Examples
Assume that the following program statements are executed while a form is
active:
10 V$="Hi there."
20 DISP V$ !Prints in form field
30 LDISP V$ !Prints outside form
INPUT
When an INPUT statement is executed while a JOINFORM is active, the
cursor is placed in the current cursor field. You can input data until
RETURN is pressed. If no input elements are specified, only the cursor
field pointer is increased. Otherwise, the entered data is assigned to
the variables in the input item list. Following the assignment, the
cursor field pointer and the input field pointer are increased.
If the cursor field pointer already points to the last input field in the
form, it is reset to the first input field of the form. In contrast, the
input field pointer is not circularly reset to the first input field but
left undefined. Any further assignments from fields to variables result
in errors.
The cursor can be explicitly positioned within the currently active form
by using a previously executed CURSOR CFLD, CURSOR SETCFLD, CURSOR IFLD,
or CURSOR Setifld statement.
When an INPUT statement is executed and a JOINFORM is not active, INPUT
behaves normally.
Prompts in the INPUT and LINPUT statements are not printed when a
JOINFORM is active.
The syntax for the INPUT statement is in chapter 4.
LINPUT
When LINPUT is executed and a JOINFORM is active, the current cursor
position in screen memory is determined. If the cursor is within the
form, LINPUT moves it to the first unprotected line following the form.
Otherwise, the cursor stays where it is (usually positioned by a
previously executed CURSOR statement). Then LINPUT outputs a line-output
prompt. When RETURN is pressed, only what has been typed in is assigned
to the string variable in the LINPUT statement. Input and output field
pointers are not affected.
When the LINPUT statement is executed and a JOINFORM is not active,
LINPUT behaves normally. The syntax for the LINPUT statement is in
chapter 4.
ENTER
When ENTER is executed and a JOINFORM is active, the content of the
current input field is assigned to the first element in the variable
list. If there are more input fields on the form, the input field
pointer is incremented to point to the next JOINFORM field. If an
additional element is present in the ENTER statement's variable list, the
value of the field is assigned to that variable. The input is read
directly from the JOINFORM field. Input from the user is not accepted.
Assignment to the variables in the variable list continues until values
have been assigned to each. If no more JOINFORM input fields are present
on the form, but one or more variables exist on the ENTER statement's
variable list, an error occurs.
The cursor can be positioned within the currently active form by using a
previously executed CURSOR IFLD statement.
When the ENTER statement is executed and a JOINFORM is not active, ENTER
behaves as described in chapter 4.
The syntax for the ENTER statement is in chapter 4.
LENTER
When LENTER is executed and a JOINFORM is active, the current cursor
position in screen memory is determined. If the cursor is within the
form, an error occurs immediately. Otherwise, the current line is input
at once without waiting for a keystroke. The cursor can be positioned
out of the currently active form by a previously executed CURSOR
statement. Input and output field pointers are not affected.
When the LENTER statement is executed and a JOINFORM is not active,
LENTER behaves as described in chapter 4.
The syntax for LENTER is in chapter 4.
ACCEPT
Input without an echo on the terminal is possible at any time, even if a
JOINFORM is active. The ACCEPT statement has no specific interaction
with JOINFORM. The ACCEPT statement is explained in chapter 4.
BB_BLOCK_READ
The routine BB_BLOCK_READ is an HP Business BASIC/XL run-time library
routine that has been provided to improve application performance.
JOINFORM requires a significant amount of terminal I/O, slowing down
performance. The BB_BLOCK_READ routine does a full-screen block-mode
read of the currently active JOINFORM, improving performance.
BB_BLOCK_READ resides in the HP Business BASIC/XL library segment in
XL.PUB.SYS.
Before using BB_BLOCK_READ, be aware of the following considerations:
* BB_BLOCK_READ can lead to hard-coding dependencies on form layout
(such as field length and order).
* BB_BLOCK_READ reads all unprotected fields on the screen each time it
is called; input and input/output JOINFORM fields are read.
* The characters from the fields are read into a single string. The
string must be large enough to hold all data from all fields plus one
byte per field as a record separator.
* The application must explicitly extract the fields and convert them
into usable data from the string.
Syntax
To call BB_BLOCK_READ from HP Business BASIC/XL, declare it as an
external routine and use the CALL statement to call it. The external
declaration has the following syntax:
EXTERNAL PASCAL BB_block_read (buffer$, SHORT INTEGER status)
Parameters
buffer$ String buffer that will contain all the input field
data. This string contains all the characters from all
the fields. This string must be long enough for that
data, plus one character per field as a record
separator.
status A short integer that contains the status of the external
call. After the call, status can has a code that
indicates the result of the call. The codes and their
meanings are:
0 Successful call.
284 String too short.
287 No input fields.
294 No JOINFORM active.
BB_BLOCK_READ reads the fields in hardware order, that is from left to
right and top to bottom. Changing input order or tab order cannot alter
how the fields are returned to BB_BLOCK_READ. Therefore, small changes to
a form, such as shortening or moving a field, can impact applications
using BB_BLOCK_READ.
Example
10 EXTERNAL PASCAL BB_block_read(Buf$, SHORT INTEGER Stat) !Declare BB_BLOCK_READ
20 SHORT INTEGER Stat
.
.
.
150 CALL BB_block_read(Buf$,Stat) !Call BB_BLOCK_READ
160 !Buf$ contains the data, stat the status
170 IF stat <> 0 Then GOSUB 800 !Goto an error subroutine if the
180 !call was not successful
.
.
.