PreviousKey Code List Syntax of Import/Export FilesNext

Chapter 19: Function Code List

This chapter provides detailed descriptions of the functions that you can include in a global or local dialog (see the chapter Dialog for details).

19.1 Function Parameters

Each function can have up to three parameters, which can be one of the following types:

attr One of the following run-time attribute names:
AUX1
AUX2
AUX3
AUX4
ERROR
INPUT
NATIVE

These enable you to associate foreground/background colors with panel fields when the screenset runs.

group The name of a group field.
proc The name of a dialog procedure, Pnnn, where nnn is a procedure number in the range 000 to 255. In functions that require a procedure parameter, you can supply the procedure number in a field or register.
numeric A numeric literal.
string An alphanumeric literal surrounded by quotes ("). If the first character of a parameter is a quote ("), it is assumed to be an alphanumeric literal. You can enter a literal of up to 80 characters by scrolling the field horizontally.
field The name of a data field. If the field is a group field, the field name can have a subscript that identifies a particular occurrence of the group:

field(subscript)

subscript can be a numeric literal, a register, or the name of another field (which must not be group field).

panel The name of a panel in a screenset.
register Dialog System maintains a number of internal registers. All registers are two-byte computational fields. The following register is provided:
$REG A general purpose register. Functions can read from $REG or write to it.
null You use the value $NULL to indicate that you are not supplying a parameter value for an optional parameter (for example, the optional procedure name parameter of the PUSH function).

19.2 Function Descriptions

This section contains a description of each function and its parameters.

Where a parameter is described as field(sub), the parameter can be a subscripted or non-subscripted field name.


BEEP

BEEP sounds the beep on the machine.

Syntax:
BEEP
Parameters:
None

BP

BP branches to a procedure without executing the remaining functions in the dialog line.

Syntax:
BP procedure
Parameters:
procedure proc, field(sub), or register.

The procedure to be branched to.

Examples:
BP P063

Branches to procedure 063.

MOVE 75 $REG
BP $REG

Branches to procedure 075.


BPD

BPD branches to a procedure without executing the remaining functions in the dialog line.

The destination procedure number is n+m-1, where:

Syntax:
BPD group  procedure
Parameters:
group The name of the group on which to act.
procedure proc, field(sub), or register.

The procedure to branch to if the selection bar in group is at position one.

Example:
BPD  MYGROUP 65

If the selection bar in MYGROUP is in position one, control branches to procedure 065; if it is in position four, control branches to procedure 068.


BPE

BPE branches to a procedure only if the next function in the dialog line causes an exception condition. The remaining functions in the dialog line are not executed.

Syntax:
BPE procedure
Parameters:
procedure proc or field(sub).

The exception procedure to be branched to.

Remarks:

A function that can cause an exception has an entry in its description describing the conditions under which it can cause an exception.

Example:
BPE P045
POP

Branches to procedure 045 only if the POP function causes an exception by attempting to pop an empty stack.


BPR

BPR branches to a procedure without executing the remaining functions in the dialog line.

The destination procedure number is n+m-1, where:

Syntax:
BPR procedure
Parameters:
procedure proc, field(sub), or register.

The procedure to which control branches if the value in the register is 1.

Example:
MOVE 4 $REG
BPR 65

Branches to procedure 068.


CALLOUT

Use CALLOUT to make a synchronous call to an external program, so that you can call a user program directly from dialog.

Syntax:
CALLOUT program-name callout-type callout-parameter
Parameters:
program-name string

The name of the program being called.

callout-type numeric

Must be 0000 or 0006. When the value 0006 is specified, the content of RETURN-CODE on exiting the callout program is moved into $REG, unless the value is -9999, when $REG is unaffected, but the dialog exception condition is set. RETURN-CODE is always cleared to zero.

callout-parameter Must be $NULL. Specifies that the whole of the Data Block is passed.
Remarks:

The normal search paths for COBOL programs are used.

The first parameter passed by Dialog System to the called program is the Ds-Control-Block, described in either ds-cntrl.mf or ds-cntrl.ans in the chapter Running the Screenset. You cannot make any changes to this control block; any changes you attempt will not be reflected in Dialog System's copy of the control block.

