INTOUCH® 4GL
A Guide to the INTOUCH Language
Previous Contents Index

Checking the Output

To see what the COBOL_TEST.DEF file looks like, you can:

  1. Get into INTOUCH by entering INTOUCH
  2. Enter CALL SETUP to activate the SETUP routine.
  3. Answer the following prompts:
    • Structure name : COBOL_TEST
    • Database engine: RMS
    • Dataset : COBOL_TEST
    • Data dictionary: COBOL_TEST

    After the prompts are answered, a COBOL_TEST.STR file is created.
  4. Use the arrow keys to select the Show menu option and the Brief field display option

The following definition listing is created: 


11-Apr-1996              Definitions for: COBOL_TEST.DEF               Page:   1 
 
Field Name       Description      First  Length  Occurs  Last  Dtype  Print Mask 
---------------- ---------------- -----  ------  ------ -----  -----  ---------- 
TEST_REC         Test rec             1     115      1    115  CH     none 
      Semantics  : UC 
 
CODE             Code                 1       1      1      1  CH     none 
      Semantics  : UC 
 
DESC             Desc                 2      20      1     21  CH     none 
      Semantics  : UC 
 
AMOUNT           Amount              22       4      1     25  IN     none 
      Semantics  : NUM:2, RJ, ZF 
 
TBL_A1           Tbl a1              26      30      1     55  CH     none 
      Semantics  : NUM, RJ, ZF 
 
TBL_CODE_A1      Tbl code a1         26       5      1     30  CH     none 
      Semantics  : UC 
 
TBL_DESC_A1      Tbl desc a1         31      25      1     55  CH     none 
      Semantics  : UC 
 
TBL_A2           Tbl a2              56      30      1     85  CH     none 
      Semantics  : NUM, RJ, ZF 
 
TBL_CODE_A2      Tbl code a2         56       5      1     60  CH     none 
      Semantics  : UC 
 
TBL_DESC_A2      Tbl desc a2         61      25      1     85  CH     none 
      Semantics  : UC 
 
TBL_A3           Tbl a3              86      30      1    115  CH     none 
      Semantics  : NUM, RJ, ZF 
 
TBL_CODE_A3      Tbl code a3         86       5      1     90  CH     none 
      Semantics  : UC 
 
TBL_DESC_A3      Tbl desc a3         91      25      1    115  CH     none 
      Semantics  : UC

Chapter 17
INTOUCH Running Under OpenVMS

17.1 File Specifications

Every file has a file specification. The file specification is used to access the file. In INTOUCH, a legal file specification looks like this:

node::device:[directory]filename.ext;version

When you use a file name in an INTOUCH statement or command, it must be given as a string expression. If the file name is given as a constant, it must be enclosed in quotes. For example:

OLD 'ACCOUNT'

You can specify any legal OpenVMS file specification with INTOUCH. Simply name the file according to the rules described in the Command Language and DCL User's Guide of the OpenVMS documentation set.

Note
The default extension for INTOUCH programs is .INT. The default for include files is .INC.

Chapter 18
Multisessions in INTOUCH

18.1 PASS Option and Statements

INTOUCH now has a multisessions feature. That is, you can switch between INTOUCH sessions. A PASS option and several statements have been created for the multisessions feature. The option and statements are:

PASS SESSION: string_expr

ASK SYSTEM: SESSIONS string_var

ASK SYSTEM: SESSION string_var

SET SYSTEM: SESSION string_var

Using the PASS SESSION statement, multiple INTOUCH 4GL sessions can be started. The user can then switch between sessions using two keystrokes --- a "session" keystroke followed by an "action" keystroke.

There are two types of sessions. The PARENT session is the session that does the "PASS SESSION". The CHILD sessions are the sessions created by the PARENT session when it uses the PASS SESSION statement.

By default, it is assumed that the PARENT session will present a menu of CHILD applications to run, and that the user will normally want to switch only between CHILD sessions --- switching to the PARENT session only when they want to start up another CHILD application or exit.

By default the tick key ("`" --- the key next to the "1" on the far left of the keyboard) is used to switch from one session to the next. A "`1" will switch to the first CHILD session, "`2" to the second CHILD session and so on. Pressing "`0" will switch back to the PARENT session. Pressing the "`" twice in a row will switch to the next CHILD session.

The session switching keystrokes can be overridden using the statement: 


 
        SET WINDOW KEYSTROKE str_expr1: VALUE str_expr2

Example: 


        SET WINDOW KEYSTROKE '&': VALUE '_session,_child'

Pressing "&&" would switch between CHILD sessions.

Example: 


        SET WINDOW KEYSTROKE "&": VALUE '_session'

Pressing "&&" would switch between both PARENT and CHILD sessions.

18.1.1 PASS Option - Format


        PASS SESSION: string_expr

Example: 


        PASS SESSION: 'intouch/image payroll' 
        PRINT _STRING 
        1

This was session number 1.

Note
The passed COMMAND MUST end up running an INTOUCH 4GL application. Only INTOUCH 4GL applications will know how to switch between sessions.

