Forms

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

Forms

CALL

The CALL command passes control from one screen to another. CALL can be invoked automatically or under user control. CALL is used to determine the flow of control through a form.

See syntax.

You can specify text for the prompt for a CALL or allow the default which is the name of the screen to be CALLed.

Calls can be made conditionally by adding an IF clause to the CALL command.

The call can be automatic without offering the user a choice with IF (...) AUTO CALL

Control is returned to the calling screen either when the user enters the RETURN command in the called screen or because of options specified on the CALL command. On return from a CALL, there are a number of options as to how the calling screen behaves. This control makes CALL a very powerful command. It is possible to CALL a screen which performs actions and then returns without the user ever seeing a different screen.

Record screens and table screens have one single active record; to display data from multiple records on a single screen, use the CALL or LOOKUP clauses to get the data.

A screen can be called from a number of different screens.

Moving between screens

When control is passed to another screen with CALL, control moves away from this screen and, if a record or row has been updated, it is written. If the AUTO WRITE option is not on this screen, the user is asked whether it is "OK" to write this screen. (A LOOKUP, by contrast, does not move away from a screen, and does not force a write of this screen.)

Passing Keys

A called screen can be left blank for the user to enter keys of records or the key fields can be passed specifying the record(s) that the called screen is to reference.

The VIA clause passes values from the calling screen that are used as the keyfields in the called screen. This means that only records with the specified key values are accessed, and the user does not have to re-enter key values on the called screen.

In a case structured database, the USING clause accesses another case by passing a value for the case id (plus any other keys), to the called screen. In a case structured database, a CALL from a record screen without a USING clause, automatically restricts the called screen to records within the same case. The case identifier is used as the key for accessing other records from any record type. For example, the command CALL OCCUP from the EMPLOYEE screen, retrieves OCCUP records only for the employee whose record has been referenced.

Automatic record access

A CALL to a record or table screen where there are no fields to be displayed is an invaluable technique for creating or updating records automatically. The effect of this is that the record or row is accessed, updated if necessary, and control returned, without the user ever being aware that a screen was called.

It can be used to take data from menu screens and write it to the database automatically; to maintain control records; to assign sequential numbers to new input, to maintain inverted lists; etc. For example, suppose that an inverted list is needed on NAME. The CALL NAMEREF writes a record and returns without showing the user anything.

FORM ....  AUTO WRITE  error 65 video nobell '' -
.......
RECORD PERSON
   FIELD ID
   FIELD NAME REQUIRED
   CALL NAMEREF USING -1,NAME,ID -
        AUTO CALL RETURN NODATA NOPROMPT
.......
RECORD NAMEREF
   FIELD ID NODATA NOPROMPT
   FIELD NAME NODATA NOPROMPT
   FIELD XID NODATA NOPROMPT
ENDRECORD

Using CALL for control

When a CALL returns to the calling screen, the ONRETURN clause specifies a command that is automatically executed. This means that a dummy CALL is sometimes useful to take advantage of this capability. For example, to RESTART a record screen automatically;

FORM .....  -
     DECLARE INTEGER DUMMY -
     ......
RECORD PERSON
     FIELD ...
     ......
* Restart automatically when the cursor gets here
     CALL DUMMY NODATA NOPROMPT AUTO CALL RETURN -
          ONRETURN RESTART -
          PASSING 1
ENDRECORD
MENU DUMMY RECEIVING DUMMY
    FIELD DUMMY NODATA NOPROMPT
ENDMENU

EXIT, RETURN,
TOP,

etc.) automatically. An IF clause can be used on the CALL command to determine whether the CALL is performed.

CALL Stack

A "stack" is maintained and each time a CALL is issued an additional level is created on the stack with information about every variable. When control returns to the calling screen, the stack level is removed. Avoid sequences of nested CALL commands which potentially never return.

If the application needs to pass control between screens at the same level, do not specify CALLs where each screen calls the other screens. Use a menu which calls all the other screens and pass control through this menu each time. (With correct specifications, the control menu screen can be hidden from the user if so required.)

Locked records normally only happen when operating in a concurrent environment and another person has accessed the record. It is possible to lock a record from yourself because of a CALL or LOOKUP of a record currently in the stack. With case structured databases, there is a Common Information Record or 'CIR' for each case. If a CALL or a LOOKUP has a USING clause, this expects to access a new case and to retrieve the CIR. If the case is already referenced in the stack, it causes a locked record on the CIR.

CALL

The only required clauses on the CALL is the called screen_name. Available clauses are:

Clauses:

CALL screen_name
AUTO [CALL [IF ( expression ) ]] [DELETE] [RETURN ] [WRITE]
CLEAR 'c'
DATA [AT r , c] [HILITE | VIDEO options]
FINAL COMPUTE var=exp, ...
HELP screen name | 'help text'
IF ( expression )
INITIAL COMPUTE var=exp, ...
LOCK lock_options
MODE

 [FIND | SEARCH | VERIFY ]
      [EDIT | NOEDIT]

NODATA
NOPROMPT
ONCALL FIRST | LAST
ONRESTART EXIT | RETURN | STOP
ONRETURN

    EXIT | FIRST    | LAST
             NEXT | PREVIOUS | RESTART
             RETURN | STOP   | TOP
             UPDATE | WRITE

PASSING expression, ...
PROMPT 'prompt' HILITE | VIDEO options
USING caseid, [ * | key, ...]
VIA * | key, ...

General Clauses:

ACTIVITIES permissions
AT [r][,c]
PAD [n][,m]

screen_name

CALL

not

Escape

AUTO

AUTO  [CALL [IF (expression)]]
      [DELETE]
      [RETURN]
      [WRITE]

The AUTO clause specifies actions that are automatically performed without user intervention when the CALL statement is executed.

CALL

NODATA

NOPROMPT

IF

AUTO
CALL

AUTO
CALL

AUTO CALL

CALL

DELETE

Specifies that the record or table row referred to by the called screen is deleted when the user moves away from the screen. In conjunction with AUTO RETURN, this deletes records automatically.

RETURN

WRITE

Specifies that the called screen is written automatically when the user moves away from the screen. Example: To specify that INDEX is called without user intervention and control is passed back without user intervention. (might be to write a record automatically.)

CALL INDEX NODATA NOPROMPT -
     AUTO CALL RETURN WRITE

CLEAR

CLEAR 'c'
Specifies the single character used in the CALL data field. A question mark (?) is the default.

DATA

[NO]DATA
    [AT [ r ] [, c ]]
    [HILITE | VIDEO  video_options]

Specifies attributes for the data area of the CALL. NODATA specifies that the data area is not present and the user does not have the opportunity to select whether or not to perform the CALL.

AT

Specifies where on the screen the CALL data field is displayed.

HILITE

CALL

VIDEO

CALL

video_options

See

video treatment

FINAL

FINAL COMPUTE   variable = expression, ...
      IF (expression) variable = expression, ...

Specifies variables which are computed after the CALL returns to this screen. The variables to be computed are variables referenced by this screen, (not by the called screen). The final compute is equivalent to the final compute on a FIELD command. Multiple COMPUTE and IF statements can be specified; specify the keyword FINAL once. Variables can be computed using the COMPUTE clause or conditionally computed using the IF clause. When the IF clause is used, variables are computed only when the expression following the IF clause is true. If multiple COMPUTEs and IFs are specified, commas are used as delimiters between specifications.

CALL INDEX -
     FINAL COMPUTE    MFLAG = 1, -
           IF (DFLAG = 2) DDATE = TODAY(0)

HELP

HELP screen_name | 'help_string'
Specifies a text string or the name of a help screen to display when help is requested by the user when positioned at the CALL field.

When the user requests help, if a screen name is specified, that help screen is displayed; if a text string is specified, the string is displayed on the status line at the bottom of the screen.

IF

IF ( expression )
IF specifies a logical expression that controls whether the CALL command is executed. If the expression is true, the CALL can be performed. If it is false, the CALL is not allowed. The IF clause is evaluated before any of the other clauses.

CALL NEXTOFKIN IF (RELATIVE = 1)

INITIAL

INITIAL  COMPUTE   variable = expression, ...
         IF (expression),  variable = expression, ...

The INITIAL clause specifies one or more variables computed before the screen is CALLed. The variables to be computed are variables referenced by this screen (not the called screen). The initial compute is equivalent to the initial compute on a FIELD command. Multiple COMPUTE and IF statements can be specified; specify the keyword INITIAL once. Variables can be computed using the COMPUTE clause or conditionally computed using the IF clause. When the IF clause is used, variables are computed only when the expression following the IF clause is true. If multiple COMPUTEs and IFs are specified, commas are used as delimiters between specifications.

LOCK

LOCK specifies the lock the called screen uses when more than concurrent operations (more than one user accessing the database) are envisaged.

MODE

MODE  [FIND      |  SEARCH ]
      [VERIFY    |  NOVERIFY ]
      [EDIT      |  NOEDIT ]

MODE specifies whether the called screen is in FIND or SEARCH mode, VERIFY or NOVERIFY and EDIT or NOEDIT mode. The default is FIND, NOVERIFY, EDIT. If the default has been changed, and a mode is not specified, the called screen takes the mode of the calling screen.