The second parameter passed by Dialog System to the called program is the screenset-Data-Block. The callout program can modify the Data Block as desired. You can use the screenset copybook that is generated by Dialog System to define the Data Block in the main application, as the data definition of the Data Block in the callout program.

The CALLOUT function has the following restrictions:

Exception:

The function causes an exception condition (see BPE) if the program specified is not found.

Example:
CALLOUT "\usr\abc\user-program" 0000 $NULL

Executes the program user-program.


CEOF

CEOF clears a field from the current cursor position to the end of the field and fills it with spaces. The field must be alphanumeric or alphabetic, otherwise this function has no effect.

Syntax:
CEOF
Parameters:

None


CFLD

CFLD clears all of an input field. The field is filled with spaces if it is an alphanumeric or alphabetic field, or zeros if it is a numeric field.

Syntax:
CFLD field
Parameters:
field field(sub).

The name of the field. If this parameter is NULL, the current field is cleared.


CLEAR

CLEAR clears all of the fields on the current panel.

Syntax:
CLEAR
Parameters:

None


CLRF

CLRF sets the value of a field to false (0).

Syntax:
CLRF field
Parameters:
field field(sub).

The name of the field.

Example:
CLRF MYGROUP(10)

Sets the tenth field in group MYGROUP to zero.


COFF

COFF turns the cursor state to off. The cursor is invisible if the current panel has no input fields.

Syntax:
COFF
Parameters:

None

Examples:

This function is system dependent, so it might not work on your system.


CON

CON turns the cursor state to on. The cursor is present even if there are no input fields on the current panel.

Syntax:
CON
Parameters:

None

Examples:

This function is system dependent, so it might not work on your system.


DBP

DPB deletes the line at the current selection bar position.

Syntax:
DBP group
Parameters:
group The name of the group on which to act.
Remarks:

The size of the group's internal array is decremented by one. Data in lines beyond the deleted line is shifted down one position.

When the internal array size is one, the DBP function does not work. The first occurrence is cleared, but the array size remains at one, because you cannot have a group that contains zero occurrences.

Example:

The group MYGROUP contains the following values (the values between the lines represent the fields visible on the panel, and the asterisks represent the position of the selection bar):

12
20
--------------------
35
4***************
65
--------------------
19
25

The function:

DBP MYGROUP

alters MYGROUP as follows:



12
20
--------------------
35
65***************
19
--------------------
25

DECVAL

DECVAL decrements a numeric field or register by one.

Syntax:
DECVAL item
Parameters:
item field(sub) or register ($REG only).

The name of the item to be decremented.

Examples:
DECVAL $REG
DECVAL QUANTITY(3)

The first example decrements the value of $REG; the second example decrements the third occurrence in group field QUANTITY.


GOF

GOF transfers control to a specified field in the current panel. If the field is not on the current panel, each panel in the screenset is searched until a panel containing the specified field is found.

Syntax:
GOF field
Parameters:
field field(sub) or register.

The name of the field to which control is transferred.

Remarks:

You can pass a field number in a register. Remember that this is the number of the field in the Data Block, rather than the number of the field in the panel.

Exception:

The function causes an exception when the specified field cannot be found in any panel in the screenset.

Examples:
GOF DESCR
GOF PRICE($REG)
GOF $REG

The first example transfers control to the field named DESCR. The second example transfers control to an occurrence in the group field PRICE; the occurrence is determined by the current value of $REG. The final example transfers control to field number n, where n is the value of $REG; note that this is the nth field in the Data Block, not the nth field in the panel.


GOMOUSE

GOMOUSE enables mouse support, without you having to return to the application or execute a CALLOUT.

Syntax:
GOMOUSE number
Parameters:
number numeric.

A number that represents the following settings:

+1 Will support relocation of the cursor to thestart of a different input field (which is not in a group) after validating the current input field. If validation fails, no cursor movement occurs.
+2 Will support relocation of the cursor to thestart of a different input field (which is in agroup and at the current action bar position) after validating the current inputfield. If validation fails, no cursor movement occurs.
+4 Will support relocation of the cursor to thestart of a different input field (which is in agroup), relocating the action bar if necessary, after validating the cursor inputfield. If validation fails, no cursor movement occurs.
Remarks:

These settings exhibit cumulative behavior. All relocations are to the position of the mouse cursor when a mouse button was last clicked.

Example:
MSL GOMOUSE 0007

Enables all of these actions for a panel.