The PARENT session is the session that executes the "PASS SESSION: ..." statements. Typically, this would be some kind of selection menu used to launch applications. If a CHILD session tries to do a "PASS SESSION", an exception (-11002) is given.

Each "PASS SESSION: ..." creates a CHILD session. The session number of the child is available in _STRING directly after the "PASS SESSION: ..." completes.

When a CHILD session ends, it will automatically switch to the PARENT session. When the PARENT session ends, all CHILD sessions are automatically terminated as well.

18.1.2 Sessions Under Program Control --- ASK SYSTEM

The PARENT session is always session number 0 (zero). CHILD session numbers are assigned as each "PASS SESSION: xxx" is executed.

To get a a comma separated list of active sessions, enter: 


        ASK SYSTEM: SESSIONS string_var

Example: 


        ASK SYSTEM: SESSIONS a$ 
        PRINT a$ 
        0,2,3,5

The PARENT session (number 0) is always active. In the above example, sessions 2, 3 and 5 are also active.

To get the session number for THIS SESSION, enter: 


        ASK SYSTEM: SESSION string_var

Example: 


        ASK SYSTEM: SESSION a$ 
        PRINT a$ 
        2

In this example, we are the 2nd CHILD session.

The ASK SYSTEM statements can be used to alter the behavior of an application based on whether it is a PARENT or a CHILD session.

18.1.3 Sessions Under Program Control --- SET SYSTEM

An application can switch between sessions under program control: 


        SET SYSTEM: SESSION string_var

For example, to switch back to the PARENT session: 


        SET SYSTEM: SESSION '0'

To switch to the 2nd CHILD session: 


        SET SYSTEM: SESSION '2'

18.2 Sample Program

The following is a short program example that shows how to use INTOUCH multisessions: 


        1000    clear 
                menu$ = '%title "INTOUCH Application Menu", guide,maintain,%bar,exit' 
                set window keystroke '&': value '_session,_child' 
                guide_ses$ = '' 
                maintain_ses$ = '' 
                do 
                  line input menu menu$: choice$ 
                  if _exit then exit do 
                  select case choice$ 
                  case 'GUIDE' 
                    when exception in 
                      set system: session guide_ses$ 
                    use 
                      pass session: 'guide' 
                      guide_ses$ = _string 
                    end when 
                  case 'MAINTAIN' 
                    when exception in 
                      set system: session maintain_ses$ 
                    use 
                      pass session: 'maintain' 
                      maintain_ses$ = _string 
                    end when 
                  end select 
                loop 
        9999    end

Appendix A
Built-in Functions

INTOUCH has numerous built-in functions. This appendix describes the system and other built-in functions.

A.1 System Functions

The following functions return information about the system and user actions:

_BACK

Returns a TRUE or FALSE value. TRUE if the backslash key was pressed at the last prompt.

_CHANNEL

Returns the next available channel number. 


        10  out_ch = _CHANNEL 
            OPEN #out_ch: NAME 'sys$scratch:test.lis' 
            PRINT #out_ch: 'This is a test' 
            CLOSE #out_ch 
        20  END

_DEBUG

Returns a TRUE or FALSE value. TRUE if DEBUG is on. FALSE if DEBUG is off.

_EXIT

Returns a TRUE or FALSE value. TRUE if EXIT was entered at the last prompt.

_EXTRACTED

Tells how many records were extracted in the last extract. 


        10  OPEN STRUCTURE cl: NAME 'tti_run:client' 
        20  EXTRACT STRUCTURE cl 
        30    INCLUDE cl(state) = 'CA' 
        40  END EXTRACT 
        50  PRINT 'Number of California clients:'; _EXTRACTED 
        60  END

_HELP

Returns a TRUE or FALSE value. TRUE if HELP or a question mark (?) was entered or the [Help] key is pressed at the last prompt.

_HELP should be checked before _BACK and/or _EXIT because, in some cases, all three are set on. For example, if "EXIT" is the default and the [Help] key is pressed, both _HELP and _EXIT are set on.

_INTEGER

Sometimes when the user does a CALL, an integer value is returned as a result of the CALL. _INTEGER returns any resulting integer data. 


        10  LIBRARY 'LIBRTL' 
        20  CALL LIB$ICHAR('Q') 
        30  PRINT 'The integer value of "Q" is: '; _INTEGER 
        40  END

_REAL

Some routines return a real value as the result of the CALL. The _REAL function returns any resulting real data. 


        10  LIBRARY 'MTHRTL' 
        20  CALL MTH$ALOG(45.3) 
        30  PRINT 'The log is:'; _REAL 
        40  END

_REPLY

Returns the user's reply to the last prompt. The reply is returned as a string.

_STATUS

Returns the value given to INTOUCH by the operating system, for the last operating system request. This function is useful when debugging system level errors. The _STATUS function is often used with the SYSTEXT$ function.

_STRING

Upon the completion of an INPUT MENU statement, the concept _STRING contains the menu path taken by the user when selecting the menu item. (i.e. "#2;#3" means the 3rd item of the 2nd submenu.)

