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 a 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:

  • Do not call any Dialog System run-time modules from the CALLOUT program or make recursive calls. Unpredictable results can occur.

  • Because of system limits, the maximum length of the name of the called module, including its path, is 82 bytes.
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. 

        
        
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 the start
            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 the start
            of a different input field (which is in a group and at the current
            action bar position) after validating the current input field. If
            validation fails, no cursor movement occurs. 
          

          

            +4
            Will support relocation of the cursor to the start
            of a different input field (which is in a group), relocating the
            action bar if necessary, after validating the cursor input field. 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 alphanumeric
        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:
        
    
          
  • n is the value of procedure.
            
            
    • 
          
  • m is the position of the selection bar in the group
            specified by group. If the group does not have
            a selection bar (as is the case with virtual attribute groups), m
            is the position of the first visible line in the data. 
    • 
        

      

      

        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 returns 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:
        
    
          
  • n is the value of procedure.
            
            
    • 
          
  • m is the value in the register. 
    • 
        

      

      

        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"