GOP

GOP passes control to a specified panel.

Syntax:
GOP panel
Parameters:
panel The name of the panel to which control passes.
Remarks:

Because this function passes control to another panel, you cannot define any subsequent entries in that dialog line.

The target panel must exist before you can use this function in dialog.

Examples:
GOP NEXTPNL

Passes control to the panel named NEXTPNL.


IBP

IBP inserts an empty line into a group at the position of the selection bar.

Syntax:
IBP group
Parameters:
group The name of the group on which to act.
Remarks:

The group's internal array size is incremented by one, subject to the maximum size of the Data Block. Data in lines after the inserted line is moved up by one position. The empty line contains zeros in numeric fields, and spaces elsewhere.

Exception:

The function causes an exception when it attempts to insert a line into a group that is already full, because this would cause loss of data from the last item in the data group.

Example:

The field MYGROUP contains the following values (values between the lines are those values that are visible in the panel, and the asterisks show the position of the selection bar):

24
--------------------
28
36**************
23
--------------------
2
30

The function:

IBP  MYGROUP

alters MYGROUP as follows:

24
--------------------
28
***************
36
--------------------
23
2
30

IF

IF tests an expression for validity, and if true, branches to a specified procedure where processing continues. Control does not return to the calling procedure. If the expression is false, execution continues at the line below the IF function.

The following IF functions are available:

IF <, IF <=, IF =, IF >, IF >=, IFNOT=

Syntax:
IF-statement expression1 expression2 procedure
Parameters:
IF-statement One of the above IF statements.
expression1 numeric, string, field(sub), or register.

The first operand of the test.

expression2 numeric, string, field(sub), or register.

The second operand of the test.

procedure proc, field(sub), or register.

The procedure to branch to if the test is true.

Remarks:

Expression1 and expression2 must be compatible types. For example, an expression cannot test a numeric literal against an alphanumeric literal. A similar set of conditional functions are provided that perform the target procedure and return control to the calling procedure. See the XIF function later in this chapter.

Examples:
IF=  QUANTITY  3  P045

Branches to procedure 045 if the field QUANTITY has the value 3.

IF> MYGROUP(2)  $REG  TARGET

Branches to the procedure whose number is stored in field TARGET if the second occurrence in group field MYGROUP is greater than the value in the register.


INCVAL

INCVAL increments a numeric field or register by one.

Syntax:
INCVAL item
Parameters:
item field(sub) or register ($REG only).

The item to be incremented.

Examples:
INCVAL  $REG
INCVAL  STEP

The first example increments the register; the second example increments the field STEP.


KS

KS scans the keyboard, checks the status of all the status keys, and forces any status key dialog to execute.

Syntax:
KS number
Parameters:
number numeric, field(sub), or register.

A number that represents the following bit settings:

bit 7 set – check Ins status
bit 6 set – check Caps Lock status
bit 5 set – check Num Lock status (DOS)
bit 4 set – check Scroll Lock status
bit 3 set – check Alt key pressed status
bit 2 set – check Ctrl key pressed status
bit 1 set – check Left Shift pressed status
bit 0 set – check Right Shift pressed status
Remarks:

The Ins, Caps, Num (DOS only), and Scroll Lock status keys are tested for their toggle status. For example, the status of the Ins key after it is pressed five times is the same as after it is pressed just once.

However, the Alt, Ctrl, Left Shift and Right Shift keys are tested to determine whether or not they are currently being held down.

If your keyboard does not have the status keys described in this section, please consult your Release Notes to see which keys on the standard keyboard for your system provide the equivalent functions.

Example:
KS 55H

Checks the status of the Caps, Scroll Lock, Ctrl and Right Shift keys and activates any dialog associated with them.


MAS

MAS moves the defined internal array size of a group to a specified field or to the register.

Syntax:
MAS group  destination
Parameters:
group The name of the group on which to act.
destination field(sub) or register.

The location where the array size is stored.

Example:
MAS  MYGROUP  $REG

Moves the internal array size of group MYGROUP to the register.


MB

MB returns the value of the item at the selection bar in a group to a specified field or register.

Syntax:
MB group  destination
Parameters:
group The name of the group on which to act.
destination field(sub) or register ($REG only).

The location where the value of the item at the selection bar position is stored.

Example:

The group MYGROUP contains the following values (values between the lines are visible in the panel, and asterisks mark the position of the selection bar):

SMITH
JONES
--------------------
ADAMS
KNIGHT**************


SNOW
STEWART
--------------------
MADISON

The function:

MB  MYGROUP  NAME

stores the value "KNIGHT" in field NAME.


MBD

MBD returns the data position where the selection bar is currently located to a specified field or register.

Syntax:
MBD group  destination
Parameters:
group The name of the group on which to act.
destination field(sub) or register ($REG only).

The location where the bar position is stored.

Example:

The group MYGROUP contains the following values and the selection bar is at the fourth data item in the group (values between the lines are visible in the panel, and asterisks mark the position of the selection bar):

SMITH
JONES
--------------------
ADAMS
KNIGHT**************
SNOW
STEWART
--------------------
MADISON

The function:

MBD  MYGROUP  INDEX

stores the value 4 in the field INDEX.


MOVE

MOVE places a value in a field or register.

Syntax:
MOVE  source  destination
Parameters:
source numeric, string, field(sub), or register.

The source of the move.

destination field(sub) or register ($REG only).

The target of the move.

Remarks:

Source and Destination must be compatible types. For example, you cannot move an anlphanumeric source to a numeric destination. If you move values between fields of different lengths, the value is truncated, as necessary.

Examples:
MOVE  3  $REG
MOVE  "INVALID PARAMETER"  MSGFLD
MOVE  MYGROUP(INDEX)  TEMP

The first example moves the value 3 into the register. The second example moves the string "INVALID PARAMETER" into the field MSGFLD. The third example moves the occurrence in MYGROUP given by INDEX into the field TEMP.


MOVEPNL

MOVEPNL moves a panel around the screen in any direction for any distance.

Syntax:
MOVEPNL panel  direction  distance
Parameters:
panel The name of the panel to move. If you specify a null parameter, the current active panel is moved.
direction numeric, field(sub), or register.

The direction in which to move the panel, indicated by the following numbers:

1 left
2 right
3 up
4 down
distance numeric, field(sub), or register.

The distance, in characters, to move the panel.

Example:
MOVEPNL  PANEL1  2  20
MOVEPNL  PANEL1  4  10

Moves PANEL1 20 characters right and 10 characters down.


MOVEVTXT

MOVETXT transfers an occurrence of a virtual text group to an alphanumeric or alphabetic field.

Syntax:
MOVETXT group  occurrence  destination
Parameters:
group The name of the virtual text group.
occurrence numeric, field(sub), or register.

The group occurrence number.

destination field(sub) (must be an alphanumeric field).

The target of the move.

Example:
MOVETXT  VGROUP  4  TXTFLD

Moves the contents of the fourth occurrence in virtual text group VGROUP to field TXTFLD.


MPID

MPID obtains the identification number of a panel.

Syntax:
MPID panel  destination
Parameters:
panel The panel name.
destination field(sub) or register ($REG only).

The location where the panel identification number is stored.

Remarks:

The calling program uses the panel id for a screenset that uses Micro Focus Panels (see the chapter Using Dialog System for details on using Micro Focus Panels) in DOS environments.

This function is not supported in the UNIX environment.

Example:
MPID  HELPPNL  PANEL-ID

Stores the identification number of panel HELPPNL in the field PANEL-ID.


MTD

MTD returns the number of the data item at the top of a visible data list to a specified field or register.

Syntax:
MTD group  destination
Parameters:
group The name of the group on which to act.
destination field(sub) or register ($REG only).

The location where the data occurrence is stored.

Example:

The group MYGROUP contains the following values and the third data item is at the top of the visible screen (the values between lines are visible in the screen panel, and asterisks mark the position of the selection bar):

25
34
20
--------------------
0
10
28****************
12
--------------------
46
45

The function:

MTD  MYGROUP  $REG

stores the value 3 in the register.


PBDN

PBDN moves the selection bar down a specified number of positions in a group.

Syntax:
PBDN group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The number of occurrences by which to move the bar down.

Remarks:

If you move the selection bar down by more lines than are visible in the group, the group automatically scrolls down the data, as long as the move does not exceed the number of data items.

Exception:

The function causes an exception when the bar is positioned on the last occurrence in the group.

Example:

The group MYGROUP contains the following values (the values between lines are visible in the screen panel, and asterisks mark the position of the selection bar):

10
--------------------
23
80***************
17
42
--------------------
0
4

The function:

PBDN  2

has the following effect:

10
--------------------
23
80
17
42***************


--------------------
0
4

If this is followed by:

PBDN  1

the display becomes:

10
23
--------------------
80
17
42
0***************
--------------------
4

PBUP

PBUP moves the selection bar up a specified number of positions in a group.

Syntax:
PBUP group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The number of occurrences by which to move the bar up.

Remarks:

If you move the selection bar up more lines than are visible in the group, the group automatically scrolls up the data, as long as the move does not exceed the number of data items.

Exception:

The function causes an exception when the bar is positioned on the first occurrence in the panel group.

Example:

The group MYGROUP contains the following values (the values between lines are visible in the screen panel, and asterisks mark the position of the selection bar):

25
10
--------------------
23
80***************
17
42
--------------------
4

The function:

PBUP  2

alters the display as follows:

25
--------------------
10***************
23
80
17
--------------------
42
4

PDDN

PDDN scrolls down a data array by the amount specified, without moving the selection bar.

Syntax:
PDDN group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The amount by which to scroll down the data.

Exception:

The function causes an exception when it is not possible to position the data any further down on the panel.

Example:

The group MYGROUP contains the following values (the values between lines are visible in the screen panel, and asterisks show the position of the selection bar):

FIRST
SECOND
THIRD
----------------------
FOURTH
FIFTH
SIXTH***************
SEVENTH
EIGHTH
----------------------
NINTH
TENTH
ELVENTH
TWELFTH

The function:

PDDN  MYGROUP  2

alters the display as follows:

FIRST
SECOND
THIRD
FOURTH
FIFTH
---------------------
SIXTH
SEVENTH
EIGHTH***************
NINTH
TENTH
---------------------
ELVENTH
TWELFTH

PDUP

PDUP scrolls up a data array by the amount specified, without moving the selection bar.

Syntax:
PDUP group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The amount by which to scroll the data up.

Exception:

The function causes an exception when it is not possible to position the data any further up on the panel.

Example:

The group MYGROUP contains the following values (the values between lines are visible in the screen panel, and asterisks show the position of the selection bar):

FIRST
SECOND
THIRD
---------------------
FOURTH
FIFTH
SIXTH***************
SEVENTH
EIGHTH
---------------------
NINTH

The function:

PDUP  MYGROUP  2

alters the display as follows:

FIRST
---------------------
SECOND
THIRD
FOURTH***************
FIFTH
SIXTH
---------------------
SEVENTH
EIGHTH
NINTH

POP

POP pops the most recent physical screen image from the stack and return control to that panel. The panel is the one that was active at the time the PUSH function was executed.

Syntax:
POP
Parameters:

None

Remarks:

Because this function passes control to another panel, you cannot define any subsequent entries in the dialog line containing the POP.

You can initiate dialog in the panel that is popped from the stack by specifying a procedure in the PUSH function that pushed the panel onto the stack.

Exception:

The function causes an exception when the stack is empty.


PUSH

PUSH pushes the current physical screen image onto a stack and retains control in the current panel.

Syntax:
PUSH procedure
Parameters:
procedure proc or null.

The name of the procedure to execute after the POP associated with this PUSH is performed. A null parameter means that no procedure is executed after the panel is popped from the stack.

Exception:

The function causes an exception when the push panel stack is full (that is, when it contains the maximum 16 entries).

Example:
PUSH  P053

Pushes the current screen image onto the stack, and specifies that after it is popped from the stack, procedure 053 is executed.


RETC

RETC forces control to return to the calling program, where the program can perform some action such as accessing the data base or deriving some new data values.

Syntax:
RETC
Parameters:

None

Remarks:

The only other way to return to the calling program is to define an input field as an exit field (see the chapter Panel Fields).


RFT

RFT refreshes the text in the current panel.

Syntax:
RFT
Parameters:

None

Example:

This function is especially useful following the SUSP function, and ensures that all updates made during the suspend are actually displayed.


RFTD

RFTD refreshes all fields and scroll bars from the Data Block. In other words, it updates the optimization rectangle that incorporates all fields and scroll bars in the current panel.

Syntax:
RFTD
Parameters:

None