_TERMINATOR

The _TERMINATOR function returns the name of the key that terminated the last INPUT statement. The values returned are:
UP Up arrow
DOWN Down arrow
RETURN Return
FIND Find (find line, word)
INS Insert
SEL Select
PREV Prev Screen
NEXT Next Screen
REM Remove
HELP Help
DO Do

PF1, PF2, PF3, PF4

KPO, KP1, KP2, KP3, KP4, KP5, KP6, KP7, KP8, KP9, MIN, COM, ENT, PER

F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, HELP, DO, F17, F18, F19, F20

A.2 Other Functions

The other non-system functions are:

ABS(num_expr)

ABS returns the absolute value of a specified numeric expression.

ACOS(num_expr)

ACOS(x) returns the angle whose COS is x. The angle is returned in radians.

ANGLE(num_expr, num_expr)

Given X and Y coordinates, returns the angle from 0,0. The angle is returned in radians.

ASCII(str_expr)

The ASCII function returns the decimal ASCII value of a string's first character. It is returned as an integer.

ASIN(num_expr)

ASIN(x) returns the angle whose SIN is x. The angle is returned in radians.

ATN(num_expr)

ATN returns the angle, in radians, of a specified tangent.

CEIL(num_expr)

CEIL(x) returns the ceiling of x. That is, the smallest integer that is not less than x.

CHANGE$(str_expr1, str_expr2, str_expr3)

CHANGE$ changes specified characters in str_expr1. str_expr1 is the source string. str_expr2 contains the target characters, and str_expr3 specifies the substitution characters. CHANGE$ returns the changed string.

CHANGE$ searches for the target characters within the source string and replaces these characters with the substitution characters. The substitution characters are mapped onto the target characters. 


        10  LET a$ = 'bdbdbdbd' 
        20  LET b$ = 'b' 
        30  LET c$ = 'c' 
        40  LET changed$ = CHANGE$(a$, b$, c$) 
        50  PRINT a$ 
        60  PRINT changed$ 
        70  END 
 
        RNH 
        bdbdbdbd 
        cdcdcdcd

CHARSET$[(str_expr)]

Returns the character set specified. The optional string expression can be used to specify the character set to return. The available character sets are:
UCASE all upper-case letters (A-Z)
LCASE all lower-case letters (a-z)
CONTROL all control characters (ASCII 0-31)
ASCII the ASCII character set, in order (0-255)

ASCII is the default character set for CHARSET$. 


        10  LINE INPUT 'Enter your text': text$ 
        20  ! Change upper-case to lower-case 
            ct$ = CHANGE$(text$, & 
                 CHARSET$('UCASE'), & 
                 CHARSET$('LCASE')) 
            PRINT 'Lower-case version is:'; ct$ 
        30  END

CHR$(int_expr1[, int_expr2])

CHR$ returns a string with the specified ASCII value (int_expr1) repeated the specified number of times (int_expr2). If no count is specified, a default count of one is used.

COMPARE(str_expr1, str_expr2)

The COMPARE function compares two strings and returns a numeric value ranging from 0 (no match) to 100 (an exact match). 


        10  options$ = 'LEFT,RIGHT,UP,DOWN' 
            best = 0 
            best$ = '' 
            INPUT 'Enter an option': usr_opt$ 
        20  FOR idx = 1 TO ELEMENTS(options$) 
              opt$ = ELEMENT$(options$, idx) 
              score = COMPARE(opt$, usr_opt$) 
              IF  score > best  THEN 
                best = score 
                best$ = opt$ 
              END IF 
            NEXT idx 
        30  SELECT CASE best 
            CASE 0 
              PRINT 'Unknown option: '; usr_opt$ 
            CASE 100 
              PRINT 'Option okay, it was: '; usr_opt$ 
            CASE ELSE 
              PRINT 'Misspelled option: '; usr_opt$ 
              PRINT USING 'Did you mean ? (## percent)': best$, best 
            END SELECT 
        40  END 
 
       RNH 
       Enter an option? dwn 
       Misspelled option: dwn 
       Did you mean DOWN (92 percent)

CONVERT(str_expr)

Given a string containing a mapped integer, this function returns the integer value. 


        10  a$ = 'AB' 
            b = CONVERT(a$) 
        20  END 
 
        RNH 
        16961

CONVERT$(int_expr1 [[, int_expr2], int_expr3])

Given an integer (int_expr1) and an optional length (int_expr2), which defaults to four, this function returns a string mapping of the integer.

If the optional data type (int_expr3) is 17, the returned string will be a packed floating (PF).

The following data types are supported:

Table A-1 CONVERT$ Function - Supported Data Types
Data Type Conversion Result
1 Integer (2 or 4 byte)
7 COBOL comp-3 (C3 packed decimal)
17 Packed floating (PF) 


        10  a$ = CONVERT$(16961) 
            PRINT a$ 
        20  END 
        
        RNH 
        AB

The CONVERT and CONVERT$ functions can be used in situations such as building segmented keys consisting of multiple data types.

Previous Next Contents Index