FIND | SEARCH

FIND

SEARCH

VERIFY | NOVERIFY

VERIFY

EDIT | NOEDIT

EDIT

NOEDIT

ONCALL

ONCALL FIRST | LAST
Specifies that either the FIRST or LAST record in the set of records available to the called screen is retrieved and displayed.

ONRESTART

ONRESTART EXIT | RETURN | STOP
Specifies an action which is performed if the called screen is RESTARTed by the user or by an

ONRETURN
RESTART

clause of a CALL command.

EXIT

Terminates the SirForms session. RETURN

Returns control to the calling screen.

STOP

Returns control to the last stop screen which the user passed. The root screen is always the highest level stop screen.

ONRETURN

ONRETURN
  EXIT
  FIRST
  LAST
  NEXT
  PREVIOUS
  RESTART
  RETURN
  STOP
  TOP
  UPDATE
  WRITE

Specifies a command which is executed when control is returned to the calling screen. Only one command may be specified. This is equivalent to the user entering this command when control returns to this screen, except that it is done automatically.

EXIT

Terminates the SirForms session.

FIRST

Gets the first record for this screen. LAST

Gets the last record for this screen. NEXT

Gets the next record for this screen. PREVIOUS

Gets the previous record for this screen. RESTART

Displays an initial screen with the cursor at the first field. RETURN

Returns control to the screen that called the current screen. STOP

Returns control to a stop screen. TOP

Displays the current record with the cursor at the top of the screen. UPDATE

UPDATE

CALL

WRITE

Writes the record to the database and restarts the screen.

PASSING

PASSING expression, ...
Specifies a list of values which are passed to the CALLed screen. Values can be variable names, constants or expressions. The values passed are received by specifying the RECEIVING clause in the screen being called. If the passing list is longer than the receiving list, additional entries in the passing list are ignored. Keys may appear on the PASSING clause but cannot be received into keys on the CALLed screen. Pass keys with the VIA or USING clauses of the CALL command.

CALL INDEX USING -1,NAME,ID -
     PASSING GENDER
 .
 .
 .
RECORD INDEX RECEIVING SEX

PROMPT

[NO]PROMPT [HILITE | VIDEO video_options]
Specifies the treatment of the prompt for the CALL. NOPROMPT suppresses the display of a prompt. If NOPROMPT and NODATA are specified, nothing is displayed and the cursor position is not altered. AT specifies the row and column position where the prompt display commences. (See AT.)

The prompt is displayed followed by the data area which displays a "?" or the specified CLEAR character. If a PROMPT is not specified, the name of the CALLed screen is displayed.

HILITE

Specifies the video treatment of the prompt when the cursor is in the field. VIDEO

video treatment

USING

USING expression,...
USING specifies that the CALL uses a different case. Specify the case id value, optionally followed by the key field values. Specify an asterisk (*) to indicate that the key fields of the current screen are to be used. USING references a different case and is not used for databases without case structures or in conjunction with the VIA clause.

Example: To call a screen INDEX which references a new case with a case id of -1 and two other keyfields:
CALL INDEX USING -1,NAME,ID

VIA

VIA expression, ...
VIA specifies the key fields for a CALL within this case, to another record on a caseless database or to a table screen. Specify values for the key fields. The values can be arithmetic expressions, constants or names of fields in the calling screen. The values are displayed in the called screen.

Specify an asterisk (*) to indicate that the key fields of the current screen are to be used. The asterisk can be followed by other values.

If one or more of the lower level keys are omitted, all records with the specified keys are accessible.

Do not specify a case id on the VIA clause. Do not use USING and VIA on the same CALL command.

Example: To access associated records in the REVIEW Record screen from the OCCUP screen. The VIA * option specifies that the caseid and all keys of the Record screen OCCUP are used in accessing records in the REVIEW screen. The user can now retrieve or create records which "belong" to the particular OCCUP record.
CALL REVIEW VIA *

Escape

CALL {'command' | expression}
     NOCLEARSCREEN
     [CALL options]

The CALL command can be used to "escape" SirForms and run another process. After the completion of the escaped process, control returns to SirForms.

Specify a constant as a quoted string or a string expression which is the command that is passed to the operating system. If the expression is simply a variable name, enclose it in parentheses () to avoid confusion between an expression and a screen name.

NOCLEARSCREEN

Specifies that the screen is not cleared when an 'escape' call is made. The screen is cleared by default. CALL options

Specify any of the CALL options as with the standard form of CALL. Example, to exit SirForms and print a file, specify a CALL such as:

CALL 'PRINT output.lst' -
      prompt 'Print Output File on Printer ?'