RKEY

RKEY redirects the keystroke to another panel.

Syntax:
RKEY panel
Parameters:
panel The name of the panel to which the keystroke should be redirected.
Exception:

The function causes an exception when the specified key has already been redirected, or the redirected key does not exist on the target screen.

Example:

The key in the original dialog line in the current panel is F10. The line:

RKEY  PANEL2

in the dialog line passes control to the F10 dialog entry in PANEL2. After completion of the F10 entry in PANEL2, control returns to the current panel.


RPKY

RPKY repeats the last keystroke upon completion of the current dialog line.

Syntax:
RPKY
Parameters:

None

Remarks:

You normally use this function when the key that is pressed requires some action in the current panel that needs a different panel, and the keystroke also needs to be carried forward to this new panel.

You should use this function with caution, because an infinite loop is created at run time if control remains in the current panel.


SAS

SAS sets the internal array size of a group, limiting the amount of scrolling that can take place to the value specified.

Syntax:
SAS group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The new value of the array size.

Exception:

The function causes an exception when it attempts to set an array size of zero.

Example:
SAS  MYGROUP  20

You can only display the first 20 occurrences in group MYGROUP.


SB

SB places the selection bar on a specified occurrence in the visible data list of a group.

Syntax:
SB group  number
Parameters:
group The name of the group on which to act.
number numeric, field(sub), or register.

The occurrence to position the selection bar on.

Remarks:

If you specify a value larger than the number of occurrences on the panel, the bar is positioned on the last panel occurrence.

Exception:

The function causes an exception when it attempts to set the bar on a line that is beyond the limit of the panel group.

Example:

The visible data list of group MYGROUP looks like this (asterisks show the position of the selection bar):

10***************
12
0
25

The function:

SB  MYGROUP  3

alters the display as follows:

10
12
0***************
25
The function:
SB  MYGROUP  7

alters the display as follows:

10
12
0
25***************

SBOD

SBOD positions the selection bar on the data item specified, and if necessary, scrolls the data to make the relevant lines visible. This function potentially can affect both the selection bar and data positions.

Syntax:
SBOD group  occurrence
Parameters:
group The name of the group on which to act.
occurrence numeric, field(sub), or register.

The data occurrence on which to set the selection bar.

Remarks:

The specified data item and selection bar do not necessarily appear at line one. For example, if the required data item is near the end of the list, it is positioned at the end of the visible list rather than on line one.

If, however, the required data item is already visible, the selection bar simply moves to the item without scrolling the group.

Exception:

The function causes an exception when it attempts to set the bar either on data item zero, or outside the limit of the Data Block.

Example:

The group MYGROUP contains the following values (values between lines are visible on the screen panel, and asterisks show the position of the selection bar):

BRIDGE
CANASTA
--------------------
POKER
WHIST**************
BLACKJACK
SOLITAIRE
--------------------
RUMMY
CRIBBAGE

The function:

SBOD  MYGROUP  2

alters the display as follows:

BRIDGE
--------------------
CANASTA*************
POKER
WHIST
BLACKJACK
--------------------
SOLITAIRE
RUMMY
CRIBBAGE

SD

SD scrolls the panel area to position the specified data occurrence in a group at the top of the associated panel, leaving the position of the selection bar unaltered.

Syntax:
SD group  occurrence
Parameters:
group The name of the group on which to act.
occurrence numeric, field(sub), or register.

The data occurrence to be positioned at line one of the screen panel.

Exception:

The function causes an exception when it attempts to set the panel area either on data item zero, or outside the limit of the Data Block.

Example:

The group MYGROUP contains the following values (values between lines are visible in the screen panel, and asterisks show the position of the selection):

1
2
---------------
3
4
5**********
---------------
6
7
8

The function:

SD  MYGROUP  5

alters the display as follows:

1
2
3
4
---------------
5
6
7**********
---------------
8

SETCUR

SETCUR positions the cursor in the next input field.

Syntax:
SETCUR position
Parameters:
position numeric, field(sub), or register.

The position of the cursor in the field.

Remarks:

The cursor is moved only when the field is used for input.

Example:
SETCUR  5

Positions the cursor at character position 5 in the next input field.


SETF

SETF sets the value of a field to true (1).

Syntax:
SETF item
Parameters:
item field(sub).

The name of the field.

Example:
SETF  FLAGS(3)

Sets the third occurrence of group field FLAGS to 1.


SFAT

SFAT sets a run-time display attribute on a particular field on the current panel.

Syntax:
SFAT field  attribute
Parameters:
field field(sub) or register.

The field on which to set the attribute.

attribute attr.

The name of the run-time attribute to be used. You can use any one of the six active run-time attributes (AUX1 through AUX4, INPUT, and ERROR), or NATIVE, which resets the attribute to the colour defined by the screenset. See the section Attribute Palette in the chapter Panel Painting.

Exception:

The function causes an exception when it attempts to set the attribute either on a field that does not exist or on a group field.

Example:
SFAT  FIELD2  AUX1

Sets the field FIELD2 to the run-time display attribute AUX1.


SGAT

SGAT sets a run-time display attribute on all fields on the current panel.

Syntax:
SGAT attribute
Parameters:
attribute attr.

The run-time attribute to be used. You can use any one of the six active run-time attributes (AUX1 through AUX4, INPUT, and ERROR), or NATIVE, which resets the attribute to the colour defined by the screenset. See the section Attribute Palette in the chapter Panel Painting.

Example:
SGAT  AUX2

Sets all fields of the current panel to the run-time display attribute AUX2.


SHP

SHP displays a panel while retaining control in the current panel.

Syntax:
SHP panel
Parameters:
panel The name of the panel to show.
Example:
SHP  ERRORPNL

Displays the panel ERRORPNL, but retains control in the current panel.


SKNF

SKNF moves the cursor to a subsequent input field on the current panel.

Syntax:
SKNF number
Parameters:
number numeric, field(sub), or register.

The number of fields to skip over.

Remarks:

If you specify a value larger than the remaining number of input fields in the panel, the cursor skips to the last input field on the panel; SKNF 9999 is guaranteed to do this.

Exception:

The function causes an exception when there is no subsequent input field.

Example:
SKNF  1

Skips to the next input field in the current panel.


SKPF

SKPF moves the cursor to a previous input field on the current panel.

Syntax:
SKPF number
Parameters:
number numeric, field(sub), or register.

The number of fields to skip over.

Remarks:

If you specify a value larger than the number of input fields before the current field, the cursor skips to the first input field on the panel;
SKPF 9999 is guaranteed to do this.

Exception:

The function causes an exception when there is no previous input field.

Example:
SKPF  999

Skips to the first input field of the current panel (there is a maximum of 512 fields per screenset, so this is bound to be greater than the number of previous input fields in the current panel).


SUSP

SUSP delays the panel refresh until either the end of the current dialog, or until the panel is explicitly refreshed with the RFTD or RFT functions.

Syntax:
SUSP
Parameters:

None

Remarks:

The function is also terminated if the POP, SHP or GOP functions are invoked.


TERM

TERM terminates a screenset, shutting down all the internal storage used by that screenset.

Syntax:
TERM
Parameters:

None

Remarks:

If you use this function with a screenset based on Micro Focus Panels, the function deletes all of the panels used by the screenset. (See the chapter Using Dialog System for details of Micro Focus Panels.)


TIMEOUT

TIMEOUT specifies a procedure to execute after a specified period of time if there is no input in the current panel.

Syntax:
TIMEOUT timeout procedure
Parameters:
timeout numeric, field(sub), or register.

The number of seconds to elapse before a timeout occurs during any future input. A value of zero means wait indefinitely for input.

procedure proc, field(sub), register, or null.

The procedure to execute when the timeout occurs. This can be $NULL.

You are advised to define this procedure in the default procedure table, because timeout can occur on any panel. If the procedure cannot be found in the panel dialog, an error occurs.

Remarks:

A typical screenset timeout procedure displays a timeout panel, containing a message, and waits for the user to type something. If the user does not respond in the timeout period, a further timeout occurs, and the same timeout procedure is entered.

To return the user to the original panel when he or she acknowledges the timeout, your timeout procedure must PUSH the current environment before doing a GOP to the timeout panel. The timeout procedure must then POP the stacked panel before it exits from the procedure.

A program loop or stack overflow can occur if the timeout panel itself times out, because the timeout panel is pushed before it is reinvoked. If this happens repeatedly, the stack will eventually overflow. If the user presses a key to make the timeout panel exit before overflow occurs, the user has to repeat the keystroke until all the stacked timeout panels have been popped, before getting back to the original panel. To prevent this, reset the timeout to zero on entry to the timeout procedure, and reset the timeout to the required value before exiting the timeout procedure.

Example:
TIMEOUT  120  P032

Specifies that procedure 032 is to be executed if no input takes place in the current panel for two minutes.


TOGF

TOGF toggles the value of a field between true (1) and false (0).

Syntax:
TOGF item
Parameters:
item field(sub).

The name of the field.

Example:
TOGF  FLAG

Toggles the value of field FLAG.


VAL

VAL forces validation of all the input fields on the current screen when an exception condition is being monitored. VAL sets an exception condition when an invalid field is encountered and that invalid field becomes the current field.

Syntax:
VAL
Parameters:

None

Example:

This function must be used in conjunction with a function that monitors an exception condition, for example BPE, XPE, or the error key ERR. If there is no exception condition monitoring, the behavior of this function is unpredictable. for more information about the error key, see the section Error Key in the chapter Key Code List.

If there are any groups on the screen, validations on that group are performed on all fields in that group up to the current array size.


XIF

XIF tests an expression for validity, and if true, performs the procedure specified, where processing continues. When execution of the procedure is complete, control returns to dialog statement following the XIF. If the expression is false, execution continues at the dialog statement following the XIF function. The following XIF functions are available:

XIF<, XIF<=, XIF=, XIF>, XIF>=, XIFNOT=

Syntax:
XIF-statement expression1 expression2 procedure-name
Parameters:
XIF-statement One of the XIF statements specified above.
expression1 numeric, string, field(sub), or register.

The first operand of the test.

expression2 numeric, string, field(sub), or register.

The second operand of the test.

procedure proc, field(sub), or register.

The procedure to perform if the test is true, or an alphabetic field that contains the name of the procedure to perform. Fields and procedures might have the same name, in which case the contents of the field are used.

Remarks:

Expression1 and expression2 must be compatible types. For example, an expression cannot test a numeric literal against an alphanumeric literal. A similar set of conditional functions are provided that execute the target procedure and do not return control to the calling procedure. See the IF function earlier in this chapter.

Example:
XIF> GOODS-COST 1500 P100

If the field GOODS-COST has a value greater than 1500, executes the procedure P100, then returns to the next function.


XP

XP executes a procedure and returns control to the next function in the dialog line.

Syntax:
XP procedure
Parameters:
procedure proc, field(sub), or register.

The procedure to be executed.

Example:
XP  PROCNO
BEEP

Executes the procedure whose number is given by field PROCNO. When the procedure has executed, control returns to the dialog and executes the BEEP function.


XPD

XPD branches to a procedure, specified by the number in the parameter and the position of the selection bar in a group, then returns control to the next function after the procedure has been performed.

Syntax:
XPD group  procedure
Parameters:
group The name of the group on which to act.
procedure proc, field(sub), or register.

The procedure to execute if the selection bar in group is at position one, or the value to use in the destination procedure calculation.

Remarks:

The destination procedure number is n+m-1, where:

Example:
XPD  MYGROUP 65

If the selection bar in MYGROUP is in position one, procedure 065 is executed; if the selection bar is in position four, procedure 068 is executed.


XPE

XPE executes a procedure and return control to the next function in the dialog line upon completion. The procedure is executed only if the next function in the dialog entry causes an exception condition (for example, attempting to scroll beyond the limit of a scrolling group).

Syntax:
XPE procedure
Parameters:
procedure proc or field(sub).

The exception procedure to be executed.

Remarks:

A function that can cause an exception has an entry in its description specifying the conditions under which this happens.

Example:
XPE P045
POP

Procedure 045 is executed only if the POP function causes an exception by attempting to pop an empty stack.


XPR

XPR executes a procedure, specified by the number in the parameter and the value in the register, then returns control to the next function in the dialog line upon completion.

Syntax:
XPR procedure
Parameters:
procedure proc, field(sub), or register.

The procedure to execute if the value in the register is one, or the value used in the destination procedure calcualtion.

Remarks:

The destination procedure number is n+m-1, where:

Example:
MOVE 4 $REG
XPR 65

This executes procedure 068.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousKey Code List Syntax of Import/Export FilesNext